Difference between revisions of "API"

From OpenCellID wiki
Jump to: navigation, search
(→‎Example)
(→‎Payload)
Line 151: Line 151:
  
 
===Payload===
 
===Payload===
 +
?? Key=
 
mcc=<mcc>&mnc=<mnc>&lac=<lac>&cellid=<cellid>&fmt=<fmt>
 
mcc=<mcc>&mnc=<mnc>&lac=<lac>&cellid=<cellid>&fmt=<fmt>
  

Revision as of 10:21, 8 January 2014

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>&mcc=<mcc>&mnc=<mnc>&lac=<lac>&cellid=<cellid>&lat=<lat>&lon=<lon>

Where

Parameter Data type Description
<apiKey> string The id of the user submitting the measurement
<cellid> integer Cell tower id
<lat> double Latitude
<lon> double Longitude
<mcc> integer Mobile country code
<mnc> integer Mobile network code
<lac> integer Local area code

Response

On successfull insert return HTTP 200 with the string "cell 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&mcc=100&mnc=10&lac=11&cellid=12&lat=10.11&lon=11.12

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: 

lat,lon,mcc,mnc,lac,cellid
37.9872945,23.5773136,202,10,11100,13245414
37.9835,24.613223,202,10,11100,13245416
...

Column names recognized: lat, lon, mnc, mcc, lac, cellid, signal level, create_at, updated_at, speed, direction

Supplemented by the parameter key=<apiKey> as form POST field.

Where

Parameter Data type Description
<apiKey> string The id of the user submitting the measurements
<cellid> integer Cell tower id
<lat> double Latitude
<lon> double Longitude
<mcc> integer Mobile country code
<mnc> integer Mobile network code
<lac> integer Local area code

Response

On successful insert return HTTP 200.

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= mcc=<mcc>&mnc=<mnc>&lac=<lac>&cellid=<cellid>&fmt=<fmt>

Where

Parameter Data type Description
<cellid> integer Cell tower id
<mcc> integer Mobile country code
<mnc> integer Mobile network code
<lac> integer Local area code
<fmt> string (xml (default), txt/text) Response format. If an unknown format is specified, text is returned.

Response

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

<rsp stat="ok">
<cell lac="0" mcc="250" lat="50.5715642160311" cellId="29513" lon="25.2897075399231" nbSamples="57" mnc="99" range="6000"/>
</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?mcc=260&mnc=2&lac=10250&cellid=26511&fmt=xml

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

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

Where

Parameter Data type Description
<cellid> integer Cell tower id
<mcc> integer Mobile country code
<mnc> integer Mobile network code
<lac> integer Local area code

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

Example

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

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