API
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 | The id of 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" | 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 return HTTP 200 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 | 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" (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 return HTTP 200 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 return HTTP 200 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 |
Response
On successful request return HTTP 200 with XML of the following format:
<rsp stat="ok"> <cell lac="0" mcc="250" lat="50.5715642160311" lon="25.2897075399231" cellId="29513" nbSamples="57" mnc="99" range="6000"> <measure takenBy="1" lat="57.8240165710449" lon="28.00119972229" takenOn="Wed Apr 02 14:16:32 +0200 2008"/> <measure takenBy="1" lat="57.8240165710449" lon="28.00119972229" takenOn="Wed Apr 02 14:17:01 +0200 2008"/> <measure takenBy="1" lat="57.8240165710449" lon="28.00119972229" takenOn="Wed Apr 02 14:17:10 +0200 2008"/> <measure takenBy="1" lat="57.8240165710449" lon="28.00119972229" takenOn="Wed Apr 02 15:50:02 +0200 2008"/> <measure takenBy="772" lat="57.8240013122559" lon="28.00119972229" takenOn="Wed Jul 22 17:02:40 +0200 2009"/> <measure takenBy="772" lat="57.8240345622559" lon="28.0011345629" takenOn="Wed Jul 22 17:08:45 +0200 2009"/> <measure takenBy="2488" lat="3.42" lon="3.12" takenOn="Fri Feb 05 20:06:14 +0100 2010"/> <measure takenBy="805" lat="38.9687213" lon="-77.3410958" takenOn="Wed May 19 18:44:04 +0200 2010"/> <measure takenBy="805" lat="53.1366825" lon="25.2740863" takenOn="Thu May 20 01:16:42 +0200 2010"/> <measure takenBy="772" lat="41.892409" lon="12.700801" takenOn="Mon May 31 18:34:29 +0200 20/> <measure takenBy="772" lat="23.0" lon="38.0" takenOn="Sun Jan 02 19:47:14 +0100 2011"/> </cell> </rsp>
Business logic
The request is handled by de.enaikoon.gpssuite.web.measure.CellController.
Example
http://www.opencellid.org/cell/getMeasures?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>&fmt=<fmt>
Where
Parameter | Data type | Description |
---|---|---|
<apiKey> | string | API key assigned to the user |
<latmin> | double | Minimal bounding latitude |
<lonmin> | double | Minimal bounding longitude |
<latmax> | double | Maximal bounding latitude |
<lonmax> | double | Maximal bounding longitude |
<limit> (optional) | integer | A number defining the size of the returned list. Default is 200. Be careful, putting too big a number can generate an error |
<mcc> (optional) | integer | Mobile country code; If you want to restrict the result to a specific country |
<mnc> (optional) | integer | Mobile network code; If you want to restrict the result to a specific operator |
<lac> (optional) | integer | Local Area Code;If you want to restrict the result to a locale area code |
<fmt> (optional) | 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. |
Response
On successful request return HTTP 200 with the following output structures:
XML
<rsp stat="ok"> <cell lac="20371" cellId="1236" mcc="208" lat="48.906431085" lon="2.211114095" nbSamples="2" mnc="20"/> <cell lac="14340" cellId="4674446" mcc="208" lat="48.840991628822" lon="2.21148552373067" nbSamples="6" mnc="1"/> <cell lac="14340" cellId="4700495" mcc="208" lat="48.8411471061408" lon="2.21169734839367" nbSamples="6" mnc="1"/> <cell lac="318" cellId="3319" mcc="208" lat="48.8286924362183" lon="2.21202850341797" nbSamples="1" mnc="20"/> <cell lac="21700" cellId="24149" mcc="208" lat="48.8317127038461" lon="2.23276453461538" nbSamples="26" mnc="10"/> </rsp>
KML
<kml xmlns="http://earth.google.com/kml/2.1"> <Document> <name>OpenCellID Cells</name> <description>List of available cells</description> <Placemark> <name>Cell:1236 mcc:208 mnc:20 lac:20371</name> <description>Operator: Bouygues Telecom Nb Samples:2</description> <Point> <coordinates>2.211114095,48.906431085,0</coordinates> </Point> </Placemark> <Placemark> <name>Cell:4674446 mcc:208 mnc:1 lac:14340</name> <description>Operator: Orange Nb Samples:6</description> <Point> <coordinates>2.21148552373067,48.840991628822,0</coordinates> </Point> </Placemark>
CSV
lat,lon,mcc,mnc,lac,cellid,range,nbSamples 48.906431085,2.211114095,208,20,20371,1236,0,2 48.840991628822,2.21148552373067,208,1,14340,4674446,6000,6 48.8411471061408,2.21169734839367,208,1,14340,4700495,6000,6 48.8286924362183,2.21202850341797,208,20,318,3319,6000,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&fmt=csv
Deleting a measurement
POST request to
http://<WebServiceURL>/measure/delete/<id>
Parameters
<WebServiceURL>: the URL to the web service
<id>: ID of the measure to delete
Payload
key=<apiKey>
Where
Parameter | Data type | Description |
---|---|---|
<apiKey> | string | API key issued to user |
Response
On successful delete return HTTP 200.
Business logic
The request is handled by de.enaikoon.gpssuite.web.measure.MeasureController.
Example
www.opencellid.org/measure/delete/123456
where 123456 is an id of the measurement and apiKey is sent as post data. "id" isn't a payload because it is a part of url, it isn't a parameter.
Listing a user's measurements
GET request to
http://<WebServiceURL>/measure/list
Parameters
<WebServiceURL>: the URL to the web service
Payload
key=<apiKey>
Where
Parameter | Data type | Description |
---|---|---|
<apiKey> | string | API key issued to user |
Response
On successful request return HTTP 200 with XML of the following format:
<rsp> <measures total="2"> <measure lac="11100" mcc="1" lat="37.9872945" signal="" measured_at="" cellId="13245414" lon="23.5773136" id="67981657" mnc="1"/> <measure lac="11100" mcc="1" lat="37.9835" signal="" measured_at="" cellId="13245416" lon="24.613223" id="67981658" mnc="1"/> </measures> </rsp>
Business logic
The request is handled by de.enaikoon.gpssuite.web.measure.MeasureController.