API

From OpenCellID wiki
Revision as of 23:01, 4 January 2014 by Msemm (Talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

h1. V1 API

Description of API functions which originate from V1 of opencellids.org.

h2. 1. 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

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

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



h2. 2. 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

  • _<apiKey>_: string

User's API key

  • _<cellid>_: integer

Cell tower id

  • _<lat>_: double

Latitude

  • _<lon>_: double

Longitude

  • _<mcc>_: integer

Mobile country code

  • _<mnc>_: integer

Mobile network code

  • _<lac>_: integer

Locale area code

  • Response*

On successfull insert return HTTP 200.

  • Business logic*

The request is handled by @de.enaikoon.gpssuite.web.measure.NewMeasureController@.


h3. 3. 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:

  • _<cellid>_: integer

Cell tower id

  • _<mcc>_: integer

Mobile country code

  • _<mnc>_: integer

Mobile network code

  • _<lac>_: integer

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


h3. 4. 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

  • _<cellid>_: integer

Cell tower id

  • _<mcc>_: integer

Mobile country code

  • _<mnc>_: integer

Mobile network code

  • _<lac>_: integer

Locale area code

  • 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" 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>
</code>


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