API

API

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

API key

Most of the API calls require an API key. This API key can be obtained by registering here.
All uploaded data will be stored along with this API key. This offers many functions, including the deletion of data from users that provide incorrect data.
It also allows the identification of users that are violating the community server usage policy.

In the examples below "apiKey" is used for this parameter.

"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, the GSM network provider O2 in Germany provides GPS information along with the Cell ID information and software is able to extract this information for OpenCellID.
  
• in this case, new measurements for the cell are stored and shown on the map; however, 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>&act=<act>

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
<act>	string	Network access type; currently supported: Technology Type Description CDMA 1xRTT single-carrier Radio Transmission Technology (2.5G) CDMA CDMA (includes IS95A, IS95B) Code division multiple access CDMA eHRPD Enhanced High Rate Packet Data CDMA EVDO_0 Evolution-Data Optimized Revision 0 CDMA EDVO_A Evolution-Data Optimized Revision A CDMA EDVO_B Evolution-Data Optimized Revision B UMTS UMTS UMTS access UMTS HSPA+ High speed Packet Access UMTS HSDPA High Speed Downlink Packet Access UMTS HSUPA High Speed Uplink Packet Access UMTS HSPA = "HSDPA/HSUPA" = High Speed Packet Access (both downlink and uplink) LTE LTE Long term evolution iDEN iDEN Integrated Digital Enhanced Network GSM EDGE Enhanced Data Rates for GSM Evolution GSM GPRS GPRS access	yes

Response

Upon successful 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 a Mongo driver.
The user is deduced from the API key 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&act=GPRS

Uploading measurements from a 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,act
262,2,434,9200,9.436598,52.892139,4,1389472208000,5,0,0,GSM
262,2,434,9200,9.441658,52.890351,4,1389472225000,20,10,90,GSM
...

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

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
<act>	string	Network access type; currently supported: Technology Type Description CDMA 1xRTT single-carrier Radio Transmission Technology (2.5G) CDMA CDMA (includes IS95A, IS95B) Code division multiple access CDMA eHRPD Enhanced High Rate Packet Data CDMA EVDO_0 Evolution-Data Optimized Revision 0 CDMA EDVO_A Evolution-Data Optimized Revision A CDMA EDVO_B Evolution-Data Optimized Revision B UMTS UMTS UMTS access UMTS HSPA+ High speed Packet Access UMTS HSDPA High Speed Downlink Packet Access UMTS HSUPA High Speed Uplink Packet Access UMTS HSPA = "HSDPA/HSUPA" = High Speed Packet Access (both downlink and uplink) LTE LTE Long term evolution iDEN iDEN Integrated Digital Enhanced Network GSM EDGE Enhanced Data Rates for GSM Evolution GSM GPRS GPRS access	yes

Response

Upon 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.

cURL command

curl -F "key=APIKEY" -F "datafile=@/path/to/file/mydata.csv;type=text/plain" http://opencellid.org/measure/uploadCsv

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

Upon 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

For the total number of measurements used to compute the position of a cell, please use /cell/getMeasuresSize (described below).

Response

Upon successful request, HTTP 200 is returned with XML in 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

Upon successful request, HTTP 200 is returned with XML in 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 specify kml, xml or csv as output. Default is kml. In CSV type of output, a first line defining the content of the list.	yes

For the total number of cells in a specified area, please use /cell/getInAreaSize (described below).

Response

Upon 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

Upon successful request, HTTP 200 is returned with XML in 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

Upon successful deletion, 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 specify csv, xml or kml as output. Default is csv. In csv type of output, a first line defining the content of the list.	yes

For the total number of cells in a specified area, please use /measure/listSize (described below).

Response

Upon 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 measurements from a user

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

Upon successful request, HTTP 200 is returned with XML in 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