Difference between revisions of "API"

From OpenCellID wiki
Jump to: navigation, search
(→‎Business logic)
(→‎Business logic)
Line 183: Line 183:
  
 
===Business logic===
 
===Business logic===
−
The request is handled by @de.enaikoon.gpssuite.web.cell.CellController@.<br>
+
The request is handled by de.enaikoon.gpssuite.web.cell.CellController.<br>
 
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.
 
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.
  

Revision as of 00:48, 7 January 2014

This wiki page describes all available API functions.

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

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: 

<code class="xml">
<rsp stat="ok">
<cell lac="0" mcc="250" lat="50.5715642160311" cellId="29513" lon="25.2897075399231" nbSamples="57" mnc="99" range="6000"/>
</rsp>
</code>

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)  ??? 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> ???  ?? is this implemented?
<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

<code class="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>
</code>

KML

<code class="xml">
<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>
</kml>
</code>

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.

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 The id of the user who submitted the measurement

Response

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

<code class="xml">
<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>
</code>

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=101"