API
This wiki page describes all available API functions.
Contents
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> <syntaxhighlight> *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 <pre> http://<WebServiceURL>/cell/getInArea?key=<ApiKey>&BBOX=<latmin>,<lonmin>,<latmax>,<lonmax>&mcc=<mcc>&mnc=<mnc>&limit=<limit>&fmt=<fmt> </pre> *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 <pre><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></pre> KML <pre><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></pre> TXT <pre> 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 </pre> *Business logic* The request is handled by @de.enaikoon.gpssuite.web.measure.CellController@. ------------- h3. 6. Deleting a measure POST request to <pre> http://<WebServiceURL>/measure/delete/<id> </pre> *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 <pre> http://<WebServiceURL>/measure/list?key=<ApiKey> </pre> *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: <pre><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></pre> *Business logic* The request is handled by @de.enaikoon.gpssuite.web.measure.MeasureController@.