API

From OpenCellID wiki
Revision as of 23:25, 23 January 2014 by Msemm (Talk | contribs)

Jump to: navigation, search

This wiki page describes all available API functions.
Please contact Markus if you have any hints, suggestions for improvement or bugs to report.

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 violating the community server usage policy.

"changeable" attribute

The meaning of the "changeable" value returned by some methods is the following:
some cell positions in the database are precise. For example GSM network provider O2 in Germany provides GPS information along with the cell-id information and some software is able to extract this information for OpenCellID.
In this case new measurements for the cell are stored and shown on the map, but their GPS positions are not used for calculating the GPS position of the cell tower.

changeable=1:
the GPS position of the cell tower has been calculated from all available measurements

changeable=0:
the GPS position of the cell tower is precise; no measurements have been used to calculate it.

Filtering of data

The following filters are currently applied to all incoming data.
Wrong data is inserted into a database table with suspect data which can be re-examined at a later stage if required.

Parameter Rules
MCC must be known in the database
MCC must be in the range: (100..999)
MNC must be known in the database
MNC must be > 0
LAC must be > 0 and LAC!=2147483647
CID must be > 0 and LAC!=2147483647
longitude must be float (not integer)
longitude must be in the range: (-180,0) U (0,180)
longitude must be != 0
latitude must be float (not integer)
latitude must be in the range: (-90,0) U (0,90)
latitude must be != 0

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 (milliseconds since 1/1/1970 00:00:00 GMT)
- "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 (milliseconds since 1/1/1970 00:00:00 GMT)
- "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 imported. Y invalid measurements rejected.".

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


Getting 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