Difference between revisions of "API"

From OpenCellID wiki
Jump to: navigation, search
(→‎Parameters)
(→‎Response)
Line 228: Line 228:
 
===Response===
 
===Response===
 
On successful request return HTTP 200 with XML of the following format:
 
On successful request return HTTP 200 with XML of the following format:
−
<pre><code class="xml">
+
<code [xml]>
 
<rsp stat="ok">
 
<rsp stat="ok">
 
<cell lac="0" mcc="250" lat="50.5715642160311" lon="25.2897075399231" cellId="29513" nbSamples="57" mnc="99" range="6000">
 
<cell lac="0" mcc="250" lat="50.5715642160311" lon="25.2897075399231" cellId="29513" nbSamples="57" mnc="99" range="6000">
Line 244: Line 244:
 
</cell>
 
</cell>
 
</rsp>
 
</rsp>
−
</code></pre>
+
</code>
  
  

Revision as of 00:06, 5 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

Headers

Content-Type: application/x-www-form-urlencoded

Payload

key=<apikey>&cellid=<cellid>&lat=<lat>&lon=<lon>&mcc=<mcc>&mnc=<mnc>&lac=<lac>

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.

Uploading measurements from CSV file

POST request to 

http://<WebServiceURL>/measure/uploadCsv

Parameters

<WebServiceURL>_ The URL to the web service

Headers

Content-Type: multipart/form-data

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

POST request to 

http://<WebServiceURL>/cell/get

Parameters

<WebServiceURL> The URL to the web service

Headers

Content-Type: application/x-www-form-urlencoded

Payload

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

Getting the raw measures used to compute the position of a cell

GET/POST request to 

http://<WebServiceURL>/cell/getMeasures?cellid=<cellid>&mcc=<mcc>&mnc=<mnc>&lac=<lac>

Parameters

<WebServiceURL> The URL to the web service

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

h3. 5. Obtaining the list of cells in a specified area

GET request to 

http://<WebServiceURL>/cell/getInArea?key=<ApiKey>&BBOX=<latmin>,<lonmin>,<latmax>,<lonmax>&mcc=<mcc>&mnc=<mnc>&limit=<limit>&fmt=<fmt>
  • Parameters*
  • _<WebServiceURL>_

The URL to the web service

  • _<ApiKey>_

API key assigned to the user

  • _<latmin>_

Minimal bounding latitude

  • _<lonmin>_

Minimal bounding longitude

  • _<latmax>_

Maximal bounding latitude

  • _<lonmax>_

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)

If you want to retrict the result to a specific country

  • _<mnc>_ (optional)

If you want to restrict the result to a specific operator

  • _<fmt>_ (optional)

you can specifiy Kml, Xml or TXT as output. Default is Kml. Txt is CSV type of output, with 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>

TXT 

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

h3. 6. Deleting a measure

POST request to 

http://<WebServiceURL>/measure/delete/<id>
  • Parameters*
  • _<WebServiceURL>_

The URL to the web service

  • _<id>_

ID of the measure to delete

  • Headers*
  • Payload*

key=<ApiKey>

Where

  • _<ApiKey>_

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

h3. 7. Listing a user's measurements

GET request to 

http://<WebServiceURL>/measure/list?key=<ApiKey>
  • Parameters*
  • _<WebServiceURL>_

The URL to the web service

  • _<ApiKey>_: hex

API key issued to user

  • 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@.

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