Difference between revisions of "API"
(→Payload) |
(→Payload) |
||
Line 101: | Line 101: | ||
! scope="col" | Data type | ! scope="col" | Data type | ||
! scope="col" | Description | ! scope="col" | Description | ||
+ | ! scope="col" | Optional | ||
|- | |- | ||
| title="Parameter" | <lat> | | title="Parameter" | <lat> | ||
Line 129: | Line 130: | ||
| title="Data type" | integer | | title="Data type" | integer | ||
| title="Description" | Signal level | | title="Description" | Signal level | ||
+ | | title="Optional" | yes | ||
|- | |- | ||
| title="Parameter" | <create_at> | | title="Parameter" | <create_at> | ||
Line 137: | Line 139: | ||
| title="Data type" | Date (format: "yyyy-mm-dd hh:mm:ss") | | title="Data type" | Date (format: "yyyy-mm-dd hh:mm:ss") | ||
| title="Description" | Timestamp when the measurement was measured (in most cases the same as <create_at>) | | title="Description" | Timestamp when the measurement was measured (in most cases the same as <create_at>) | ||
+ | | title="Optional" | yes | ||
|- | |- | ||
| title="Parameter" | <speed> | | title="Parameter" | <speed> | ||
| title="Data type" | integer | | title="Data type" | integer | ||
| title="Description" | Speed when creating the measurement | | title="Description" | Speed when creating the measurement | ||
+ | | title="Optional" | yes | ||
|- | |- | ||
| title="Parameter" | <direction> | | title="Parameter" | <direction> | ||
| title="Data type" | integer | | title="Data type" | integer | ||
| title="Description" | Heading direction when creating the measurement. 0=north, 90=east | | title="Description" | Heading direction when creating the measurement. 0=north, 90=east | ||
+ | | title="Optional" | yes | ||
|} | |} | ||
Revision as of 15:46, 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,signal level,create_at,updated_at,speed,direction 37.9872945,23.5773136,202,10,11100,13245414,0,2014-01-01 01:02:03,2014-01-01 01:02:03,0,0 37.9835,24.613223,202,10,11100,13245416,0,2014-01-01 02:03:04,2014-01-01 02:03:04,0,0 ...
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, which is the user's API key.
Where
Parameter | Data type | Description | Optional |
---|---|---|---|
<lat> | double | Latitude | |
<lon> | double | Longitude | |
<mcc> | integer | Mobile country code | |
<mnc> | integer | Mobile network code | |
<lac> | integer | Local area code | |
<cellid> | integer | Cell tower id | |
<signal level> | integer | Signal level | yes |
<create_at> | Date (format: "yyyy-mm-dd hh:mm:ss") | Timestamp when the measurement was created (UTC) | |
<updated_at> | Date (format: "yyyy-mm-dd hh:mm:ss") | Timestamp when the measurement was measured (in most cases the same as <create_at>) | yes |
<speed> | integer | Speed when creating the measurement | yes |
<direction> | integer | Heading direction when creating the measurement. 0=north, 90=east | yes |
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.