Difference between revisions of "API"
(→Payload) |
(→Payload) |
||
| Line 188: | Line 188: | ||
| 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<br>(0=north, 90=east) |
| title="Optional" | yes | | title="Optional" | yes | ||
|} | |} | ||
Revision as of 09:30, 15 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>&lat=<lat>&lon=<lon>&mcc=<mcc>&mnc=<mnc>&lac=<lac>&cellid=<cellid>&signal=<signal>&measured_at=<measured_at>&rating=<rating>&speed=<speed>&direction=<direction>
Where
| Parameter | Data type | Description | Optional |
|---|---|---|---|
| <apiKey> | string | API key assigned to the user submitting the measurement | no |
| <lat> | double | Latitude | no |
| <lon> | double | Longitude | no |
| <mcc> | integer | Mobile country code | no |
| <mnc> | integer | Mobile network code | no |
| <lac> | integer | Local area code | no |
| <cellid> | integer | Cell tower id | no |
| <signal> | integer | Signal level | yes |
| <measured_at> | date | When the measurement was measured. Supported date formats: timestamp, "yyyy-MM-dd HH:mm:ss", "yyyyMMddHHmmss", "yyyy-MM-dd HH:mm:ss.SSSZ", "yyyy-MM-dd" | yes |
| <rating> | integer | GPS quality/accuracy information | yes |
| <speed> | integer | Speed when creating the measurement | yes |
| <direction> | integer | Heading direction when creating the measurement (0=north, 90=east) | yes |
Response
On successfull insert return HTTP 200 with the string "Your measurement has been 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
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:
mcc,mnc,lac,cellid,lon,lat,signal,measured_at,rating,speed,direction 262,2,434,9200,9.436598,52.892139,4,1389472208000,5,0,0 262,2,434,9200,9.441658,52.890351,4,1389472225000,20,10,90 ...
Column names recognized:
mcc, mnc, lac, cellid, lon, lat, signal, measured_at, rating, 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 | no |
| <lon> | double | Longitude | no |
| <mcc> | integer | Mobile country code | no |
| <mnc> | integer | Mobile network code | no |
| <lac> | integer | Local area code | no |
| <cellid> | integer | Cell tower id | no |
| <signal> | integer | Signal level | yes |
| <measured_at> | Date | When the measurement was measured. Supported date formats: - timestamp - "yyyy-MM-dd HH:mm:ss" - "yyyyMMddHHmmss" - "yyyy-MM-dd HH:mm:ss.SSSZ" - "yyyy-MM-dd" Time zone: UTC |
yes |
| <rating> | integer | GPS quality/accuracy information | 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 with the string "X unique measurements have been imported".
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=<apiKey>&mcc=<mcc>&mnc=<mnc>&lac=<lac>&cellid=<cellid>
Where
| Parameter | Data type | Description | Optional |
|---|---|---|---|
| <apiKey> | string | API key assigned to the user | no |
| <mcc> | integer | Mobile country code | no |
| <mnc> | integer | Mobile network code | no |
| <lac> | integer | Local area code | no |
| <cellid> | integer | Cell tower id | no |
Response
On successful request return HTTP 200 with XML of the following format:
<?xml version="1.0" encoding="UTF-8"?> <rsp stat="ok"> <cell lat="52.891587" lon="9.438145" mcc="262" mnc="2" lac="434" cellid="9200" averageSignalStrength="4" samples="13" changeable="1"/> </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?key=xxx&mcc=260&mnc=2&lac=10250&cellid=26511
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
key=<apiKey>&mcc=<mcc>&mnc=<mnc>&lac=<lac>&cellid=<cellid>&limit=<limit>&offset=<offset>
Where
| Parameter | Data type | Description | Optional |
|---|---|---|---|
| <apiKey> | string | API key assigned to the user | no |
| <mcc> | integer | Mobile country code | no |
| <mnc> | integer | Mobile network code | no |
| <lac> | integer | Local area code | no |
| <cellid> | integer | Cell tower id | no |
| <limit> | integer | A number defining max size of the returned list. Default and max value is 1000. | yes |
| <offset> | integer | The field says to skip that many measurements before beginning to return measurements. Default is 0. | yes |
In order to know the number of all measurements used to compute the position of a cell, please use /cell/getMeasuresSize (described below).
Response
On successful request return HTTP 200 with XML of the following format:
<?xml version="1.0" encoding="UTF-8"?> <rsp stat="ok"> <cell lon="9.439112000000002" lat="52.891242" mcc="262" mnc="2" lac="434" cellid="9200" range="0" averageSignalStrength="4" samples="3"> <measure id="52d3db7ccd214d36357b9fee" lat="52.891501" lon="9.438351" mcc="262" mnc="2" lac="434" cellid="9200" created_at="1389614776127" measured_at="1389477214000" signal="4" rating="10" speed="20" direction="90"/> <measure id="52d3db7ccd214d36357b9ff2" lat="52.890977" lon="9.439841" mcc="262" mnc="2" lac="434" cellid="9200" created_at="1389614776134" measured_at="1389477219000" signal="4" rating="0" speed="0" direction="0"/> <measure id="52d3db7ccd214d36357b9ff6" lat="52.890351" lon="9.441658" mcc="262" mnc="2" lac="434" cellid="9200" created_at="1389614776138" measured_at="1389477225000" signal="4" rating="0" speed="0" direction="0"/> </cell> </rsp>
Business logic
The request is handled by de.enaikoon.gpssuite.web.measure.CellController.
Example
Getting the number of all measures used to compute the position of a cell
GET/POST request to
http://<WebServiceURL>/cell/getMeasuresSize
Parameters
<WebServiceURL>: the URL to the web service
Payload
key=<apiKey>&mcc=<mcc>&mnc=<mnc>&lac=<lac>&cellid=<cellid>
Where
| Parameter | Data type | Description | Optional |
|---|---|---|---|
| <apiKey> | string | API key assigned to the user | no |
| <mcc> | integer | Mobile country code | no |
| <mnc> | integer | Mobile network code | no |
| <lac> | integer | Local area code | no |
| <cellid> | integer | Cell tower id | no |
Response
On successful request return HTTP 200 with XML of the following format:
<?xml version="1.0" encoding="UTF-8"?> <rsp stat="ok"> <measurements count="123"/> </rsp>
Business logic
The request is handled by de.enaikoon.gpssuite.web.measure.CellController.
Example
http://www.opencellid.org/cell/getMeasuresSize?key=xxx&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>&lac=<lac>&limit=<limit>&offset=<offset>&format=<format>
Where
| Parameter | Data type | Description | Optional |
|---|---|---|---|
| <apiKey> | string | API key assigned to the user | no |
| <latmin> | double | Minimal bounding latitude | no |
| <lonmin> | double | Minimal bounding longitude | no |
| <latmax> | double | Maximal bounding latitude | no |
| <lonmax> | double | Maximal bounding longitude | no |
| <mcc> | integer | Mobile country code; If you want to restrict the result to a specific country | yes |
| <mnc> | integer | Mobile network code; If you want to restrict the result to a specific operator | yes |
| <lac> | integer | Local Area Code;If you want to restrict the result to a locale area code | yes |
| <limit> | integer | A number defining maximum size of the returned list. Default and maximum value is 1000. | yes |
| <offset> | integer | The field says to skip that many cells before beginning to return cells. Default is 0. | yes |
| <format> | 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. | yes |
In order to know the number of all cells in a specified area, please use /cell/getInAreaSize (described below).
Response
On successful request return HTTP 200 with the following output structures:
XML
<?xml version="1.0" encoding="UTF-8"?> <rsp stat="ok"> <cell lat="52.9523755" lon="9.252112" mcc="262" mnc="2" lac="1434" cellid="17275" averageSignalStrength="3" samples="12" changeable="1"/> <cell lat="52.9463072" lon="9.258809" mcc="262" mnc="2" lac="1434" cellid="17276" averageSignalStrength="3" samples="11" changeable="1"/> <cell lat="52.9367185" lon="9.27343925" mcc="262" mnc="2" lac="1434" cellid="17272" averageSignalStrength="3" samples="12" changeable="1"/> <cell lat="52.9322157" lon="9.2847167" mcc="262" mnc="2" lac="1434" cellid="29322" averageSignalStrength="3" samples="5" changeable="1"/> </rsp>
KML (default)
<?xml version="1.0" encoding="UTF-8"?> <kml xmlns="http://earth.google.com/kml/2.1"> <Document> <name>OpenCellID Cells</name> <description>List of available cells</description> <Placemark><name></name><description><![CDATA[lat: <b>52.9523755</b><br/>lon: <b>9.252112</b><br/>mcc: <b>262</b><br/>mnc: <b>2</b><br/>lac: <b>1434</b><br/>cellid: <b>17275</b><br/>averageSignalStrength: <b>3</b><br/>samples: <b>12</b><br/>changeable: <b>1</b>]]></description><Point><coordinates>9.252112,52.9523755,0</coordinates></Point></Placemark> <Placemark><name></name><description><![CDATA[lat: <b>52.9463072</b><br/>lon: <b>9.258809</b><br/>mcc: <b>262</b><br/>mnc: <b>2</b><br/>lac: <b>1434</b><br/>cellid: <b>17276</b><br/>averageSignalStrength: <b>3</b><br/>samples: <b>11</b><br/>changeable: <b>1</b>]]></description><Point><coordinates>9.258809,52.9463072,0</coordinates></Point></Placemark> <Placemark><name></name><description><![CDATA[lat: <b>52.9367185</b><br/>lon: <b>9.27343925</b><br/>mcc: <b>262</b><br/>mnc: <b>2</b><br/>lac: <b>1434</b><br/>cellid: <b>17272</b><br/>averageSignalStrength: <b>3</b><br/>samples: <b>12</b><br/>changeable: <b>1</b>]]></description><Point><coordinates>9.27343925,52.9367185,0</coordinates></Point></Placemark> <Placemark><name></name><description><![CDATA[lat: <b>52.9322157</b><br/>lon: <b>9.2847167</b><br/>mcc: <b>262</b><br/>mnc: <b>2</b><br/>lac: <b>1434</b><br/>cellid: <b>29322</b><br/>averageSignalStrength: <b>3</b><br/>samples: <b>5</b><br/>changeable: <b>1</b>]]></description><Point><coordinates>9.2847167,52.9322157,0</coordinates></Point></Placemark> </Document> </kml>
CSV
lat,lon,mcc,mnc,lac,cellid,averageSignalStrength,samples,changeable 52.9523755,9.252112,262,2,1434,17275,3,12,1 52.9463072,9.258809,262,2,1434,17276,3,11,1 52.9367185,9.27343925,262,2,1434,17272,3,12,1 52.9322157,9.2847167,262,2,1434,29322,3,5,1
Business logic
The request is handled by de.enaikoon.gpssuite.web.measure.CellController.
Example
Getting the number of cells in a specified area
GET request to
http://<WebServiceURL>/cell/getInAreaSize
Parameters
<WebServiceURL>: the URL to the web service
Payload
key=<apiKey>&BBOX=<latmin>,<lonmin>,<latmax>,<lonmax>&mcc=<mcc>&mnc=<mnc>&lac=<lac>
Where
| Parameter | Data type | Description | Optional |
|---|---|---|---|
| <apiKey> | string | API key assigned to the user | no |
| <latmin> | double | Minimal bounding latitude | no |
| <lonmin> | double | Minimal bounding longitude | no |
| <latmax> | double | Maximal bounding latitude | no |
| <lonmax> | double | Maximal bounding longitude | no |
| <mcc> | integer | Mobile country code; If you want to restrict the result to a specific country | yes |
| <mnc> | integer | Mobile network code; If you want to restrict the result to a specific operator | yes |
| <lac> | integer | Local Area Code;If you want to restrict the result to a locale area code | yes |
Response
On successful request return HTTP 200 with XML of the following format:
XML
<?xml version="1.0" encoding="UTF-8"?> <rsp stat="ok"> <cells count="5"/> </rsp>
Business logic
The request is handled by de.enaikoon.gpssuite.web.measure.CellController.
Example
Deleting a measurement
POST request to
http://<WebServiceURL>/measure/delete
Parameters
<WebServiceURL>: the URL to the web service
<id>: ID of the measure to delete
Payload
key=<apiKey>&id=<id>
Where
| Parameter | Data type | Description | Optional |
|---|---|---|---|
| <apiKey> | string | API key assigned to the user | no |
| <id> | string | ID of the measure to delete | no |
Response
On successful delete return HTTP 200 with the string "Measurement with id=<id> has been deleted."
Business logic
The request is handled by de.enaikoon.gpssuite.web.measure.MeasureController.
Example
http://www.opencellid.org/measure/delete?key=xxx&id=123abc4567890123abcd1234
Listing a user's measurements
GET request to
http://<WebServiceURL>/measure/list
Parameters
<WebServiceURL>: the URL to the web service
Payload
key=<apikey>&limit=<limit>&offset=<offset>&format=<format>
Where
| Parameter | Data type | Description | Optional |
|---|---|---|---|
| <apiKey> | string | API key assigned to the user | no |
| <limit> | integer | A number defining maximum size of the returned list. Default and maximum value is 1000. | yes |
| <offset> | integer | The field says to skip that many measurements before beginning to return measurements. Default is 0. | yes |
| <format> | string | You can specifiy csv, xml or kml as output. Default is csv. In csv type of output, a first line defining the content of the list. | yes |
In order to know the number of all cells in a specified area, please use /measure/listSize (described below).
Response
On successful request return HTTP 200 with the following output structures:
CSV (default)
id,mcc,mnc,lac,cellid,lat,lon,created_at,measured_at,signal,rating,speed,direction 5213db7abcda4d36357b9f12,262,2,434,9200,52.892139,9.436598,1311615996112,1311512208000,4,10,10,90 5213db7abcda4d36357b9f15,262,2,1434,17271,52.96261,9.241319,1311615996122,1311511534000,3,20,11,90
XML
<?xml version="1.0" encoding="UTF-8"?> <rsp stat="ok"> <measure id="5213db7abcda4d36357b9f12" lat="52.892139" lon="9.436598" mcc="262" mnc="2" lac="434" cellid="9200" created_at="1311615996112" measured_at="1311512208000" signal="4" rating="10" speed="10" direction="90"/> <measure id="5213db7abcda4d36357b9f15" lat="52.96261" lon="9.241319" mcc="262" mnc="2" lac="1434" cellid="17271" created_at="1311615996122" measured_at="1311511534000" signal="3" rating="20" speed="11" direction="90"/> </rsp>
KML
<?xml version="1.0" encoding="UTF-8"?> <kml xmlns="http://www.opengis.net/kml/2.2"> <Document> <name>OpenCellID measurements</name> <description>List of user's measurements</description> <Placemark><name></name><description><![CDATA[id: <b>5213db7abcda4d36357b9f12</b><br/>mcc: <b>262</b><br/>mnc: <b>2</b><br/>lac: <b>434</b><br/>cellid: <b>9200</b><br/>lat: <b>52.892139</b><br/>lon: <b>9.436598</b><br/>created_at: <b>1311615996112</b><br/>measured_at: <b>1311512208000</b><br/>signal: <b>4</b><br/>rating: <b>3</b><br/>speed: <b>0</b><br/>direction: <b>0</b>]]></description><Point><coordinates>9.436598,52.892139,0</coordinates></Point></Placemark> <Placemark><name></name><description><![CDATA[id: <b>5213db7abcda4d36357b9f15</b><br/>mcc: <b>262</b><br/>mnc: <b>2</b><br/>lac: <b>1434</b><br/>cellid: <b>17271</b><br/>lat: <b>52.96261</b><br/>lon: <b>9.241319</b><br/>created_at: <b>1311615996112</b><br/>measured_at: <b>1311511534000</b><br/>signal: <b>3</b><br/>rating: <b>4</b><br/>speed: <b>0</b><br/>direction: <b>0</b>]]></description><Point><coordinates>9.241319,52.96261,0</coordinates></Point></Placemark> </Document> </kml>
Business logic
The request is handled by de.enaikoon.gpssuite.web.measure.MeasureController.
Example
http://www.opencellid.org/measure/list?key=xxx&limit=2&offset=128&format=xml
Getting the number of a user's measurements
GET/POST request to
http://<WebServiceURL>/measure/listSize
Parameters
<WebServiceURL>: the URL to the web service
Payload
key=<apiKey>
Where
| Parameter | Data type | Description | Optional |
|---|---|---|---|
| <apiKey> | string | API key assigned to the user | no |
Response
On successful request return HTTP 200 with XML of the following format:
<?xml version="1.0" encoding="UTF-8"?> <rsp stat="ok"> <measurements count="123"/> </rsp>
Business logic
The request is handled by de.enaikoon.gpssuite.web.measure.MeasureController.
