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