API

From OpenCellID wiki
Revision as of 10:48, 15 January 2014 by Msemm (Talk | contribs)

Jump to: navigation, search

This wiki page describes all available API functions.

apiKey

Most of the API calls require an API key. This API key can be obtained by registering here. All data uploaded will be stored along with this apiKey. This allows amongst others to delete data of users that provide wrong data. It also allows to identify users that are violate the community server usage policy.

Adding a single measurement

GET/POST request to 

http://<WebServiceURL>/measure/add

Parameters

<WebServiceURL>: the URL to the web service

Payload

key=<apikey>&lat=<lat>&lon=<lon>&mcc=<mcc>&mnc=<mnc>&lac=<lac>&cellid=<cellid>&signal=<signal>&measured_at=<measured_at>&rating=<rating>&speed=<speed>&direction=<direction>

Where

Parameter Data type Description Optional
<apiKey> string API key assigned to the user submitting the measurement no
<lat> double Latitude no
<lon> double Longitude no
<mcc> integer Mobile country code no
<mnc> integer Mobile network code no
<lac> integer Local area code no
<cellid> integer Cell tower id no
<signal> integer Signal level yes
<measured_at> date When the measurement was measured.
Supported date formats:
- timestamp
- "yyyy-MM-dd HH:mm:ss"
- "yyyyMMddHHmmss"
- "yyyy-MM-dd HH:mm:ss.SSSZ"
- "yyyy-MM-dd"
Time zone: UTC 		yes
<rating> integer GPS quality/accuracy information yes
<speed> integer Speed when creating the measurement yes
<direction> integer Heading direction when creating the measurement (0=north, 90=east) yes

Response

On successfull insert HTTP 200 is returned with the string "Your measurement has been inserted."

Business logic

The request is handled by de.enaikoon.gpssuite.web.measure.NewMeasureController.
The parameters are read into a map and then parsed into a de.enaikoon.m2m.gsmcellmanagment.model.CellMeasurement, and persisted by de.enaikoon.m2m.gsmcellmanagment.dao.mongodb.GsmCellDao (see the Spring common-business.xml configuration) which saves data via Mongo driver.
The user is deduced from apiKey which is a string unique to each user. User id is persisted as a field in the same object. Suspect measurements are saved into a special collection CellMeasurementSuspect.

Example

http://www.opencellid.org/measure/add?key=xxx&lat=10.11&lon=11.12&mcc=100&mnc=10&lac=11&cellid=12&rating=10&direction=90

Uploading measurements from CSV file

POST request to 

http://<WebServiceURL>/measure/uploadCsv

Parameters

<WebServiceURL>: the URL to the web service

Payload

CSV file of the following format: 

mcc,mnc,lac,cellid,lon,lat,signal,measured_at,rating,speed,direction
262,2,434,9200,9.436598,52.892139,4,1389472208000,5,0,0
262,2,434,9200,9.441658,52.890351,4,1389472225000,20,10,90
...

Column names recognized:
mcc, mnc, lac, cellid, lon, lat, signal, measured_at, rating, speed, direction

Supplemented by the parameter key=<apiKey> as form POST field, which is the user's API key.

Where

Parameter Data type Description Optional
<lat> double Latitude no
<lon> double Longitude no
<mcc> integer Mobile country code no
<mnc> integer Mobile network code no
<lac> integer Local area code no
<cellid> integer Cell tower id no
<signal> integer Signal level yes
<measured_at> Date When the measurement was measured.
Supported date formats:
- timestamp
- "yyyy-MM-dd HH:mm:ss"
- "yyyyMMddHHmmss"
- "yyyy-MM-dd HH:mm:ss.SSSZ"
- "yyyy-MM-dd"
Time zone: UTC 		yes
<rating> integer GPS quality/accuracy information yes
<speed> integer Speed when creating the measurement yes
<direction> integer Heading direction when creating the measurement
(0=north, 90=east) 		yes

Response

On successful insert HTTP 200 is returned with the string "X unique measurements have been imported".

Business logic

The request is handled by de.enaikoon.gpssuite.web.measure.NewMeasureController.

Getting cell position

GET/POST request to 

http://<WebServiceURL>/cell/get

Parameters

<WebServiceURL>: the URL to the web service

Headers

Content-Type: application/x-www-form-urlencoded

Payload

key=<apiKey>&mcc=<mcc>&mnc=<mnc>&lac=<lac>&cellid=<cellid>

Where

Parameter Data type Description Optional
<apiKey> string API key assigned to the user no
<mcc> integer Mobile country code no
<mnc> integer Mobile network code no
<lac> integer Local area code no
<cellid> integer Cell tower id no

Response

On successful request HTTP 200 is returned with XML of the following format: 

<?xml version="1.0" encoding="UTF-8"?>
<rsp stat="ok">
  <cell lat="52.891587" lon="9.438145" mcc="262" mnc="2" lac="434" cellid="9200" averageSignalStrength="4" samples="13" changeable="1"/>
</rsp>

Business logic

The request is handled by de.enaikoon.gpssuite.web.cell.CellController.
It uses de.enaikoon.m2m.gsmcellmanagment.dao.mongodb.GsmCellDao to calculate the average cell measurement, and builds an XML string to return to the user.

Example

http://www.opencellid.org/cell/get?key=xxx&mcc=260&mnc=2&lac=10250&cellid=26511

Getting the raw measurements used to compute the position of a cell

GET/POST request to 

http://<WebServiceURL>/cell/getMeasures

Parameters

<WebServiceURL>: the URL to the web service

Payload

key=<apiKey>&mcc=<mcc>&mnc=<mnc>&lac=<lac>&cellid=<cellid>&limit=<limit>&offset=<offset>

Where

Parameter Data type Description Optional
<apiKey> string API key assigned to the user no
<mcc> integer Mobile country code no
<mnc> integer Mobile network code no
<lac> integer Local area code no
<cellid> integer Cell tower id no
<limit> integer A number defining max size of the returned list.
Default and max value is 1000. 		yes
<offset> integer The field says to skip that many measurements before beginning to return measurements.
Default is 0. 		yes

In order to know the number of all measurements used to compute the position of a cell, please use /cell/getMeasuresSize (described below).

Response

On successful request HTTP 200 is returned with XML of the following format:

<?xml version="1.0" encoding="UTF-8"?>
<rsp stat="ok">
  <cell lon="9.439112000000002" 
        lat="52.891242" 
        mcc="262" 
        mnc="2" 
        lac="434" 
        cellid="9200" 
        range="0"
        averageSignalStrength="4" 
        samples="3">
    <measure id="52d3db7ccd214d36357b9fee" 
             lat="52.891501" 
             lon="9.438351"
             mcc="262" mnc="2"
             lac="434"
             cellid="9200"
             created_at="1389614776127"
             measured_at="1389477214000"
             signal="4"
             rating="10"
             speed="20"
             direction="90"/>
    <measure id="52d3db7ccd214d36357b9ff2"
             lat="52.890977"
             lon="9.439841"
             mcc="262"
             mnc="2"
             lac="434"
             cellid="9200"
             created_at="1389614776134"
             measured_at="1389477219000"
             signal="4"
             rating="0"
             speed="0"
             direction="0"/>
    <measure id="52d3db7ccd214d36357b9ff6"
             lat="52.890351"          
             lon="9.441658" 
             mcc="262" 
             mnc="2" 
             lac="434" 
             cellid="9200" 
             created_at="1389614776138" 
             measured_at="1389477225000" 
             signal="4" 
             rating="0" 
             speed="0" 
             direction="0"/>
  </cell>
</rsp>

Business logic

The request is handled by de.enaikoon.gpssuite.web.measure.CellController.

Example

http://www.opencellid.org/cell/getMeasures?key=xxx&mcc=260&mnc=2&lac=10250&cellid=26511&limit=10&offset=1

Getting the number of all measures used to compute the position of a cell

GET/POST request to 

http://<WebServiceURL>/cell/getMeasuresSize

Parameters

<WebServiceURL>: the URL to the web service

Payload

key=<apiKey>&mcc=<mcc>&mnc=<mnc>&lac=<lac>&cellid=<cellid>

Where

Parameter Data type Description Optional
<apiKey> string API key assigned to the user no
<mcc> integer Mobile country code no
<mnc> integer Mobile network code no
<lac> integer Local area code no
<cellid> integer Cell tower id no

Response

On successful request HTTP 200 is returned with XML of the following format:

<?xml version="1.0" encoding="UTF-8"?>
<rsp stat="ok">
  <measurements count="123"/>
</rsp>

Business logic

The request is handled by de.enaikoon.gpssuite.web.measure.CellController.

Example

http://www.opencellid.org/cell/getMeasuresSize?key=xxx&mcc=260&mnc=2&lac=10250&cellid=26511

Obtaining the list of cells in a specified area

GET request to 

http://<WebServiceURL>/cell/getInArea

Parameters

<WebServiceURL>: the URL to the web service

Payload

key=<apiKey>&BBOX=<latmin>,<lonmin>,<latmax>,<lonmax>&mcc=<mcc>&mnc=<mnc>&lac=<lac>&limit=<limit>&offset=<offset>&format=<format>

Where

Parameter Data type Description Optional
<apiKey> string API key assigned to the user no
<latmin> double Minimal bounding latitude no
<lonmin> double Minimal bounding longitude no
<latmax> double Maximal bounding latitude no
<lonmax> double Maximal bounding longitude no
<mcc> integer Mobile country code; If you want to restrict the result to a specific country yes
<mnc> integer Mobile network code; If you want to restrict the result to a specific operator yes
<lac> integer Local Area Code;If you want to restrict the result to a locale area code yes
<limit> integer A number defining maximum size of the returned list. Default and maximum value is 1000. yes
<offset> integer The field says to skip that many cells before beginning to return cells. Default is 0. yes
<format> string You can specifiy kml, xml or csv as output. Default is kml.
In CSV type of output, a first line defining the content of the list. 		yes

In order to know the number of all cells in a specified area, please use /cell/getInAreaSize (described below).

Response

On successful request HTTP 200 is returned with one of the following output structures:

XML

<?xml version="1.0" encoding="UTF-8"?>
<rsp stat="ok">
  <cell lat="52.9523755" 
        lon="9.252112" 
        mcc="262" 
        mnc="2" 
        lac="1434" 
        cellid="17275" 
        averageSignalStrength="3" 
        samples="12" 
        changeable="1"/>
  <cell lat="52.9463072" 
        lon="9.258809" 
        mcc="262" 
        mnc="2" 
        lac="1434" 
        cellid="17276" 
        averageSignalStrength="3" 
        samples="11" 
        changeable="1"/>
  <cell lat="52.9367185" 
        lon="9.27343925" 
        mcc="262" 
        mnc="2" 
        lac="1434" 
        cellid="17272" 
        averageSignalStrength="3"
        samples="12"
        changeable="1"/>
  <cell lat="52.9322157" 
        lon="9.2847167"
        mcc="262"
        mnc="2"
        lac="1434"
        cellid="29322"
        averageSignalStrength="3"
        samples="5"
        changeable="1"/>
</rsp>

KML (default)

<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://earth.google.com/kml/2.1">
  <Document>
    <name>OpenCellID Cells</name>
    <description>List of available cells</description>
    <Placemark>
      <name></name>
      <description><![CDATA[lat: <b>52.9523755</b><br/>
                            lon: <b>9.252112</b><br/>
                            mcc: <b>262</b><br/>
                            mnc: <b>2</b><br/>
                            lac: <b>1434</b><br/>
                            cellid: <b>17275</b><br/>
                            averageSignalStrength: <b>3</b><br/>
                            samples: <b>12</b><br/>
                            changeable: <b>1</b>]]>
      </description>
      <Point><coordinates>9.252112,52.9523755,0</coordinates></Point>
    </Placemark>
    <Placemark>
      <name></name>
      <description><![CDATA[lat: <b>52.9463072</b><br/>
                            lon: <b>9.258809</b><br/>
                            mcc: <b>262</b><br/>
                            mnc: <b>2</b><br/>
                            lac: <b>1434</b><br/>
                            cellid: <b>17276</b><br/>
                            averageSignalStrength: <b>3</b><br/>
                            samples: <b>11</b><br/>
                            changeable: <b>1</b>]]>
      </description>
      <Point><coordinates>9.258809,52.9463072,0</coordinates></Point>
    </Placemark>
    <Placemark>
      <name></name>
      <description><![CDATA[lat: <b>52.9367185</b><br/>
                            lon: <b>9.27343925</b><br/>
                            mcc: <b>262</b><br/>
                            mnc: <b>2</b><br/>
                            lac: <b>1434</b><br/>
                            cellid: <b>17272</b><br/>
                            averageSignalStrength: <b>3</b><br/>
                            samples: <b>12</b><br/>
                            changeable: <b>1</b>]]>
      </description>
      <Point><coordinates>9.27343925,52.9367185,0</coordinates></Point>
    </Placemark>
    <Placemark>
      <name></name>
      <description><![CDATA[lat: <b>52.9322157</b><br/>
                            lon: <b>9.2847167</b><br/>
                            mcc: <b>262</b><br/>
                            mnc: <b>2</b><br/>
                            lac: <b>1434</b><br/>
                            cellid: <b>29322</b><br/>
                            averageSignalStrength: <b>3</b><br/>
                            samples: <b>5</b><br/>
                            changeable: <b>1</b>]]>
      </description>
      <Point><coordinates>9.2847167,52.9322157,0</coordinates></Point>
    </Placemark>
  </Document>
</kml>

CSV

lat,lon,mcc,mnc,lac,cellid,averageSignalStrength,samples,changeable
52.9523755,9.252112,262,2,1434,17275,3,12,1
52.9463072,9.258809,262,2,1434,17276,3,11,1
52.9367185,9.27343925,262,2,1434,17272,3,12,1
52.9322157,9.2847167,262,2,1434,29322,3,5,1

Business logic

The request is handled by de.enaikoon.gpssuite.web.measure.CellController.

Example

http://www.opencellid.org/cell/getInArea?key=xxx&BBOX=52.0,21.0,52.5,21.5&mcc=260&mnc=2&lac=45070&limit=4&offset=16&format=kml

Getting the number of cells in a specified area

GET request to 

http://<WebServiceURL>/cell/getInAreaSize

Parameters

<WebServiceURL>: the URL to the web service

Payload

key=<apiKey>&BBOX=<latmin>,<lonmin>,<latmax>,<lonmax>&mcc=<mcc>&mnc=<mnc>&lac=<lac>

Where

Parameter Data type Description Optional
<apiKey> string API key assigned to the user no
<latmin> double Minimal bounding latitude no
<lonmin> double Minimal bounding longitude no
<latmax> double Maximal bounding latitude no
<lonmax> double Maximal bounding longitude no
<mcc> integer Mobile country code; If you want to restrict the result to a specific country yes
<mnc> integer Mobile network code; If you want to restrict the result to a specific operator yes
<lac> integer Local Area Code;If you want to restrict the result to a locale area code yes

Response

On successful request HTTP 200 is returned with XML of the following format:

XML

<?xml version="1.0" encoding="UTF-8"?>
<rsp stat="ok">
  <cells count="5"/>
</rsp>

Business logic

The request is handled by de.enaikoon.gpssuite.web.measure.CellController.

Example

http://www.opencellid.org/cell/getInAreaSize?key=xxx&BBOX=52.0,21.0,52.5,21.5&mcc=260&mnc=2&lac=45070

Deleting a measurement

POST request to 

http://<WebServiceURL>/measure/delete

Parameters

<WebServiceURL>: the URL to the web service

<id>: ID of the measure to delete

Payload

key=<apiKey>&id=<id>

Where

Parameter Data type Description Optional
<apiKey> string API key assigned to the user no
<id> string ID of the measure to delete no

Response

On successful delete HTTP 200 is returned with the string "Measurement with id=<id> has been deleted."

Business logic

The request is handled by de.enaikoon.gpssuite.web.measure.MeasureController.

Example

http://www.opencellid.org/measure/delete?key=xxx&id=123abc4567890123abcd1234

Listing a user's measurements

GET request to 

http://<WebServiceURL>/measure/list

Parameters

<WebServiceURL>: the URL to the web service

Payload

key=<apikey>&limit=<limit>&offset=<offset>&format=<format>

Where

Parameter Data type Description Optional
<apiKey> string API key assigned to the user no
<limit> integer A number defining maximum size of the returned list.
Default and maximum value is 1000. 		yes
<offset> integer The field says to skip that many measurements before beginning to return measurements.
Default is 0. 		yes
<format> string You can specifiy csv, xml or kml as output. Default is csv.
In csv type of output, a first line defining the content of the list. 		yes

In order to know the number of all cells in a specified area, please use /measure/listSize (described below).

Response

On successful request HTTP 200 is returned with one of the following output structures:

CSV (default)

id,mcc,mnc,lac,cellid,lat,lon,created_at,measured_at,signal,rating,speed,direction
5213db7abcda4d36357b9f12,262,2,434,9200,52.892139,9.436598,1311615996112,1311512208000,4,10,10,90
5213db7abcda4d36357b9f15,262,2,1434,17271,52.96261,9.241319,1311615996122,1311511534000,3,20,11,90

XML

<?xml version="1.0" encoding="UTF-8"?>
<rsp stat="ok">
  <measure id="5213db7abcda4d36357b9f12" 
           lat="52.892139" 
           lon="9.436598" 
           mcc="262"
           mnc="2"
           lac="434"
           cellid="9200"
           created_at="1311615996112"
           measured_at="1311512208000"
           signal="4"
           rating="10"
           speed="10"
           direction="90"/>
  <measure id="5213db7abcda4d36357b9f15"
           lat="52.96261"
           lon="9.241319"
           mcc="262"
           mnc="2"
           lac="1434"
           cellid="17271"
           created_at="1311615996122"
           measured_at="1311511534000"
           signal="3"
           rating="20"
           speed="11"
           direction="90"/>
</rsp>

KML

<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://www.opengis.net/kml/2.2">
  <Document>
    <name>OpenCellID measurements</name>
    <description>List of user's measurements</description>
    <Placemark>
      <name></name>
      <description><![CDATA[id: <b>5213db7abcda4d36357b9f12</b><br/>
                            mcc: <b>262</b><br/>
                            mnc: <b>2</b><br/>
                            lac: <b>434</b><br/>
                            cellid: <b>9200</b><br/>
                            lat: <b>52.892139</b><br/>
                            lon: <b>9.436598</b><br/>
                            created_at: <b>1311615996112</b><br/>
                            measured_at: <b>1311512208000</b><br/>
                            signal: <b>4</b><br/>
                            rating: <b>3</b><br/>
                            speed: <b>0</b><br/>
                            direction: <b>0</b>]]>
      </description>
      <Point><coordinates>9.436598,52.892139,0</coordinates></Point>
    </Placemark>
    <Placemark>
      <name></name>
      <description><![CDATA[id: <b>5213db7abcda4d36357b9f15</b><br/>
                            mcc: <b>262</b><br/>
                            mnc: <b>2</b><br/>
                            lac: <b>1434</b><br/>
                            cellid: <b>17271</b><br/>
                            lat: <b>52.96261</b><br/>
                            lon: <b>9.241319</b><br/>
                            created_at: <b>1311615996112</b><br/>
                            measured_at: <b>1311511534000</b><br/>
                            signal: <b>3</b><br/>
                            rating: <b>4</b><br/>
                            speed: <b>0</b><br/>
                            direction: <b>0</b>]]>
      </description>
      <Point><coordinates>9.241319,52.96261,0</coordinates></Point>
    </Placemark>
  </Document>
</kml>

Business logic

The request is handled by de.enaikoon.gpssuite.web.measure.MeasureController.

Example

http://www.opencellid.org/measure/list?key=xxx&limit=2&offset=128&format=xml

Getting the number of a user's measurements

GET/POST request to 

http://<WebServiceURL>/measure/listSize

Parameters

<WebServiceURL>: the URL to the web service

Payload

key=<apiKey>

Where

Parameter Data type Description Optional
<apiKey> string API key assigned to the user no

Response

On successful request HTTP 200 is returned with XML of the following format: 

<?xml version="1.0" encoding="UTF-8"?>
<rsp stat="ok">
  <measurements count="123"/>
</rsp>

Business logic

The request is handled by de.enaikoon.gpssuite.web.measure.MeasureController.

Example

http://www.opencellid.org/measure/listSize?key=xxx

Retrieved from "http://wiki.opencellid.org/index.php?title=API&oldid=527"