Difference between revisions of "API"

From OpenCellID wiki
Jump to: navigation, search
m (Updating NR range)
 
(419 intermediate revisions by 6 users not shown)
Line 1: Line 1:
This wiki page desccribes all available API functions.
+
{|align=right 
 +
|__TOC__
 +
|}
 +
<div style="font-size: 180%;"><span style="color:#505D89">'''API'''</span></div><br>
  
h2. 1. Adding a single measurement
+
This wiki page describes all available API functions.<br>
 +
Please contact <u>[mailto:[email protected] Unwired Labs]</u> if you have any suggestions for improvement or bugs to report.
 +
 
 +
==API key==
 +
Most of the API calls require an API key. This API key can be obtained by registering <u>[http://opencellid.org/#&action=database.requestForApiKey here]</u>.<br>
 +
All uploaded data will be stored along with this API key. This offers many functions, including the deletion of data from users that provide incorrect data.<br>
 +
It also allows the identification of users that are violating the community server usage policy.
 +
 
 +
Some smartphone apps also require an API key, for example the <u>[https://play.google.com/store/apps/details?id=info.zamojski.soft.towercollector Tower Collector]</u>.
 +
 
 +
For those who prefer contributing data to OpenCellID completely anonymously we recommend using the <u>[https://play.google.com/store/apps/details?id=de.enaikoon.android.inviu.opencellid OpenCellID client]</u> which does not require an API key for uploading data.
 +
 
 +
In the examples below "apiKey" is used as a place holder for this parameter.
 +
 
 +
=="changeable" attribute==
 +
The meaning of the "changeable" value returned by some methods is the following:<br>
 +
*some cell positions in the database are precise; for example, the GSM network provider O2 in Germany provides GPS information along with the Cell ID information and software is able to extract this information for OpenCellID.<br>
 +
*in this case, new measurements for the cell are stored and shown on the map; however, their GPS positions are not used for calculating the GPS position of the cell tower.
 +
 
 +
changeable=1:<br>
 +
the GPS position of the cell tower has been calculated from all available measurements
 +
 
 +
changeable=0:<br>
 +
the GPS position of the cell tower is precise; no measurements have been used to calculate it.
 +
 
 +
==Filtering of data==
 +
 
 +
The following filters are currently applied to all incoming data and decide if a measurement is suspicious or valid.<br>
 +
Suspect data is inserted into a database table with suspect data which can be re-examined at a later stage if required.
 +
 
 +
{| class="wikitable sortable" style="font-size: 85%; text-align: left;"
 +
|-
 +
! scope="col" | Parameter
 +
! scope="col" | Rules
 +
|-
 +
| title=Parameter | act
 +
| tilte="Rules" | must be one of supported type:<br>1xRTT, CDMA, eHRPD, IS95A, IS95B, EVDO_0, EVDO_A, EVDO_B, UMTS, HSPA+, HSDPA, HSUPA, HSPA, LTE, LTECATM, NR, NBIOT, EDGE, GPRS, GSM
 +
|-
 +
| title="Parameter" | MCC
 +
| title="Rules" | must be known in the database
 +
|-
 +
| title="Parameter" | MCC
 +
| title="Rules" | must be in the range of 100 to 999
 +
|-
 +
| title="Parameter" | MNC/SID
 +
| title="Rules" | must be known in the database
 +
|-
 +
| title="Parameter" | MNC
 +
| title="Rules" | must be in the range of 0 to 999 for GSM, UMTS, LTE, NR and NBIOT
 +
|-
 +
| title="Parameter" | MNC/SID
 +
| title="Rules" | must be in the range of 0 to 32767 for CDMA
 +
|-
 +
| title="Parameter" | LAC/TAC/NID
 +
| title="Rules" | must be in the range of 1 to 65535 for all radios except NR, 0 to 16777215 for NR.
 +
|-
 +
| title="Parameter" | CID
 +
| title="Rules" | must be in the range of 1 to 65535 for GSM
 +
|-
 +
| title="Parameter" | CID
 +
| title="Rules" | must be in the range of 1 to 268435455 for UMTS and LTE, 1 to 68719476735 for NR
 +
|-
 +
| title="Parameter" | CID/BID
 +
| title="Rules" | must be in the range 1 to 65535 for CDMA
 +
|-
 +
| title="Parameter" | longitude
 +
| title="Rules" | must be float (not integer)
 +
|-
 +
| title="Parameter" | longitude
 +
| title="Rules" | must be in the range: (-180,0) U (0,180)
 +
|-
 +
| title="Parameter" | longitude
 +
| title="Rules" | must be != 0
 +
|-
 +
| title="Parameter" | latitude
 +
| title="Rules" | must be float (not integer)
 +
|-
 +
| title="Parameter" | latitude
 +
| title="Rules" | must be in the range: (-90,0) U (0,90)
 +
|-
 +
| title="Parameter" | latitude
 +
| title="Rules" | must be != 0
 +
|}
 +
 
 +
{| class="wikitable sortable" style="font-size: 85%; text-align: left;"
 +
|-
 +
! scope="col" | Parameters
 +
! scope="col" | Rules
 +
|-
 +
| title=Parameter | MCC,MNC,LAC,CID,longitude,latitude
 +
| tilte="Rules" | must have unique coordinates for the cell
 +
|-
 +
| title="Parameter" | MCC,longitude,latitude
 +
| title="Rules" | must have coordinates in the home country
 +
|-
 +
| title="Parameter" | MCC,MNC,LAC,CID,longitude,latitude
 +
| title="Rules" | must be closer than 150 km away from the cell (only in case of precise cells)
 +
|}
 +
 
 +
The following filters are currently applied to optional fields in all incoming data.<br>
 +
If an optional field has invalid value, then only the value is rejected.
 +
 
 +
{| class="wikitable sortable" style="font-size: 85%; text-align: left;"
 +
|-
 +
! scope="col" | Parameter
 +
! scope="col" | Rules
 +
|-
 +
| title=Parameter | measured_at
 +
| tilte="Rules" | must be in one of supported date formats:<br>- timestamp (milliseconds since 1/1/1970 00:00:00 GMT),<br>- "yyyy-MM-dd HH:mm:ss",<br>- "yyyyMMddHHmmss",<br>- "yyyy-MM-dd HH:mm:ss.SSSZ",<br>- "yyyy-MM-dd"
 +
|-
 +
| title="Parameter" | signal
 +
| title="Rules" |
 +
{| class="wikitable sortable" style="font-size: 85%; text-align: left;"
 +
|-
 +
! scope="col" | Technology
 +
! scope="col" | Rules
 +
|-
 +
| title="Technology" | GSM
 +
| title="Rules" | RSSI in dBm in the range of -51 to -113 or ASU in the range of 0 to 31
 +
|-
 +
| title="Technology" | UMTS
 +
| title="Rules" | RSCP in dBm in the range of -25 to -121 or ASU in the range of -5 to 91
 +
|-
 +
| title="Technology" | LTE
 +
| title="Rules" | RSRP in dBm in the range of -45 to -137 or ASU in the range of 0 to 95
 +
|-
 +
| title="Technology" | NR
 +
| title="Rules" | RSRP in dBm in the range of -44 to -140 or ASU in the range of 0 to 97
 +
|-
 +
| title="Technology" | CDMA
 +
| title="Rules" | RSSI in dBm in the range of -75 to -100 or ASU in the range of 1 to 16
 +
|}
 +
|-
 +
| title="Parameter" | rating
 +
| title="Rules" | must be in metres in the range of 0 to 35000
 +
|-
 +
| title="Parameter" | speed
 +
| title="Rules" | must be in metres/second in the range of 0 to 300
 +
|-
 +
| title="Parameter" | direction
 +
| title="Rules" | must be in the range of 0 to 360
 +
|-
 +
| title="Parameter" | ta
 +
| title="Rules" | only for GSM and LTE; must be in the range of 0 to 63
 +
|-
 +
| title="Parameter" | psc
 +
| title="Rules" | only for UMTS; must be in the range of 0 to 511
 +
|-
 +
| title="Parameter" | pci
 +
| title="Rules" | only for LTE; must be in the range of 0 to 503
 +
|-
 +
| title="Parameter" | txp
 +
| title="Rules" | must be in the range of -200 to 100
 +
|-
 +
| title="Parameter" | tsrf
 +
| title="Rules" | must be in the range of -100 to 100
 +
|}
 +
 
 +
==Payload legend==
 +
 
 +
A typical payload for API requests and Measurement submissions may include some or all of the following parameters:
 +
 
 +
{| class="wikitable sortable" style="font-size: 85%; text-align: left;"
 +
|-
 +
! scope="col" | Parameter
 +
! scope="col" | Data type
 +
! scope="col" | Description
 +
! scope="col" | Optional
 +
|-
 +
| title="Parameter" | <apiKey>
 +
| title="Data type" | string
 +
| title="Description" | API key assigned to the user submitting the measurement
 +
| title="Optional" | no
 +
|-
 +
| title="Parameter" | <lat>
 +
| title="Data type" | double
 +
| title="Description" | Latitude
 +
| title="Optional" | no
 +
|-
 +
| title="Parameter" | <lon>
 +
| title="Data type" | double
 +
| title="Description" | Longitude
 +
| title="Optional" | no
 +
|-
 +
| title="Parameter" | <mcc>
 +
| title="Data type" | integer
 +
| title="Description" | Mobile country code
 +
| title="Optional" | no<br>(except CDMA)
 +
|-
 +
| title="Parameter" | <mnc>
 +
| title="Data type" | integer
 +
| title="Description" | Mobile network code or system identifier
 +
| title="Optional" | no<br>(except CDMA if sid is provided)
 +
|-
 +
| title="Parameter" | <lac>
 +
| title="Data type" | integer
 +
| title="Description" | Local area code, tracking area code or network id
 +
| title="Optional" | no<br>(except CDMA if nid is provided or LTE or NR if tac is provided)
 +
|-
 +
| title="Parameter" | <cellid>
 +
| title="Data type" | integer
 +
| title="Description" | Cell tower id or base station id
 +
| title="Optional" | no<br>(except CDMA if bid is provided)
 +
|-
 +
| title="Parameter" | <signal>
 +
| title="Data type" | integer
 +
| title="Description" | Signal level: either in dBm or as defined in TS 27.007 8.5; both is accepted.
 +
| title="Optional" | yes
 +
|-
 +
| title="Parameter" | <measured_at>
 +
| title="Data type" | date
 +
| title="Description" | When the measurement was measured.<br>Supported date formats:<br>- timestamp (milliseconds since 1/1/1970 00:00:00 GMT)<br>- "yyyy-MM-dd HH:mm:ss"<br>- "yyyyMMddHHmmss"<br>- "yyyy-MM-dd HH:mm:ss.SSSZ"<br>- "yyyy-MM-dd"<br>Time zone: UTC
 +
| title="Optional" | yes
 +
|-
 +
| title="Parameter" | <rating>
 +
| title="Data type" | double
 +
| title="Description" | GPS quality/accuracy information (metres)
 +
| title="Optional" | yes
 +
|-
 +
| title="Parameter" | <speed>
 +
| title="Data type" | double
 +
| title="Description" | Speed when creating the measurement, in metres/second
 +
| title="Optional" | yes
 +
|-
 +
| title="Parameter" | <direction>
 +
| title="Data type" | double
 +
| title="Description" | Heading direction when creating the measurement<br>(0=north, 90=east)
 +
| title="Optional" | yes
 +
|-
 +
| title="Parameter" | <act>
 +
| title="Data type" | string
 +
| title="Description" | Network access type; currently supported:<br>1xRTT, CDMA, eHRPD, IS95A, IS95B, EVDO_0, EVDO_A, EVDO_B, UMTS, HSPA+, HSDPA, HSUPA, HSPA, TDSCDMA, LTE, LTECATM, NR, NBIOT, EDGE, GPRS, GSM<br>
 +
{| class="wikitable sortable" style="font-size: 85%; text-align: left;"
 +
|-
 +
! scope="col" | Technology
 +
! scope="col" | Type
 +
! scope="col" | Description
 +
|-
 +
| title="Technology" | CDMA
 +
| title="Type" | 1xRTT
 +
| title="Description" | single-carrier Radio Transmission Technology (2.5G)
 +
|-
 +
| title="Technology" | CDMA
 +
| title="Type" | CDMA (includes IS95A, IS95B)
 +
| title="Description" | Code division multiple access
 +
|-
 +
| title="Technology" | CDMA
 +
| title="Type" | eHRPD
 +
| title="Description" | Enhanced High Rate Packet Data
 +
|-
 +
| title="Technology" | CDMA
 +
| title="Type" | EVDO_0
 +
| title="Description" | Evolution-Data Optimized Revision 0
 +
|-
 +
| title="Technology" | CDMA
 +
| title="Type" | EVDO_A
 +
| title="Description" | Evolution-Data Optimized Revision A
 +
|-
 +
| title="Technology" | CDMA
 +
| title="Type" | EVDO_B
 +
| title="Description" | Evolution-Data Optimized Revision B
 +
|-
 +
| title="Technology" | UMTS
 +
| title="Type" | UMTS
 +
| title="Description" | UMTS access
 +
|-
 +
| title="Technology" | UMTS
 +
| title="Type" | HSPA+
 +
| title="Description" | High speed Packet Access
 +
|-
 +
| title="Technology" | UMTS
 +
| title="Type" | HSDPA
 +
| title="Description" | High Speed Downlink Packet Access
 +
|-
 +
| title="Technology" | UMTS
 +
| title="Type" | HSUPA
 +
| title="Description" | High Speed Uplink Packet Access
 +
|-
 +
| title="Technology" | UMTS
 +
| title="Type" | HSPA
 +
| title="Description" | = "HSDPA/HSUPA" = High Speed Packet Access (both downlink and uplink)
 +
|-
 +
| title="Technology" | UMTS
 +
| title="Type" | TDSCDMA
 +
| title="Description" | = "TDSCDMA" = Time Division Synchronous Code Division Multiple Access (TD-SCDMA)
 +
|-
 +
| title="Technology" | LTE
 +
| title="Type" | LTE
 +
| title="Description" | Long term evolution
 +
|-
 +
| title="Technology" | LTE
 +
| title="Type" | LTECATM
 +
| title="Description" | Long term evolution CAT-M network
 +
|-
 +
| title="Technology" | NR
 +
| title="Type" | NR
 +
| title="Description" | New Radio (5G)
 +
|-
 +
| title="Technology" | NBIOT
 +
| title="Type" | NBIOT
 +
| title="Description" | Narrowband IoT
 +
|-
 +
| title="Technology" | iDEN
 +
| title="Type" | iDEN
 +
| title="Description" | Integrated Digital Enhanced Network
 +
|-
 +
| title="Technology" | GSM
 +
| title="Type" | EDGE
 +
| title="Description" | Enhanced Data Rates for GSM Evolution
 +
|-
 +
| title="Technology" | GSM
 +
| title="Type" | GPRS
 +
| title="Description" | GPRS access
 +
|}
 +
| title="Optional" | yes
 +
|-
 +
| title="Parameter" | <ta>
 +
| title="Data type" | integer
 +
| title="Description" | Timing advance; only for GSM and LTE
 +
| title="Optional" | yes
 +
|-
 +
| title="Parameter" | <psc>
 +
| title="Data type" | integer
 +
| title="Description" | Primary scrambling code; only for UMTS and TDSCDMA
 +
| title="Optional" | yes
 +
|-
 +
| title="Parameter" | <tac>
 +
| title="Data type" | integer
 +
| title="Description" | Tracking area code; only for LTE or NR
 +
| title="Optional" | yes
 +
|-
 +
| title="Parameter" | <pci>
 +
| title="Data type" | integer
 +
| title="Description" | Physical cell Id; only for LTE or NR
 +
| title="Optional" | yes
 +
|-
 +
| title="Parameter" | <sid>
 +
| title="Data type" | integer
 +
| title="Description" | System identifier; only for CDMA
 +
| title="Optional" | yes
 +
|-
 +
| title="Parameter" | <nid>
 +
| title="Data type" | integer
 +
| title="Description" | Network id; only for CDMA
 +
| title="Optional" | yes
 +
|-
 +
| title="Parameter" | <bid>
 +
| title="Data type" | integer
 +
| title="Description" | Base station id; only for CDMA
 +
| title="Optional" | yes
 +
|-
 +
| title="Parameter" | <devn>
 +
| title="Data type" | string
 +
| title="Description" | Device name as concatenated strings with the manufacturer and the model name; max 50 characters
 +
| title="Optional" | yes
 +
|-
 +
| title="Parameter" | <txp>
 +
| title="Data type" | integer
 +
| title="Description" | TX power in dBm
 +
| title="Optional" | yes
 +
|-
 +
| title="Parameter" | <tsrf>
 +
| title="Data type" | integer
 +
| title="Description" | Temperature in the RF module; in degrees Celsius; only with <txp> parameter
 +
| title="Optional" | yes
 +
|}
 +
 
 +
 
 +
==Error codes==
 +
 
 +
The following error codes might be returned by OpenCellID services:
 +
 
 +
{| class="wikitable sortable" style="font-size: 85%; text-align: left;"
 +
|-
 +
! scope="col" | Error code
 +
! scope="col" | HTTP code
 +
! scope="col" | Description
 +
|-
 +
| title="Error code" | 1
 +
| title="HTTP code" | 200
 +
| title="Description " | Cell not found
 +
|-
 +
| title="Error code" | 2
 +
| title="HTTP code" | 401
 +
| title="Description " | Invalid API key
 +
|-
 +
| title="Error code" | 3
 +
| title="HTTP code" | 400
 +
| title="Description " | Invalid input data
 +
|-
 +
| title="Error code" | 4
 +
| title="HTTP code" | 403
 +
| title="Description " | Your API key must be white listed in order to run this operation. This service is free of charge as long as your application contributes to the OpenCellID project. Should your application meet this requirement, please contact [email protected] for the authorisation of your API key.<br><br>For further details please visit:<br>http://wiki.opencellid.org/wiki/Commercial_users<br>http://wiki.opencellid.org/wiki/Request_whitelisting<br><br>You can alternatively download the entire database here:<br>http://opencellid.org/downloads/
 +
|-
 +
| title="Error code" | 5
 +
| title="HTTP code" | 500
 +
| title="Description " | Internal server error
 +
|-
 +
| title="Error code" | 6
 +
| title="HTTP code" | 503
 +
| title="Description " | Too many requests. Try later again.
 +
|-
 +
| title="Error code" | 7
 +
| title="HTTP code" | 429
 +
| title="Description " | Daily limit 1000 requests exceeded for your API key.<br><br>For further details please visit:<br>http://wiki.opencellid.org/wiki/Commercial_users<br><br>You can alternatively download the entire database here:<br>http://opencellid.org/downloads/
 +
|}
 +
 
 +
==Adding a single measurement==
  
 
GET/POST request to
 
GET/POST request to
Line 8: Line 418:
 
</pre>
 
</pre>
  
*Parameters*
+
===Parameters===
*  _<WebServiceURL>_
+
<WebServiceURL>: the URL to the web service
The URL to the web service
+
 
+
*Headers*
+
Content-Type: application/x-www-form-urlencoded
+
  
*Payload*
+
===Payload===
_key=<apikey>&cellid=<cellid>&lat=<lat>&lon=<lon>&mcc=<mcc>&mnc=<mnc>&lac=<lac>_
+
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>&act=<act>&ta=<ta>&psc=<psc>&tac=<tac>&pci=<pci>&sid=<sid>&nid=<nid>&bid=<bid>&devn=<devn>&txp=<txp>&tsrf=<tsrf>
  
 
Where
 
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*
+
===Response===
The request is handled by @[email protected] The parameters are read into a map and then parsed into a de.enaikoon.m2m.gsmcellmanagment.model.CellMeasurement, and persisted by @[email protected] (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.
+
Upon successful insert, HTTP 200 is returned with the string "Your measurement has been inserted."
  
 +
===Business logic===
 +
The request is handled by de.enaikoon.gpssuite.web.measure.NewMeasureController.<br>
 +
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 a Mongo driver.<br>
 +
The user is deduced from the API key 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. This collection currently cannot be accessed. The suspect data is rechecked every now and then after the filters have been updated in order to check if some initially supsect data can be recovered.
  
-------------
+
===Example===
 +
<u>http://opencellid.org/measure/add?key=xxx&lat=10.11&lon=11.12&mcc=100&mnc=10&lac=11&cellid=12&rating=10&direction=90&act=GPRS</u><br>
 +
<u>http://opencellid.org/measure/add?key=xxx&lat=10.11&lon=11.12&mcc=100&mnc=10&lac=11&cellid=12&rating=10.1&direction=90.3&speed=12.3&act=GPRS&ta=3</u><br>
 +
<u>http://opencellid.org/measure/add?key=xxx&lat=10.11&lon=11.12&mcc=100&mnc=10&lac=11&cellid=12&rating=10.1&direction=90.3&speed=12.3&act=HSPA+&psc=3</u><br>
 +
<u>http://opencellid.org/measure/add?key=xxx&lat=10.11&lon=11.12&mcc=100&mnc=10&lac=11&cellid=12&rating=10.1&direction=90.3&speed=12.3&act=LTE&pci=3</u><br>
 +
<u>http://opencellid.org/measure/add?key=xxx&lat=10.11&lon=11.12&mcc=100&mnc=10&tac=11&cellid=12&rating=10.1&direction=90.3&speed=12.3&act=LTE&pci=3</u><br>
 +
<u>http://opencellid.org/measure/add?key=xxx&lat=10.11&lon=11.12&mcc=100&mnc=10&lac=11&cellid=12&rating=10.1&direction=90.3&speed=12.3&act=1xRTT</u><br>
 +
<u>http://opencellid.org/measure/add?key=xxx&lat=10.11&lon=11.12&mcc=100&sid=10&nid=11&bid=12&rating=10.1&direction=90.3&speed=12.3&act=1xRTT</u><br>
 +
<u>http://opencellid.org/measure/add?key=xxx&lat=10.11&lon=11.12&sid=10&nid=11&bid=12&rating=10.1&direction=90.3&speed=12.3&act=eHRPD</u><br>
 +
<u>http://opencellid.org/measure/add?key=xxx&lat=10.11&lon=11.12&mcc=100&mnc=10&lac=11&cellid=12&act=GSM&devn=Samsung%20GT-S5830L&txp=-45&tsrf=22</u>
  
h2. 2. Uploading measurements from CSV file
+
===Time needed for processing newly uploaded measurements===
 +
After uploading new measurements to the OpenCellID community servers they are added to our waiting queues and processed in the background.
 +
We aim the real-time processing, but maximum time depends on traffic on OpenCellID servers. Current throughput of our servers is around 15000 measurements per second.
 +
 
 +
Measurements are processed in 3 steps:
 +
 
 +
# parsing and filtering raw data
 +
# updating measurement statistics and storing measurements in the database
 +
# updating existing cell towers information or adding new cell towers to the database
 +
 
 +
Our waiting queues for cell towers and for measurements are independent, so you can see your measurements in the OpenCellID database but related cell towers might be not updated yet. This means that if you upload a measurement of a cell tower that was not in the database before and the waiting queue for cell towers has some data to process, you have to expect some times (usually few minutes) until the queue delivers the newly uploaded cell tower information.
 +
 
 +
==Uploading measurements from a CSV file==
  
 
POST request to
 
POST request to
Line 50: Line 465:
 
</pre>
 
</pre>
  
*Parameters*
+
===Parameters===
*  _<WebServiceURL>_
+
<WebServiceURL>: the URL to the web service
The URL to the web service
+
 
+
*Headers*
+
Content-Type: multipart/form-data
+
  
*Payload*
+
===Payload===
 
CSV file of the following format:
 
CSV file of the following format:
 
<pre>
 
<pre>
lat,lon,mcc,mnc,lac,cellid
+
mcc,mnc,lac,cellid,lon,lat,signal,measured_at,rating,speed,direction,act,ta,psc,tac,pci,sid,nid,bid
37.9872945,23.5773136,202,10,11100,13245414
+
100,2,434,9200,9.436598,52.892139,4,1389472208000,5.4,0,0,GPRS,3,,,,,,
37.9835,24.613223,202,10,11100,13245416
+
100,2,434,9200,9.441658,52.890351,4,1389472225000,20.1,10.4,90.1,HSPA+,,4,,,,,
 +
100,2,434,9200,9.441658,52.890351,4,1389472225000,20.1,10.4,90.1,LTE,,,,4,,,
 +
100,2,,9200,9.441658,52.890351,4,1389472225000,20.1,10.4,90.1,LTE,,,434,4,,,
 +
100,2,432,9200,9.441658,52.890351,4,1389472225000,20.1,10.4,90.1,LTE,,,432,4,,,
 +
100,1234,432,9201,9.441658,52.890351,4,1389472225000,20.1,10.4,90.1,eHRPD,,,,,,,
 +
100,1234,432,9201,9.441658,52.890351,4,1389472225000,20.1,10.4,90.1,eHRPD,,,,,1234,432,9201
 +
100,,,,9.441658,52.890351,4,1389472225000,20.1,10.4,90.1,1xRTT,,,,,1234,432,9201
 +
,,,,9.441658,52.890351,4,1389472225000,20.1,10.4,90.1,eHRPD,,,,,1234,432,9201
 
...
 
...
 
</pre>
 
</pre>
Column names recognized:
+
Column names recognised:<br>
lat, lon, mnc, mcc, lac, cellid, signal level, create_at, updated_at, speed, direction
+
mcc, mnc, lac, cellid, lat, lon, signal, measured_at, rating, speed, direction, act, ta, psc, tac, pci, sid, nid, bid
  
Supplemented by the parameter _key=<apiKey>_  as form POST field.
+
Maximum file size:<br>
 +
2 MB; upload multiple files if you want to upload more data.
  
Where
+
Supplemented by the parameter ''key=<apiKey>'' as form POST field, which is the user's API key.
* _<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*
+
===Response===
The request is handled by @[email protected].
+
Upon successful insert, HTTP 200 is returned with the string "0,OK".
  
-------------
+
===Business logic===
 +
The request is handled by de.enaikoon.gpssuite.web.measure.NewMeasureController.
  
h3. 3. Getting cell position
+
===cURL command===
 +
<syntaxhighlight lang="bash">
 +
curl -F "key=apiKey" -F "[email protected]/path/to/file/mydata.csv;type=text/plain" http://opencellid.org/measure/uploadCsv
 +
</syntaxhighlight>
 +
 
 +
===Time needed for processing newly uploaded measurements===
 +
After uploading new measurements to the OpenCellID community servers they are added to our waiting queues and processed in the background.
 +
We aim the real-time processing, but maximum time depends on traffic on OpenCellID servers. Current throughput of our servers is around 15000 measurements per second.
 +
 
 +
Measurements are processed in 3 steps:
 +
 
 +
# parsing and filtering raw data
 +
# updating measurement statistics and storing measurements in the database
 +
# updating existing cell towers information or adding new cell towers to the database
 +
 
 +
Our waiting queues for cell towers and for measurements are independent, so you can see your measurements in the OpenCellID database but related cell towers might be not updated yet. This means that if you upload a measurement of a cell tower that was not in the database before and the waiting queue for cell towers has some data to process, you have to expect some times (usually few minutes) until the queue delivers the newly uploaded cell tower information.
 +
 
 +
===FAQ===
 +
<b>What does "optional" mean?</b><br>
 +
"optional" means that this field is not required in the csv file.<br>
 +
Minimal csv file looks as follows:<br>
 +
<pre>
 +
mcc,mnc,lac,cellid,lon,lat
 +
262,2,434,9200,9.436598,52.892139
 +
</pre>
 +
 
 +
<b>What does "Supplemented by the parameter key=<apiKey> as form POST field, which is the user's API key" mean?</b><br>
 +
This means that the user must send his data (apiKey and csv file) in the same way as from the following form:<br>
 +
<syntaxhighlight lang="html5">
 +
<form method="post" action="http://opencellid.org/measure/uploadCsv" enctype="multipart/form-data">
 +
  apiKey: <input type="text" name="key" />
 +
  CSV (max 2MB): <input type="file" name="datafile" />
 +
  <input type="submit" name="upload" value="Upload"/>
 +
</form>
 +
</syntaxhighlight>
 +
 
 +
<b>What does the following error mean?</b><br>
 +
<syntaxhighlight lang="xml">
 +
<?xml version="1.0" encoding="UTF-8"?>
 +
<rsp stat="fail"><err info="cell not found" code="1"/></rsp>
 +
</syntaxhighlight>
 +
 
 +
This error message means that no cell was found for the given user criteria (mcc-mnc-lac-cid combination was not found in database).
 +
 
 +
<b>Can I upload CDMA using mcc-mnc-lac-cellid parameters?</b><br>
 +
Yes, you can use mnc as sid, lac as nid and cellid as bid.
 +
 
 +
==Uploading measurements from a JSON file==
  
 
POST request to
 
POST request to
 +
<pre>
 +
http://<WebServiceURL>/measure/uploadJson
 +
</pre>
 +
 +
===Parameters===
 +
<WebServiceURL>: the URL to the web service
 +
 +
===Payload===
 +
JSON file (send in ''datafile'' parameter) of the following format:
 +
 +
<syntaxhighlight lang="javascript">
 +
{
 +
    "measurements": [
 +
        {
 +
            "lon": 9.436598,
 +
            "lat": 52.892139,
 +
            "mcc": 100,
 +
            "mnc": 2,
 +
            "lac": 434,
 +
            "cellid": 9200,
 +
            "measured_at": 1389472224000,
 +
            "signal": -80,
 +
            "rating": 5.4,
 +
            "speed": 2.32,
 +
            "direction": 93.22,
 +
            "act": "EDGE",
 +
            "ta": 3
 +
        },
 +
        {
 +
            "lon": 9.441658,
 +
            "lat": 52.890351,
 +
            "mcc": 100,
 +
            "mnc": 2,
 +
            "lac": 3,
 +
            "cellid": 9200,
 +
            "measured_at": 1389472225000,
 +
            "signal": -80,
 +
            "speed": 11.21,
 +
            "act": "HSDPA",
 +
            "psc": 2
 +
        },
 +
        {
 +
            "lon": 9.441658,
 +
            "lat": 52.890351,
 +
            "mcc": 100,
 +
            "mnc": 2,
 +
            "lac": 321,
 +
            "cellid": 9200,
 +
            "measured_at": 1389472226000,
 +
            "signal": -80,
 +
            "rating": 11.21,
 +
            "act": "LTE",
 +
            "pci": 2
 +
        },
 +
        {
 +
            "lon": 9.441658,
 +
            "lat": 52.890351,
 +
            "mcc": 100,
 +
            "mnc": 2,
 +
            "tac": 321,
 +
            "cellid": 9200,
 +
            "measured_at": 1389472227000,
 +
            "signal": -80,
 +
            "act": "LTE"
 +
        },
 +
        {
 +
            "lon": 9.441658,
 +
            "lat": 52.890351,
 +
            "mcc": 100,
 +
            "mnc": 12345,
 +
            "lac": 1,
 +
            "cellid": 2,
 +
            "measured_at": 1389472228000,
 +
            "signal": -80,
 +
            "act": "eHRPD"
 +
        },
 +
        {
 +
            "lon": 9.441658,
 +
            "lat": 52.890351,
 +
            "mcc": 100,
 +
            "sid": 12345,
 +
            "nid": 1,
 +
            "bid": 2,
 +
            "measured_at": 1389472229000,
 +
            "signal": -80,
 +
            "act": "EVDO_0"
 +
        }
 +
    ]
 +
}
 +
</syntaxhighlight>
 +
 +
Field names recognised:<br>
 +
mcc, mnc, lac, cellid, lat, lon, signal, measured_at, rating, speed, direction, act, ta, psc, tac, pci, sid, nid, bid
 +
 +
Maximum file size:<br>
 +
2 MB; upload multiple files if you want to upload more data.
 +
 +
Supplemented by the parameter ''key=<apiKey>'' as form POST field, which is the user's API key.
 +
 +
===Response===
 +
Upon successful insert, HTTP 200 is returned with ''application/json'' content type and following json document as a content: ''{"code":0,"status":"OK"}''
 +
 +
===Business logic===
 +
The request is handled by de.enaikoon.gpssuite.web.measure.NewMeasureController.
 +
 +
===cURL command===
 +
<syntaxhighlight lang="bash">
 +
curl -F "key=apiKey" -F "[email protected]/path/to/file/mydata.json;type=text/plain" http://opencellid.org/measure/uploadJson
 +
</syntaxhighlight>
 +
 +
===Time needed for processing newly uploaded measurements===
 +
After uploading new measurements to the OpenCellID community servers they are added to our waiting queues and processed in the background.
 +
We aim the real-time processing, but maximum time depends on traffic on OpenCellID servers. Current throughput of our servers is around 15000 measurements per second.
 +
 +
Measurements are processed in 3 steps:
 +
 +
# parsing and filtering raw data
 +
# updating measurement statistics and storing measurements in the database
 +
# updating existing cell towers information or adding new cell towers to the database
 +
 +
Our waiting queues for cell towers and for measurements are independent, so you can see your measurements in the OpenCellID database but related cell towers might be not updated yet. This means that if you upload a measurement of a cell tower that was not in the database before and the waiting queue for cell towers has some data to process, you have to expect some times (usually few minutes) until the queue delivers the newly uploaded cell tower information.
 +
 +
===FAQ===
 +
<b>What does "optional" mean?</b><br>
 +
"optional" means that this field is not required in the json file.<br>
 +
Minimal json file looks as follows:<br>
 +
<syntaxhighlight lang="javascript">
 +
{
 +
    "measurements": [
 +
        {
 +
            "lon": 9.436598,
 +
            "lat": 52.892139,
 +
            "mcc": 262,
 +
            "mnc": 2,
 +
            "lac": 434,
 +
            "cellid": 9200
 +
        }
 +
    ]
 +
}
 +
</syntaxhighlight>
 +
 +
<b>What does "Supplemented by the parameter key=<apiKey> as form POST field, which is the user's API key" mean?</b><br>
 +
This means that the user must send his data (apiKey and json file) in the same way as from the following form:<br>
 +
<syntaxhighlight lang="html5">
 +
<form method="post" action="http://opencellid.org/measure/uploadJson" enctype="multipart/form-data">
 +
  apiKey: <input type="text" name="key" />
 +
  JSON (max 2MB): <input type="file" name="datafile" />
 +
  <input type="submit" name="upload" value="Upload"/>
 +
</form>
 +
</syntaxhighlight>
 +
 +
<b>What does the following error mean?</b><br>
 +
<syntaxhighlight lang="xml">
 +
<?xml version="1.0" encoding="UTF-8"?>
 +
<rsp stat="fail"><err info="cell not found" code="1"/></rsp>
 +
</syntaxhighlight>
 +
 +
This error message means that no cell was found for the given user criteria (mcc-mnc-lac-cid combination was not found in database).
 +
 +
<b>Can I upload CDMA using mcc-mnc-lac-cellid parameters?</b><br>
 +
Yes, you can use mnc as sid, lac as nid and cellid as bid.
 +
 +
==Uploading measurements from CLF3 file==
 +
 +
POST request to
 +
<pre>
 +
http://<WebServiceURL>/measure/uploadClf
 +
</pre>
 +
 +
===Parameters===
 +
<WebServiceURL>: The URL to the web service
 +
 +
===Payload===
 +
CLF version 3.0 file (to be sent in datafile parameter) of the following format:
 +
<pre>
 +
//mcc+mnc;cellid;lac;rnc;lat;lon;ratio;data;rfu
 +
26202;07812;03101;0;45.894375;31.51312;0;City Square;0
 +
</pre>
 +
Columns are semicolon separated and have the following strict order:<br>
 +
mcc+mnc, lac, cellid, rnc, lat, lon, ratio, data, rfu
 +
 +
There is no header in CLF3 files.
 +
Therefore the columns must be provided in the order given above and all values must be there.<br>
 +
 +
You can add comments to CLF3 files.<br>
 +
Comments in CLF3 start with // and extend to the end of the physical line.
 +
 +
Maximum file size:<br>
 +
2 MB; upload multiple files if you want to upload more data.
 +
 +
Supplemented by the parameter key=<apiKey> as form POST field, which is the user's API key
 +
 +
{| class="wikitable sortable" style="font-size: 85%; text-align: left;"
 +
|-
 +
 +
Supported columns:
 +
! scope="col" | Column name
 +
! scope="col" | Data type
 +
! scope="col" | Description
 +
! scope="col" | Optional
 +
|-
 +
| title="Column name" | <mcc+mnc>
 +
| title="Data type" | string
 +
| title="Description" | Mobile country code and mobile network code
 +
| title="Optional" | no
 +
|-
 +
| title="Column name" | lac
 +
| title="Data type" | integer
 +
| title="Description" | Local area code
 +
| title="Optional" | no
 +
|-
 +
| title="Column name" | cellid
 +
| title="Data type" | integer
 +
| title="Description" | Cell tower id
 +
| title="Optional" | no
 +
|-
 +
| title="Column name" | rnc
 +
| title="Data type" | integer
 +
| title="Description" | Radio network controller;<br>provide "0", (zero, without the quotation marks) or an empty string in case there is no rnc value.
 +
| title="Optional" | no
 +
|-
 +
| title="Column name" | lat
 +
| title="Data type" | double
 +
| title="Description" | Latitude
 +
| title="Optional" | no
 +
|-
 +
| title="Column name" | lon
 +
| title="Data type" | double
 +
| title="Description" | Latitude
 +
| title="Optional" | no
 +
|-
 +
| title="Column name" | ratio
 +
| title="Data type" | integer
 +
| title="Description" | Accuracy of the cell coordinates. Use -1 for the exact position.
 +
| title="Optional" | yes
 +
|-
 +
| title="Column name" | data
 +
| title="Data type" | string
 +
| title="Description" | Short cell description
 +
| title="Optional" | yes
 +
|-
 +
| title="Column name" | rfu
 +
| title="Data type" | string
 +
| title="Description" |  Not really used; use 0 if unknown
 +
| title="Optional" | yes
 +
|}
 +
 +
===Response===
 +
On successful insert return HTTP 200 with the string "0,OK".
 +
 +
===Business logic===
 +
The request is handled by de.enaikoon.gpssuite.web.measure.NewMeasureController.
 +
===Time needed for processing newly uploaded measurements===
 +
After uploading new measurements to the OpenCellID community servers they are added to our waiting queues and processed in the background.
 +
We aim the real-time processing, but maximum time depends on traffic on OpenCellID servers. Current throughput of our servers is around 15000 measurements per second.
 +
 +
Measurements are processed in 3 steps:
 +
 +
# parsing and filtering raw data
 +
# updating measurement statistics and storing measurements in the database
 +
# updating existing cell towers information or adding new cell towers to the database
 +
 +
Our waiting queues for cell towers and for measurements are independent, so you can see your measurements in the OpenCellID database but related cell towers might be not updated yet. This means that if you upload a measurement of a cell tower that was not in the database before and the waiting queue for cell towers has some data to process, you have to expect some times (usually few minutes) until the queue delivers the newly uploaded cell tower information.
 +
 +
==Getting cell position==
 +
 +
GET/POST request to
 
<pre>
 
<pre>
 
http://<WebServiceURL>/cell/get
 
http://<WebServiceURL>/cell/get
 
</pre>
 
</pre>
  
*Parameters*
+
===Parameters===
*  _<WebServiceURL>_
+
<WebServiceURL>: the URL to the web service
The URL to the web service
+
  
*Headers*
+
===Headers===
Content-Type: application/x-www-form-urlencoded
+
  
*Payload*
+
'''JSON:'''<br>Content-Type: application/json;charset=UTF-8
cellid=<cellid>&mcc=<mcc>&mnc=<mnc>&lac=<lac>&fmt=<fmt>
+
  
Where:
+
'''XML:'''<br>Content-Type: text/xml;charset=utf-8
* _<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.
+
  
 +
'''AT:'''<br>Content-Type: text/plain;charset=utf-8
  
*Response*
+
===Payload===
On successful request return HTTP 200 with XML of the following format:
+
key=<apiKey>&mcc=<mcc>&mnc=<mnc>&lac=<lac>&cellid=<cellid>&radio=<radio>&format=<format>
<pre><code class="xml">
+
 
 +
Where
 +
 
 +
{| class="wikitable sortable" style="font-size: 85%; text-align: left;"
 +
|-
 +
! scope="col" | Parameter
 +
! scope="col" | Data type
 +
! scope="col" | Description
 +
! scope="col" | Optional
 +
 
 +
|-
 +
| title="Parameter" | <apiKey>
 +
| title="Data type" | string
 +
| title="Description" | API key assigned to the user
 +
| title="Optional" | no
 +
|-
 +
| title="Parameter" | <mcc>
 +
| title="Data type" | integer
 +
| title="Description" | Mobile country code
 +
| title="Optional" | no
 +
|-
 +
| title="Parameter" | <mnc>
 +
| title="Data type" | integer
 +
| title="Description" | Mobile network code or system identifier
 +
| title="Optional" | no
 +
|-
 +
| title="Parameter" | <lac>
 +
| title="Data type" | integer
 +
| title="Description" | Local area code, tracking area code or network id
 +
| title="Optional" | no
 +
|-
 +
| title="Parameter" | <cellid>
 +
| title="Data type" | integer
 +
| title="Description" | Cell id or base station id
 +
| title="Optional" | no
 +
|-
 +
| title="Parameter" | <radio>
 +
| title="Data type" | string
 +
| title="Description" | You can specifiy GSM, UMTS, LTE, NBIOT, NR or CDMA as the radio of returned cell. Otherwise first matched cell will be returned.
 +
| title="Optional" | yes
 +
|-
 +
| title="Parameter" | <format>
 +
| title="Data type" | string
 +
| title="Description" | You can specifiy xml, at or json as output. Default is xml.
 +
| title="Optional" | yes
 +
|}
 +
 
 +
===Response===
 +
 
 +
====XML====
 +
Upon successful request, HTTP 200 is returned with XML of the following format:
 +
<syntaxhighlight lang="xml">
 +
<?xml version="1.0" encoding="UTF-8"?>
 
<rsp stat="ok">
 
<rsp stat="ok">
<cell lac="0" mcc="250" lat="50.5715642160311" cellId="29513" lon="25.2897075399231" nbSamples="57" mnc="99" range="6000"/>
+
  <cell lat="52.891587"  
 +
        lon="9.438145"  
 +
        mcc="262"  
 +
        mnc="2"  
 +
        lac="434"  
 +
        cellid="9200"  
 +
        averageSignalStrength="-81"  
 +
        range="123"
 +
        samples="13"
 +
        changeable="1"
 +
        radio="GSM"/>
 
</rsp>
 
</rsp>
</code></pre>
+
</syntaxhighlight>
  
*Business logic*
 
The request is handled by @[email protected] It uses @[email protected] to calculate the average cell measurement, and builds an XML string to return to the user.
 
  
-------------
+
<syntaxhighlight lang="xml">
 +
<?xml version="1.0" encoding="UTF-8"?>
 +
<rsp stat="ok">
 +
  <cell lat="51.206"
 +
        lon="20.424"
 +
        mcc="260"
 +
        mnc="2"
 +
        lac="52712"
 +
        cellid="59350690"
 +
        averageSignalStrength="-96"
 +
        range="1234"
 +
        samples="5"
 +
        changeable="1"
 +
        radio="UMTS"
 +
        rnc="905"
 +
        cid="40610"/>
 +
</rsp>
 +
</syntaxhighlight>
  
h3. 4. Getting the raw measures used to compute the position of a cell
+
 
 +
<syntaxhighlight lang="xml">
 +
<?xml version="1.0" encoding="UTF-8"?>
 +
<rsp stat="ok">
 +
  <cell lat="51.90994"
 +
        lon="19.505"
 +
        mcc="260"
 +
        mnc="6"
 +
        lac="12"
 +
        cellid="864246"
 +
        averageSignalStrength="-100"
 +
        range="12345"
 +
        samples="4"
 +
        changeable="1"
 +
        radio="LTE"
 +
        tac="12"/>
 +
</rsp>
 +
</syntaxhighlight>
 +
 
 +
 
 +
<syntaxhighlight lang="xml">
 +
<?xml version="1.0" encoding="UTF-8"?>
 +
<rsp stat="ok">
 +
  <cell lat="42.46"
 +
        lon="-73.245"
 +
        mcc="310"
 +
        mnc="119"
 +
        lac="48"
 +
        cellid="4127"
 +
        averageSignalStrength="-90"
 +
        range="123"
 +
        samples="5"
 +
        changeable="1"
 +
        radio="CDMA"
 +
        sid="119"
 +
        nid="48"
 +
        bid="4127"/>
 +
</rsp>
 +
</syntaxhighlight>
 +
 
 +
====JSON====
 +
<syntaxhighlight lang="javascript">
 +
{
 +
  "lon": -73.245,
 +
  "lat": 42.46,
 +
  "mcc": 310,
 +
  "mnc": 119,
 +
  "lac": 48,
 +
  "cellid": 4127,
 +
  "averageSignalStrength": -90,
 +
  "range": 123,
 +
  "samples": 5,
 +
  "changeable": true,
 +
  "radio": "CDMA",
 +
  "sid": 119,
 +
  "nid": 48,
 +
  "bid": 4127
 +
}
 +
</syntaxhighlight>
 +
 
 +
====AT====
 +
<syntaxhighlight lang="text">
 +
+Location:42.46,-73.245,1483228800
 +
</syntaxhighlight>
 +
 
 +
===Business logic===
 +
The request is handled by de.enaikoon.gpssuite.web.cell.CellController.<br>
 +
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===
 +
<u>http://opencellid.org/cell/get?key=xxx&mcc=260&mnc=2&lac=10250&cellid=26511</u><br>
 +
<u>http://opencellid.org/cell/get?key=xxx&mcc=260&mnc=2&lac=10250&cellid=26511&radio=UMTS</u><br>
 +
<u>http://opencellid.org/cell/get?key=xxx&mcc=260&mnc=2&lac=10250&cellid=26511&format=json</u>
 +
 
 +
===Availability===
 +
This feature is available free of charge in case your application contributes data to OpenCellID at the same time.<br>
 +
In case you want to use this service without contributing to OpenCellID please refer to <u>[[Commercial_users|the commercial users guideline]]</u>.<br>
 +
An automated check for providing this service to white-listed apiKeys only was activated on Jun 15th, 2014
 +
 
 +
<!--
 +
==Getting the raw measurements used to compute the position of a cell==
  
 
GET/POST request to
 
GET/POST request to
 
<pre>
 
<pre>
http://<WebServiceURL>/cell/getMeasures?cellid=<cellid>&mcc=<mcc>&mnc=<mnc>&lac=<lac>
+
http://<WebServiceURL>/cell/getMeasures
 
</pre>
 
</pre>
  
*Parameters*
+
===Parameters===
*  _<WebServiceURL>_
+
<WebServiceURL>: the URL to the web service
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*
+
===Payload===
On successful request return HTTP 200 with XML of the following format:
+
key=<apiKey>&mcc=<mcc>&mnc=<mnc>&lac=<lac>&cellid=<cellid>&radio=<radio>&limit=<limit>&offset=<offset>&format=<format>
<pre><code class="xml">
+
 
 +
Where
 +
 
 +
{| class="wikitable sortable" style="font-size: 85%; text-align: left;"
 +
|-
 +
! scope="col" | Parameter
 +
! scope="col" | Data type
 +
! scope="col" | Description
 +
! scope="col" | Optional
 +
|-
 +
| title="Parameter" | <apiKey>
 +
| title="Data type" | string
 +
| title="Description" | API key assigned to the user
 +
| title="Optional" | no
 +
|-
 +
| title="Parameter" | <mcc>
 +
| title="Data type" | integer
 +
| title="Description" | Mobile country code
 +
| title="Optional" | no
 +
|-
 +
| title="Parameter" | <mnc>
 +
| title="Data type" | integer
 +
| title="Description" | Mobile network code or system identifier
 +
| title="Optional" | no
 +
|-
 +
| title="Parameter" | <lac>
 +
| title="Data type" | integer
 +
| title="Description" | Local area code, tracking area code or network id
 +
| title="Optional" | no
 +
|-
 +
| title="Parameter" | <cellid>
 +
| title="Data type" | integer
 +
| title="Description" | Cell id or base station id
 +
| title="Optional" | no
 +
|-
 +
| title="Parameter" | <radio>
 +
| title="Data type" | string
 +
| title="Description" | You can specifiy GSM, UMTS, LTE, NR, NBIOT or CDMA as the radio of returned data. Otherwise first matched cell will be returned with its measurements.
 +
| title="Optional" | yes
 +
|-
 +
| title="Parameter" | <limit>
 +
| title="Data type" | integer
 +
| title="Description" | A number defining max size of the returned list.<br>Default and max value is 1000.
 +
| title="Optional" | yes
 +
|-
 +
| title="Parameter" | <offset>
 +
| title="Data type" | integer
 +
| title="Description" | The field says to skip that many measurements before beginning to return measurements.<br>Default is 0.
 +
| title="Optional" | yes
 +
|-
 +
| title="Parameter" | <format>
 +
| title="Data type" | string
 +
| title="Description" | You can specifiy xml or json as output. Default is xml.
 +
| title="Optional" | yes
 +
|}
 +
 
 +
For the total number of measurements used to compute the position of a cell, please use /cell/getMeasuresSize (described below).
 +
 
 +
===Response===
 +
 
 +
====XML====
 +
Upon successful request, HTTP 200 is returned with XML in the following format:<br>
 +
<syntaxhighlight lang="xml">
 +
<?xml version="1.0" encoding="UTF-8"?>
 
<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 lat="42.47"  
<measure takenBy="1" lat="57.8240165710449" lon="28.00119972229" takenOn="Wed Apr 02 14:16:32 +0200 2008"/>
+
        lon="-73.24"  
<measure takenBy="1" lat="57.8240165710449" lon="28.00119972229" takenOn="Wed Apr 02 14:17:01 +0200 2008"/>
+
        mcc="310"  
<measure takenBy="1" lat="57.8240165710449" lon="28.00119972229" takenOn="Wed Apr 02 14:17:10 +0200 2008"/>
+
        mnc="119"  
<measure takenBy="1" lat="57.8240165710449" lon="28.00119972229" takenOn="Wed Apr 02 15:50:02 +0200 2008"/>
+
        lac="48"  
<measure takenBy="772" lat="57.8240013122559" lon="28.00119972229" takenOn="Wed Jul 22 17:02:40 +0200 2009"/>
+
        cellid="4217"  
<measure takenBy="772" lat="57.8240345622559" lon="28.0011345629" takenOn="Wed Jul 22 17:08:45 +0200 2009"/>
+
        averageSignalStrength="-91"  
<measure takenBy="2488" lat="3.42" lon="3.12" takenOn="Fri Feb 05 20:06:14 +0100 2010"/>
+
        range="123"  
<measure takenBy="805" lat="38.9687213" lon="-77.3410958" takenOn="Wed May 19 18:44:04 +0200 2010"/>
+
        samples="2"  
<measure takenBy="805" lat="53.1366825" lon="25.2740863" takenOn="Thu May 20 01:16:42 +0200 2010"/>
+
        changeable="1"  
<measure takenBy="772" lat="41.892409" lon="12.700801" takenOn="Mon May 31 18:34:29 +0200 20/>
+
        radio="CDMA"  
<measure takenBy="772" lat="23.0" lon="38.0" takenOn="Sun Jan 02 19:47:14 +0100 2011"/>
+
        sid="119"  
</cell>
+
        nid="48"  
 +
        bid="4217">
 +
    <measure id="53cfd12ee4b033313ec44a01"  
 +
            lat="42.469"  
 +
            lon="-73.24"  
 +
            mcc="310"  
 +
            mnc="119"  
 +
            lac="48"  
 +
            cellid="4217"  
 +
            created_at="1400128406300"  
 +
            measured_at="1400127406300"  
 +
            signal="-90"
 +
            rating="10.1"  
 +
            speed="20.2"  
 +
            direction="30.0"  
 +
            radio="CDMA"  
 +
            sid="119"  
 +
            nid="48"  
 +
            bid="4217"/>
 +
    <measure id="53cfd177e4b033313ec44e51"  
 +
            lat="42.471"  
 +
            lon="-73.24"  
 +
            mcc="310"  
 +
            mnc="119"  
 +
            lac="48"  
 +
            cellid="4217"  
 +
            created_at="1400128493848"  
 +
            measured_at="1400127493848"  
 +
            signal="-92"  
 +
            rating="20.0"  
 +
            speed="40.0"  
 +
            direction="40.0"  
 +
            radio="CDMA"  
 +
            sid="119"  
 +
            nid="48"  
 +
            bid="4217"/>
 +
  </cell>
 
</rsp>
 
</rsp>
</code></pre>
+
</syntaxhighlight>
  
 +
====JSON====
 +
<syntaxhighlight lang="javascript">
 +
{
 +
  "cell": {
 +
    "lon": 20.42,
 +
    "lat": 51.2,
 +
    "mcc": 260,
 +
    "mnc": 2,
 +
    "lac": 52702,
 +
    "cellid": 59350690,
 +
    "averageSignalStrength": -90,
 +
    "range": 123,
 +
    "samples": 2,
 +
    "changeable": true,
 +
    "radio": "UMTS",
 +
    "rnc": 905,
 +
    "cid": 40610
 +
  },
 +
  "measurements": [
 +
    {
 +
      "id": "52d3db7ccd214d12357b9fee",
 +
      "lon": 20.42,
 +
      "lat": 51.2,
 +
      "mcc": 260,
 +
      "mnc": 2,
 +
      "lac": 52702,
 +
      "cellid": 59350690,
 +
      "created_at": 1399614776134,
 +
      "measured_at": 1398477214000,
 +
      "signal": -90,
 +
      "rating": 10.1,
 +
      "speed": 20.4,
 +
      "direction": 90.8,
 +
      "radio": "UMTS",
 +
      "rnc": 905,
 +
      "cid": 40610
 +
    },
 +
    {
 +
      "id": "52d3db7ccd214d12357b9ff2",
 +
      "lon": 20.42,
 +
      "lat": 51.2,
 +
      "mcc": 260,
 +
      "mnc": 2,
 +
      "lac": 52702,
 +
      "cellid": 59350690,
 +
      "created_at": 1380559325000,
 +
      "measured_at": 1379477219000,
 +
      "signal": -90,
 +
      "radio": "UMTS",
 +
      "rnc": 905,
 +
      "cid": 40610,
 +
      "psc": 2
 +
    }
 +
  ]
 +
}
 +
</syntaxhighlight>
 +
 +
===Business logic===
 +
The request is handled by de.enaikoon.gpssuite.web.measure.CellController.
 +
 +
===Example===
 +
<u>http://www.opencellid.org/cell/getMeasures?key=xxx&mcc=260&mnc=2&lac=10250&cellid=26511&limit=10&offset=1</u><br>
 +
<u>http://www.opencellid.org/cell/getMeasures?key=xxx&mcc=260&mnc=2&lac=10250&cellid=26511&radio=UMTS&limit=10&offset=1&format=json</u>
 +
 +
===Availability===
 +
This feature is available free of charge in case your application contributes data to OpenCellID at the same time.<br>
 +
In case you want to use this service without contributing to OpenCellID please refer to <u>[[Commercial_users|the commercial users guideline]]</u>.<br>
 +
An automated check for providing this service to white-listed apiKeys only was activated on Jun 15th, 2014
 +
 +
==Getting the number of all measures used to compute the position of a cell==
 +
 +
GET/POST request to
 +
<pre>
 +
http://<WebServiceURL>/cell/getMeasuresSize
 +
</pre>
 +
 +
===Parameters===
 +
<WebServiceURL>: the URL to the web service
 +
 +
===Payload===
 +
key=<apiKey>&mcc=<mcc>&mnc=<mnc>&lac=<lac>&cellid=<cellid>&radio=<radio>&format=<format>
 +
 +
Where
 +
 +
{| class="wikitable sortable" style="font-size: 85%; text-align: left;"
 +
|-
 +
! scope="col" | Parameter
 +
! scope="col" | Data type
 +
! scope="col" | Description
 +
! scope="col" | Optional
 +
|-
 +
| title="Parameter" | <apiKey>
 +
| title="Data type" | string
 +
| title="Description" | API key assigned to the user
 +
| title="Optional" | no
 +
|-
 +
| title="Parameter" | <mcc>
 +
| title="Data type" | integer
 +
| title="Description" | Mobile country code
 +
| title="Optional" | no
 +
|-
 +
| title="Parameter" | <mnc>
 +
| title="Data type" | integer
 +
| title="Description" | Mobile network code or system identifier
 +
| title="Optional" | no
 +
|-
 +
| title="Parameter" | <lac>
 +
| title="Data type" | integer
 +
| title="Description" | Local area code, tracking area code or network id
 +
| title="Optional" | no
 +
|-
 +
| title="Parameter" | <cellid>
 +
| title="Data type" | integer
 +
| title="Description" | Cell id or base station id
 +
| title="Optional" | no
 +
|-
 +
| title="Parameter" | <radio>
 +
| title="Data type" | string
 +
| title="Description" | You can specifiy GSM, UMTS, LTE, NR, NBIOT or CDMA as the radio of returned data. Otherwise first matched cell will be returned with its measurements.
 +
| title="Optional" | yes
 +
|-
 +
| title="Parameter" | <format>
 +
| title="Data type" | string
 +
| title="Description" | You can specifiy xml or json as output. Default is xml.
 +
| title="Optional" | no
 +
|}
 +
 +
===Response===
 +
 +
====XML====
 +
Upon successful request, HTTP 200 is returned with XML in the following format:<br>
 +
<syntaxhighlight lang="xml">
 +
<?xml version="1.0" encoding="UTF-8"?>
 +
<rsp stat="ok">
 +
  <measurements count="123"/>
 +
</rsp>
 +
</syntaxhighlight>
 +
====JSON====
 +
<syntaxhighlight lang="javascript">
 +
{
 +
  "count": 123
 +
}
 +
</syntaxhighlight>
  
*Business logic*
+
===Business logic===
The request is handled by @de.enaikoon.gpssuite.web.measure.CellController@.
+
The request is handled by de.enaikoon.gpssuite.web.measure.CellController.
  
------------------
+
===Example===
 +
<u>http://www.opencellid.org/cell/getMeasuresSize?key=xxx&mcc=260&mnc=2&lac=10250&cellid=26511&radio=GSM</u><br>
 +
<u>http://www.opencellid.org/cell/getMeasuresSize?key=xxx&mcc=260&mnc=2&lac=10250&cellid=26511&format=json</u>
  
h3. 5. Obtaining the list of cells in a specified area
+
===Availability===
 +
This feature is available free of charge in case your application contributes data to OpenCellID at the same time.<br>
 +
In case you want to use this service without contributing to OpenCellID please refer to <u>[[Commercial_users|the commercial users guideline]]</u>.<br>
 +
An automated check for providing this service to white-listed apiKeys only was activated on Jun 15th, 2014
 +
-->
 +
==Getting the list of cells in a specified area==
  
 
GET request to
 
GET request to
 
<pre>
 
<pre>
http://<WebServiceURL>/cell/getInArea?key=<ApiKey>&BBOX=<latmin>,<lonmin>,<latmax>,<lonmax>&mcc=<mcc>&mnc=<mnc>&limit=<limit>&fmt=<fmt>
+
http://<WebServiceURL>/cell/getInArea
 
</pre>
 
</pre>
  
*Parameters*
+
===Parameters===
*  _<WebServiceURL>_
+
<WebServiceURL>: the URL to the web service
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*
+
===Payload===
On successful request return HTTP 200 with the following output structures:
+
key=<apiKey>&BBOX=<latmin>,<lonmin>,<latmax>,<lonmax>&mcc=<mcc>&mnc=<mnc>&lac=<lac>&radio=<radio>&limit=<limit>&offset=<offset>&format=<format>
  
XML
+
Where
<pre><code class="xml">
+
 
 +
{| class="wikitable sortable" style="font-size: 85%; text-align: left;"
 +
|-
 +
! scope="col" | Parameter
 +
! scope="col" | Data type
 +
! scope="col" | Description
 +
! scope="col" | Optional
 +
|-
 +
| title="Parameter" | <apiKey>
 +
| title="Data type" | string
 +
| title="Description" | API key assigned to the user
 +
| title="Optional" | no
 +
|-
 +
| title="Parameter" | <latmin>
 +
| title="Data type" | double
 +
| title="Description" | Minimal bounding latitude
 +
| title="Optional" | no
 +
|-
 +
| title="Parameter" | <lonmin>
 +
| title="Data type" | double
 +
| title="Description" | Minimal bounding longitude
 +
| title="Optional" | no
 +
|-
 +
| title="Parameter" | <latmax>
 +
| title="Data type" | double
 +
| title="Description" | Maximal bounding latitude
 +
| title="Optional" | no
 +
|-
 +
| title="Parameter" | <lonmax>
 +
| title="Data type" | double
 +
| title="Description" | Maximal bounding longitude
 +
| title="Optional" | no
 +
|-
 +
| title="Parameter" | <mcc>
 +
| title="Data type" | integer
 +
| title="Description" | Mobile country code; If you want to restrict the result to a specific country
 +
| title="Optional" | yes
 +
|-
 +
| title="Parameter" | <mnc>
 +
| title="Data type" | integer
 +
| title="Description" | Mobile network code or system identifier; If you want to restrict the result
 +
| title="Optional" | yes
 +
|-
 +
| title="Parameter" | <lac>
 +
| title="Data type" | integer
 +
| title="Description" | Local area code, tracking area code or network id; If you want to restrict the result
 +
| title="Optional" | yes
 +
|-
 +
| title="Parameter" | <radio>
 +
| title="Data type" | string
 +
| title="Description" | You can specifiy GSM, UMTS, LTE, NR, NBIOT or CDMA as the radio of returned cells. Otherwise cells with any radios will be returned.
 +
| title="Optional" | yes
 +
|-
 +
| title="Parameter" | <limit>
 +
| title="Data type" | integer
 +
| title="Description" | A number defining maximum size of the returned list. Default and maximum value is 1000.
 +
| title="Optional" | yes
 +
|-
 +
| title="Parameter" | <offset>
 +
| title="Data type" | integer
 +
| title="Description" | The field says to skip that many cells before beginning to return cells. Default is 0.
 +
| title="Optional" | yes
 +
|-
 +
| title="Parameter" | <format>
 +
| title="Data type" | string
 +
| title="Description" | You can specify kml, xml, csv or json as output. Default is kml.<br>In csv type of output, there is a first line defining the content of the list.
 +
| title="Optional" | yes
 +
|}
 +
 
 +
For the total number of cells in a specified area, please use /cell/getInAreaSize (described below).
 +
 
 +
===Response===
 +
Upon successful request, HTTP 200 is returned with one of the following output structures:
 +
 
 +
====XML====
 +
<syntaxhighlight lang="xml">
 +
<?xml version="1.0" encoding="UTF-8"?>
 
<rsp stat="ok">
 
<rsp stat="ok">
<cell lac="20371" cellId="1236" mcc="208" lat="48.906431085" lon="2.211114095" nbSamples="2" mnc="20"/>
+
  <cell lat="52.9523755"  
<cell lac="14340" cellId="4674446" mcc="208" lat="48.840991628822" lon="2.21148552373067" nbSamples="6" mnc="1"/>
+
        lon="9.252112"  
<cell lac="14340" cellId="4700495" mcc="208" lat="48.8411471061408" lon="2.21169734839367" nbSamples="6" mnc="1"/>
+
        mcc="262"  
<cell lac="318" cellId="3319" mcc="208" lat="48.8286924362183" lon="2.21202850341797" nbSamples="1" mnc="20"/>
+
        mnc="2"  
<cell lac="21700" cellId="24149" mcc="208" lat="48.8317127038461" lon="2.23276453461538" nbSamples="26" mnc="10"/>
+
        lac="1434"  
 +
        cellid="17275"  
 +
        averageSignalStrength="-70"  
 +
        range="123"  
 +
        samples="12"  
 +
        changeable="1"  
 +
        radio="GSM"/>
 +
  <cell lat="52.9463072"  
 +
        lon="9.258809"  
 +
        mcc="262"  
 +
        mnc="2"  
 +
        lac="1434"  
 +
        cellid="17276"  
 +
        averageSignalStrength="-98"  
 +
        range="1234"  
 +
        samples="11"  
 +
        changeable="1"  
 +
        radio="LTE"
 +
        tac="1434"/>
 +
  <cell lat="52.9367185"  
 +
        lon="9.27343925"  
 +
        mcc="260"  
 +
        mnc="16256"  
 +
        lac="1434"  
 +
        cellid="17272"  
 +
        averageSignalStrength="-93"  
 +
        range="12345"  
 +
        samples="12"  
 +
        changeable="1"  
 +
        radio="CDMA"  
 +
        sid="16256"  
 +
        bid="1434"  
 +
        nid="17272"/>
 
</rsp>
 
</rsp>
</code></pre>
+
</syntaxhighlight>
  
KML
+
====KML (default)====
<pre><code class="xml">
+
<syntaxhighlight lang="xml">
 +
<?xml version="1.0" encoding="UTF-8"?>
 
<kml xmlns="http://earth.google.com/kml/2.1">
 
<kml xmlns="http://earth.google.com/kml/2.1">
<Document>
+
  <Document>
<name>OpenCellID Cells</name>
+
    <name>OpenCellID Cells</name>
<description>List of available cells</description>
+
    <description>List of available cells</description>
<Placemark>
+
    <Placemark>
<name>Cell:1236 mcc:208 mnc:20 lac:20371</name>
+
      <name></name>
<description>Operator: Bouygues Telecom Nb Samples:2</description>
+
      <description><![CDATA[lat: <b>52.9523755</b><br/>
<Point>
+
                            lon: <b>9.252112</b><br/>
<coordinates>2.211114095,48.906431085,0</coordinates>
+
                            mcc: <b>262</b><br/>
</Point>
+
                            mnc: <b>2</b><br/>
</Placemark>
+
                            lac: <b>1434</b><br/>
<Placemark>
+
                            cellid: <b>17275</b><br/>
<name>Cell:4674446 mcc:208 mnc:1 lac:14340</name>
+
                            averageSignalStrength: <b>-73</b><br/>
<description>Operator: Orange Nb Samples:6</description>
+
                            range: <b>123</b><br/>
<Point>
+
                            samples: <b>12</b><br/>
<coordinates>2.21148552373067,48.840991628822,0</coordinates>
+
                            changeable: <b>1</b><br/>
</Point>
+
                            radio: <b>GSM</b><br/>
</Placemark>
+
                            rnc: <b></b><br/>
 +
                            cid: <b></b><br/>
 +
                            tac: <b></b><br/>
 +
                            sid: <b></b><br/>
 +
                            nid: <b></b><br/>
 +
                            bid: <b></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>21.1525</b><br/>
 +
                            mcc: <b>260</b><br/>
 +
                            mnc: <b>2</b><br/>
 +
                            lac: <b>1434</b><br/>
 +
                            cellid: <b>17272</b><br/>
 +
                            averageSignalStrength: <b>-83</b><br/>
 +
                            range: <b>1234</b><br/>
 +
                            samples: <b>11</b><br/>
 +
                            changeable: <b>1</b><br/>
 +
                            radio: <b>LTE</b><br/>
 +
                            rnc: <b></b><br/>
 +
                            cid: <b></b><br/>
 +
                            tac: <b>1434</b><br/>
 +
                            sid: <b></b><br/>
 +
                            nid: <b></b><br/>
 +
                            bid: <b></b>]]>
 +
      </description>
 +
      <Point><coordinates>21.1525,52.9463072,0</coordinates></Point>
 +
    </Placemark>
 +
    <Placemark>
 +
      <name></name>
 +
      <description><![CDATA[lat: <b>53.9367185</b><br/>
 +
                            lon: <b>12.27343925</b><br/>
 +
                            mcc: <b>262</b><br/>
 +
                            mnc: <b>16256</b><br/>
 +
                            lac: <b>1434</b><br/>
 +
                            cellid: <b>17272</b><br/>
 +
                            averageSignalStrength: <b>-91</b><br/>
 +
                            range: <b>12345</b><br/>
 +
                            samples: <b>2</b><br/>
 +
                            changeable: <b>1</b><br/>
 +
                            radio: <b>CDMA</b><br/>
 +
                            rnc: <b></b><br/>
 +
                            cid: <b></b><br/>
 +
                            tac: <b></b><br/>
 +
                            sid: <b>16256</b><br/>
 +
                            nid: <b>1434</b><br/>
 +
                            bid: <b>17272</b>]]>
 +
      </description>
 +
      <Point><coordinates>12.27343925,53.9367185,0</coordinates></Point>
 +
    </Placemark>
 +
    <Placemark>
 +
      <name></name>
 +
      <description><![CDATA[lat: <b>52.1322157</b><br/>
 +
                            lon: <b>21.065345</b><br/>
 +
                            mcc: <b>260</b><br/>
 +
                            mnc: <b>2</b><br/>
 +
                            lac: <b>1434</b><br/>
 +
                            cellid: <b>42042781</b><br/>
 +
                            averageSignalStrength: <b>-89</b><br/>
 +
                            range: <b>1231</b><br/>
 +
                            samples: <b>5</b><br/>
 +
                            changeable: <b>1</b><br/>
 +
                            radio: <b>UMTS</b><br/>
 +
                            rnc: <b>641</b><br/>
 +
                            cid: <b>34205</b><br/>
 +
                            tac: <b></b><br/>
 +
                            sid: <b></b><br/>
 +
                            nid: <b></b><br/>
 +
                            bid: <b></b>]]>
 +
      </description>
 +
      <Point><coordinates>21.065345,52.1322157,0</coordinates></Point>
 +
    </Placemark>
 +
  </Document>
 
</kml>
 
</kml>
</code></pre>
+
</syntaxhighlight>
  
TXT
+
====CSV====
 +
<pre>lat,lon,mcc,mnc,lac,cellid,averageSignalStrength,range,samples,changeable,radio,rnc,cid,tac,sid,nid,bid
 +
52.275505,21.016382,260,2,45080,21728,-55,123,2,1,GSM,,,,,,
 +
52.201454,21.065345,260,2,58140,42042781,-59,1234,3,1,UMTS,641,34205,,,,
 +
52.207123,21.029972,260,6,58,119093,-80,122,2,1,LTE,,,58,,,
 +
52.274612,21.034485,260,16256,45,22613,-98,134,2,1,CDMA,,,,16256,45,22613</pre>
 +
 
 +
====JSON====
 +
<syntaxhighlight lang="javascript">
 +
{
 +
  "count": 3,
 +
  "cells": [
 +
    {
 +
      "lon": 21.014,
 +
      "lat": 52.278,
 +
      "mcc": 260,
 +
      "mnc": 2,
 +
      "lac": 45080,
 +
      "cellid": 22613,
 +
      "averageSignalStrength": -70,
 +
      "range": 123,
 +
      "samples": 2,
 +
      "changeable": true,
 +
      "radio": "GSM"
 +
    },
 +
    {
 +
      "lon": 21.04,
 +
      "lat": 52.2234,
 +
      "mcc": 260,
 +
      "mnc": 2,
 +
      "lac": 58140,
 +
      "cellid": 42042781,
 +
      "averageSignalStrength": -90,
 +
      "range": 125,
 +
      "samples": 2,
 +
      "changeable": true,
 +
      "radio": "UMTS",
 +
      "rnc": 641,
 +
      "cid": 34205
 +
    },
 +
    {
 +
      "lon": 21.5604,
 +
      "lat": 52.284,
 +
      "mcc": 260,
 +
      "mnc": 2,
 +
      "lac": 581,
 +
      "cellid": 42048,
 +
      "averageSignalStrength": -90,
 +
      "range": 12345,
 +
      "samples": 9,
 +
      "changeable": true,
 +
      "radio": "LTE",
 +
      "tac": 581
 +
    }
 +
  ]
 +
}
 +
</syntaxhighlight>
 +
 
 +
===Business logic===
 +
The request is handled by de.enaikoon.gpssuite.web.measure.CellController.
 +
 
 +
===Example===
 +
<u>http://www.opencellid.org/cell/getInArea?key=xxx&BBOX=52.0,21.0,52.5,21.5&mcc=260&mnc=2&lac=45070&limit=4&offset=16&format=kml</u><br>
 +
<u>http://www.opencellid.org/cell/getInArea?key=xxx&BBOX=52.0,21.0,52.5,21.5&mcc=260&mnc=2&lac=45070&radio=CDMA&limit=4&offset=16&format=json</u>
 +
 
 +
===Availability===
 +
This feature is available free of charge in case your application contributes data to OpenCellID at the same time.<br>
 +
In case you want to use this service without contributing to OpenCellID please refer to <u>[[Commercial_users|the commercial users guideline]]</u>.<br>
 +
An automated check for providing this service to white-listed apiKeys only was activated on Jun 15th, 2014
 +
 
 +
==Getting the number of cells in a specified area==
 +
 
 +
GET request to
 
<pre>
 
<pre>
lat,lon,mcc,mnc,lac,cellid,range,nbSamples
+
http://<WebServiceURL>/cell/getInAreaSize
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>
 
</pre>
  
*Business logic*
+
===Parameters===
The request is handled by @de.enaikoon.gpssuite.web[email protected]
+
<WebServiceURL>: the URL to the web service
  
-------------
+
===Payload===
 +
key=<apiKey>&BBOX=<latmin>,<lonmin>,<latmax>,<lonmax>&mcc=<mcc>&mnc=<mnc>&lac=<lac>&radio=<radio>&format=<format>
  
h3. 6. Deleting a measure
+
Where
 +
 
 +
{| class="wikitable sortable" style="font-size: 85%; text-align: left;"
 +
|-
 +
! scope="col" | Parameter
 +
! scope="col" | Data type
 +
! scope="col" | Description
 +
! scope="col" | Optional
 +
|-
 +
| title="Parameter" | <apiKey>
 +
| title="Data type" | string
 +
| title="Description" | API key assigned to the user
 +
| title="Optional" | no
 +
|-
 +
| title="Parameter" | <latmin>
 +
| title="Data type" | double
 +
| title="Description" | Minimal bounding latitude
 +
| title="Optional" | no
 +
|-
 +
| title="Parameter" | <lonmin>
 +
| title="Data type" | double
 +
| title="Description" | Minimal bounding longitude
 +
| title="Optional" | no
 +
|-
 +
| title="Parameter" | <latmax>
 +
| title="Data type" | double
 +
| title="Description" | Maximal bounding latitude
 +
| title="Optional" | no
 +
|-
 +
| title="Parameter" | <lonmax>
 +
| title="Data type" | double
 +
| title="Description" | Maximal bounding longitude
 +
| title="Optional" | no
 +
|-
 +
| title="Parameter" | <mcc>
 +
| title="Data type" | integer
 +
| title="Description" | Mobile country code; If you want to restrict the result to a specific country
 +
| title="Optional" | yes
 +
|-
 +
| title="Parameter" | <mnc>
 +
| title="Data type" | integer
 +
| title="Description" | Mobile network code or system identifier; If you want to restrict the result
 +
| title="Optional" | yes
 +
|-
 +
| title="Parameter" | <lac>
 +
| title="Data type" | integer
 +
| title="Description" | Local area code, tracking area code or network id; If you want to restrict the result
 +
| title="Optional" | yes
 +
|-
 +
| title="Parameter" | <radio>
 +
| title="Data type" | string
 +
| title="Description" | You can specifiy GSM, UMTS, LTE, NR or CDMA as the radio of returned data. Otherwise any cells will be returned.
 +
| title="Optional" | yes
 +
|-
 +
| title="Parameter" | <format>
 +
| title="Data type" | string
 +
| title="Description" | You can specifiy xml or json as output. Default is xml.
 +
| title="Optional" | yes
 +
|}
 +
 
 +
===Response===
 +
Upon successful request, HTTP 200 is returned with XML in the following format:
 +
 
 +
====XML====
 +
<syntaxhighlight lang="xml">
 +
<?xml version="1.0" encoding="UTF-8"?>
 +
<rsp stat="ok">
 +
  <cells count="5"/>
 +
</rsp>
 +
</syntaxhighlight>
 +
====JSON====
 +
<syntaxhighlight lang="javascript">
 +
{
 +
  "count": 123
 +
}
 +
</syntaxhighlight>
 +
 
 +
===Business logic===
 +
The request is handled by de.enaikoon.gpssuite.web.measure.CellController.
 +
 
 +
===Example===
 +
<u>http://www.opencellid.org/cell/getInAreaSize?key=xxx&BBOX=52.0,21.0,52.5,21.5&mcc=260&mnc=2&lac=45070</u><br>
 +
<u>http://www.opencellid.org/cell/getInAreaSize?key=xxx&BBOX=52.0,21.0,52.5,21.5&mcc=260&mnc=2&lac=45070&radio=CDMA&format=json</u>
 +
 
 +
===Availability===
 +
This feature is available free of charge in case your application contributes data to OpenCellID at the same time.<br>
 +
In case you want to use this service without contributing to OpenCellID please refer to <u>[[Commercial_users|the commercial users guideline]]</u>.<br>
 +
An automated check for providing this service to white-listed apiKeys only was activated on Jun 15th, 2014
 +
 
 +
<!--
 +
==Deleting a measurement==
  
 
POST request to
 
POST request to
 
<pre>
 
<pre>
http://<WebServiceURL>/measure/delete/<id>
+
http://<WebServiceURL>/measure/delete
 
</pre>
 
</pre>
  
*Parameters*
+
===Parameters===
*  _<WebServiceURL>_
+
<WebServiceURL>: the URL to the web service
The URL to the web service
+
* _<id>_
+
ID of the measure to delete
+
  
*Headers*
+
<id>: ID of the measurement to be deleted
  
*Payload*
+
===Payload===
key=<ApiKey>
+
key=<apiKey>&id=<id>
  
 
Where
 
Where
* _<ApiKey>_
 
API key issued to user
 
  
*Response*
+
{| class="wikitable sortable" style="font-size: 85%; text-align: left;"
On successful delete return HTTP 200.
+
|-
 +
! scope="col" class="unsortable" | Parameter
 +
! scope="col" class="unsortable" | Data type
 +
! scope="col" class="unsortable" | Description
 +
| scope="col" class="unsortable" | Optional
  
*Business logic*
+
|-
The request is handled by @de.enaikoon.gpssuite.web.measure[email protected]
+
| title="Parameter" | <apiKey>
 +
| title="Data type" | string
 +
| title="Description" | API key assigned to the user
 +
| title="Optional" | no
 +
|-
 +
| title="Parameter" | <id>
 +
| title="Data type" | string
 +
| title="Description" | ID of the measure to delete
 +
| title="Optional" | no
 +
|}
  
-------------
+
===Response===
 +
Upon successful deletion, HTTP 200 is returned with the string "Measurement with id=<id> has been deleted."
  
h3. 7. Listing a user's measurements
+
===Business logic===
 +
The request is handled by de.enaikoon.gpssuite.web.measure.MeasureController.
 +
 
 +
===Example===
 +
<u>http://www.opencellid.org/measure/delete?key=xxx&id=123abc4567890123abcd1234</u>
 +
 
 +
===Availability===
 +
This feature is available free of charge in case your application contributes data to OpenCellID at the same time.<br>
 +
In case you want to use this service without contributing to OpenCellID please refer to <u>[[Commercial_users|the commercial users guideline]]</u>.<br>
 +
An automated check for providing this service to white-listed apiKeys only was activated on Jun 15th, 2014
 +
 
 +
==Listing a user's measurements==
  
 
GET request to
 
GET request to
 
<pre>
 
<pre>
http://<WebServiceURL>/measure/list?key=<ApiKey>
+
http://<WebServiceURL>/measure/list
 
</pre>
 
</pre>
  
*Parameters*
+
===Parameters===
*  _<WebServiceURL>_
+
<WebServiceURL>: the URL to the web service
The URL to the web service
+
* _<ApiKey>_: hex
+
API key issued to user
+
  
*Response*
+
===Payload===
On successful request return HTTP 200 with XML of the following format:
+
key=<apiKey>&limit=<limit>&offset=<offset>&format=<format>
  
<pre><code class="xml">
+
Where
<rsp>
+
 
<measures total="2">
+
{| class="wikitable sortable" style="font-size: 85%; text-align: left;"
   <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"/>
+
! scope="col" class="unsortable" | Parameter
</measures>
+
! scope="col" class="unsortable" | Data type
 +
! scope="col" class="unsortable" | Description
 +
! scope="col" class="unsortable" | Optional
 +
|-
 +
| title="Parameter" | <apiKey>
 +
| title="Data type" | string
 +
| title="Description" | API key assigned to the user
 +
| title="Optional" | no
 +
|-
 +
| title="Parameter" | <limit>
 +
| title="Data type" | integer
 +
| title="Description" | A number defining maximum size of the returned list.<br>Default and maximum value is 1000.
 +
| title="Optional" | yes
 +
|-
 +
| title="Parameter" | <offset>
 +
| title="Data type" | integer
 +
| title="Description" | The field says to skip that many measurements before beginning to return measurements.<br>Default is 0.
 +
| title="Optional" | yes
 +
|-
 +
| title="Parameter" | <format>
 +
| title="Data type" | string
 +
| title="Description" | You can specify csv, xml, kml or json as output. Default is csv.<br>In csv type of output, a first line defining the content of the list.
 +
| title="Optional" | yes
 +
|}
 +
 
 +
For the total number of cells in a specified area, please use /measure/listSize (described below).
 +
 
 +
===Response===
 +
Upon successful request, HTTP 200 is returned with one of the following output structures, '''oldest''' entries first:
 +
 
 +
====CSV (default)====
 +
<pre>
 +
id,mcc,mnc,lac,cellid,lat,lon,created_at,measured_at,signal,rating,speed,direction,radio,ta,rnc,cid,psc,tac,pci,sid,nid,bid
 +
127b4c71e4b041a566539fc5,260,2,38,17171,21.0132,52.235,1400589414253,1396096553493,-90,,,,GSM,3,,,,,,,,
 +
14b52ea2e4b564a972d12361,260,6,52712,59350690,20.424,51.206,1404382897375,1404382894835,-70,,,,UMTS,,905,40610,123,,,,,
 +
14b52ea2e4b564a972c73b29,260,6,18512,30694,21.0132,52.21,1404382866577,1404381511123,-60,10.1,2.3,93.1,LTE,,,,,18512,,,,
 +
14b52ea2e4b564a972c82a67,260,6,18512,30694,21.0137,52.212,1404382867773,1404381512374,-60,10.2,2.5,93.2,LTE,2,,,,18512,3,,,
 +
15b52ea2e4b564a972d11114,310,119,48,4127,42.46,-73.245,1404382891235,1404382890121,-99,,,,CDMA,,,,,,,119,48,4127
 +
</pre>
 +
 
 +
====XML====
 +
<syntaxhighlight lang="xml">
 +
<?xml version="1.0" encoding="UTF-8"?>
 +
<rsp stat="ok">
 +
   <measure id="1213db7abcda4d36357b9f12"  
 +
          lat="52.892139"
 +
          lon="9.436598"
 +
          mcc="262"
 +
          mnc="2"
 +
          lac="434"
 +
          cellid="9200"
 +
          created_at="1311615996112"
 +
          measured_at="1311512208000"
 +
          signal="-94"
 +
          rating="10.1"  
 +
          speed="10.2"  
 +
          direction="90.9"  
 +
          radio="GSM"  
 +
          ta="3" />
 +
  <measure id="1213db7abcda4d36357b9f15"
 +
          lat="52.212"
 +
          lon="21.0137"  
 +
          mcc="260"  
 +
          mnc="2"
 +
          lac="52712"
 +
          cellid="59350690"
 +
          created_at="1311615996122"
 +
          measured_at="1311511534000"
 +
          signal="-83"
 +
          rating="20.1"
 +
          speed="1.2"
 +
          direction="9.5"
 +
          radio="UMTS"
 +
          rnc="905"
 +
          cid="40610"
 +
          psc="102" />
 +
   <measure id="14b12ca2e4b564a972c82321"  
 +
          lat="52.96261"  
 +
          lon="9.241319"  
 +
          mcc="262"  
 +
          mnc="2"
 +
          lac="1434"
 +
          cellid="17271"
 +
          created_at="1404382891235"
 +
          measured_at="1404382890121"  
 +
          signal="-82"  
 +
          rating="20.12"  
 +
          speed="11.12"  
 +
          direction="90.5"
 +
          radio="LTE"
 +
          tac="1434"
 +
          pci="2" />
 +
  <measure id="15b52ea2e4b564a972d11114"
 +
          lat="42.46"
 +
          lon="-73.245"
 +
          mcc="310"
 +
          mnc="119"
 +
          lac="48"
 +
          cellid="4127"
 +
          created_at="1404382897375"
 +
          measured_at="1404382897221"
 +
          signal="-99"
 +
          rating="0.0"
 +
          speed="0.0"
 +
          direction="0.0"
 +
          radio="CDMA"
 +
          sid="119"
 +
          nid="48"
 +
          bid="4127" />
 
</rsp>
 
</rsp>
</code></pre>
+
</syntaxhighlight>
 +
 
 +
====KML====
 +
<syntaxhighlight lang="xml">
 +
<?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.4</b><br/>
 +
                            speed: <b>0</b><br/>
 +
                            direction: <b>0</b><br/>
 +
                            radio: <b>GSM</b><br/>
 +
                            ta: <b>2</b><br/>
 +
                            rnc: <b></b><br/>
 +
                            cid: <b></b><br/>
 +
                            psc: <b></b><br/>
 +
                            tac: <b></b><br/>
 +
                            pci: <b></b><br/>
 +
                            sid: <b></b><br/>
 +
                            nid: <b></b><br/>
 +
                            bid: <b></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>59350690</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.4</b><br/>
 +
                            speed: <b>4.02</b><br/>
 +
                            direction: <b>0.56</b><br/>
 +
                            radio: <b>UMTS</b><br/>
 +
                            ta: <b></b><br/>
 +
                            rnc: <b>905</b><br/>
 +
                            cid: <b>40610</b><br/>
 +
                            psc: <b>12</b><br/>
 +
                            tac: <b></b><br/>
 +
                            pci: <b></b><br/>
 +
                            sid: <b></b><br/>
 +
                            nid: <b></b><br/>
 +
                            bid: <b></b>]]>
 +
      </description>
 +
      <Point><coordinates>9.241319,52.96261,0</coordinates></Point>
 +
    </Placemark>
 +
  </Document>
 +
</kml>
 +
</syntaxhighlight>
 +
 
 +
====JSON====
 +
<syntaxhighlight lang="javascript">
 +
{
 +
  "count": 2,
 +
  "measurements": [
 +
    {
 +
      "id": "11123b7abcda1436357b9f12",
 +
      "lon": 9.436598,
 +
      "lat": 52.892139,
 +
      "mcc": 262,
 +
      "mnc": 2,
 +
      "lac": 434,
 +
      "cellid": 9200,
 +
      "created_at": 1311615996112,
 +
      "measured_at": 1311512208000,
 +
      "signal": -84,
 +
      "rating": 10.3,
 +
      "speed": 10.2,
 +
      "direction": 90.08,
 +
      "radio": "GSM",
 +
      "ta": 3
 +
    },
 +
    {
 +
      "id": "11123b7abcda1236357b9f15",
 +
      "lon": 9.241319,
 +
      "lat": 52.96261,
 +
      "mcc": 262,
 +
      "mnc": 2,
 +
      "lac": 1434,
 +
      "cellid": 42119093,
 +
      "created_at": 1311615996122,
 +
      "measured_at": 1311511534000,
 +
      "signal": -93,
 +
      "rating": 20.13,
 +
      "speed": 11.1,
 +
      "direction": 90.01,
 +
      "radio": "UMTS",
 +
      "rnc": 642,
 +
      "cid": 44981
 +
    }
 +
  ]
 +
}
 +
</syntaxhighlight>
 +
 
 +
If you want the '''newest''' entries, use an <code>&offset=</code> to subtract most of the [[#Getting the number of measurements from a user|number of measurements from a user]].
 +
 
 +
===Business logic===
 +
The request is handled by de.enaikoon.gpssuite.web.measure.MeasureController.
 +
 
 +
===Example===
 +
<u>http://www.opencellid.org/measure/list?key=xxx&limit=2&offset=128&format=xml</u>
 +
 
 +
===Availability===
 +
This feature is available free of charge in case your application contributes data to OpenCellID at the same time.<br>
 +
In case you want to use this service without contributing to OpenCellID please refer to <u>[[Commercial_users|the commercial users guideline]]</u>.<br>
 +
An automated check for providing this service to white-listed apiKeys only was activated on Jun 15th, 2014
 +
 
 +
==Getting the number of measurements from a user==
 +
 
 +
GET/POST request to
 +
<pre>
 +
http://<WebServiceURL>/measure/listSize
 +
</pre>
 +
 
 +
===Parameters===
 +
<WebServiceURL>: the URL to the web service
 +
 
 +
===Payload===
 +
key=<apiKey>&format=<format>
 +
 
 +
Where
 +
 
 +
{| class="wikitable sortable" style="font-size: 85%; text-align: left;"
 +
|-
 +
! scope="col" class="unsortable" | Parameter
 +
! scope="col" class="unsortable" | Data type
 +
! scope="col" class="unsortable" | Description
 +
! scope="col" class="unsortable" | Optional
 +
|-
 +
| title="Parameter" | <apiKey>
 +
| title="Data type" | string
 +
| title="Description" | API key assigned to the user
 +
| title="Optional" | no
 +
|-
 +
| title="Parameter" | <format>
 +
| title="Data type" | string
 +
| title="Description" | You can specifiy xml or json as output. Default is xml.
 +
| title="Optional" | yes
 +
|}
 +
 
 +
===Response===
 +
 
 +
====XML====
 +
Upon successful request, HTTP 200 is returned with XML in the following format:
 +
 
 +
<syntaxhighlight lang="xml">
 +
<?xml version="1.0" encoding="UTF-8"?>
 +
<rsp stat="ok">
 +
  <measurements count="123"/>
 +
</rsp>
 +
</syntaxhighlight>
 +
 
 +
====JSON====
 +
<syntaxhighlight lang="javascript">
 +
{
 +
  "count": 5
 +
}
 +
</syntaxhighlight>
 +
 
 +
===Business logic===
 +
The request is handled by de.enaikoon.gpssuite.web.measure.MeasureController.
 +
 
 +
===Example===
 +
<u>http://www.opencellid.org/measure/listSize?key=xxx</u>
 +
 
 +
===Availability===
 +
This feature is available free of charge in case your application contributes data to OpenCellID at the same time.<br>
 +
In case you want to use this service without contributing to OpenCellID please refer to <u>[[Commercial_users|the commercial users guideline]]</u>.<br>
 +
An automated check for providing this service to white-listed apiKeys only was activated on Jun 15th, 2014
 +
 
 +
==Check the online status of OpenCellID==
 +
GET/POST request to
 +
<pre>http://<WebServiceURL>/ocid/status</pre>
 +
 
 +
===Parameters===
 +
<WebServiceURL>: the URL to the web service
 +
 
 +
===Response===
 +
Upon successful request, HTTP 200 is returned with JSON in the following format:
 +
<syntaxhighlight lang="javascript">
 +
{"status":"ok"}
 +
</syntaxhighlight>
 +
 
 +
===Business logic===
 +
The request is handled by de.enaikoon.gpssuite.web.ocid.StatusController
 +
 
 +
===Example===
 +
<u>http://opencellid.org/ocid/status</u>
  
*Business logic*
+
-->
The request is handled by @[email protected]
+

Latest revision as of 15:16, 9 November 2021

API

This wiki page describes all available API functions.
Please contact Unwired Labs if you have any suggestions for improvement or bugs to report.

API key

Most of the API calls require an API key. This API key can be obtained by registering here.
All uploaded data will be stored along with this API key. This offers many functions, including the deletion of data from users that provide incorrect data.
It also allows the identification of users that are violating the community server usage policy.

Some smartphone apps also require an API key, for example the Tower Collector.

For those who prefer contributing data to OpenCellID completely anonymously we recommend using the OpenCellID client which does not require an API key for uploading data.

In the examples below "apiKey" is used as a place holder for this parameter.

"changeable" attribute

The meaning of the "changeable" value returned by some methods is the following:

  • some cell positions in the database are precise; for example, the GSM network provider O2 in Germany provides GPS information along with the Cell ID information and software is able to extract this information for OpenCellID.
  • in this case, new measurements for the cell are stored and shown on the map; however, their GPS positions are not used for calculating the GPS position of the cell tower.

changeable=1:
the GPS position of the cell tower has been calculated from all available measurements

changeable=0:
the GPS position of the cell tower is precise; no measurements have been used to calculate it.

Filtering of data

The following filters are currently applied to all incoming data and decide if a measurement is suspicious or valid.
Suspect data is inserted into a database table with suspect data which can be re-examined at a later stage if required.

Parameter Rules
act must be one of supported type:
1xRTT, CDMA, eHRPD, IS95A, IS95B, EVDO_0, EVDO_A, EVDO_B, UMTS, HSPA+, HSDPA, HSUPA, HSPA, LTE, LTECATM, NR, NBIOT, EDGE, GPRS, GSM
MCC must be known in the database
MCC must be in the range of 100 to 999
MNC/SID must be known in the database
MNC must be in the range of 0 to 999 for GSM, UMTS, LTE, NR and NBIOT
MNC/SID must be in the range of 0 to 32767 for CDMA
LAC/TAC/NID must be in the range of 1 to 65535 for all radios except NR, 0 to 16777215 for NR.
CID must be in the range of 1 to 65535 for GSM
CID must be in the range of 1 to 268435455 for UMTS and LTE, 1 to 68719476735 for NR
CID/BID must be in the range 1 to 65535 for CDMA
longitude must be float (not integer)
longitude must be in the range: (-180,0) U (0,180)
longitude must be != 0
latitude must be float (not integer)
latitude must be in the range: (-90,0) U (0,90)
latitude must be != 0
Parameters Rules
MCC,MNC,LAC,CID,longitude,latitude must have unique coordinates for the cell
MCC,longitude,latitude must have coordinates in the home country
MCC,MNC,LAC,CID,longitude,latitude must be closer than 150 km away from the cell (only in case of precise cells)

The following filters are currently applied to optional fields in all incoming data.
If an optional field has invalid value, then only the value is rejected.

Parameter Rules
measured_at must be in one of supported date formats:
- timestamp (milliseconds since 1/1/1970 00:00:00 GMT),
- "yyyy-MM-dd HH:mm:ss",
- "yyyyMMddHHmmss",
- "yyyy-MM-dd HH:mm:ss.SSSZ",
- "yyyy-MM-dd"
signal
Technology Rules
GSM RSSI in dBm in the range of -51 to -113 or ASU in the range of 0 to 31
UMTS RSCP in dBm in the range of -25 to -121 or ASU in the range of -5 to 91
LTE RSRP in dBm in the range of -45 to -137 or ASU in the range of 0 to 95
NR RSRP in dBm in the range of -44 to -140 or ASU in the range of 0 to 97
CDMA RSSI in dBm in the range of -75 to -100 or ASU in the range of 1 to 16
rating must be in metres in the range of 0 to 35000
speed must be in metres/second in the range of 0 to 300
direction must be in the range of 0 to 360
ta only for GSM and LTE; must be in the range of 0 to 63
psc only for UMTS; must be in the range of 0 to 511
pci only for LTE; must be in the range of 0 to 503
txp must be in the range of -200 to 100
tsrf must be in the range of -100 to 100

Payload legend

A typical payload for API requests and Measurement submissions may include some or all of the following parameters:

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
(except CDMA)
<mnc> integer Mobile network code or system identifier no
(except CDMA if sid is provided)
<lac> integer Local area code, tracking area code or network id no
(except CDMA if nid is provided or LTE or NR if tac is provided)
<cellid> integer Cell tower id or base station id no
(except CDMA if bid is provided)
<signal> integer Signal level: either in dBm or as defined in TS 27.007 8.5; both is accepted. yes
<measured_at> date When the measurement was measured.
Supported date formats:
- timestamp (milliseconds since 1/1/1970 00:00:00 GMT)
- "yyyy-MM-dd HH:mm:ss"
- "yyyyMMddHHmmss"
- "yyyy-MM-dd HH:mm:ss.SSSZ"
- "yyyy-MM-dd"
Time zone: UTC
yes
<rating> double GPS quality/accuracy information (metres) yes
<speed> double Speed when creating the measurement, in metres/second yes
<direction> double Heading direction when creating the measurement
(0=north, 90=east)
yes
<act> string Network access type; currently supported:
1xRTT, CDMA, eHRPD, IS95A, IS95B, EVDO_0, EVDO_A, EVDO_B, UMTS, HSPA+, HSDPA, HSUPA, HSPA, TDSCDMA, LTE, LTECATM, NR, NBIOT, EDGE, GPRS, GSM
Technology Type Description
CDMA 1xRTT single-carrier Radio Transmission Technology (2.5G)
CDMA CDMA (includes IS95A, IS95B) Code division multiple access
CDMA eHRPD Enhanced High Rate Packet Data
CDMA EVDO_0 Evolution-Data Optimized Revision 0
CDMA EVDO_A Evolution-Data Optimized Revision A
CDMA EVDO_B Evolution-Data Optimized Revision B
UMTS UMTS UMTS access
UMTS HSPA+ High speed Packet Access
UMTS HSDPA High Speed Downlink Packet Access
UMTS HSUPA High Speed Uplink Packet Access
UMTS HSPA = "HSDPA/HSUPA" = High Speed Packet Access (both downlink and uplink)
UMTS TDSCDMA = "TDSCDMA" = Time Division Synchronous Code Division Multiple Access (TD-SCDMA)
LTE LTE Long term evolution
LTE LTECATM Long term evolution CAT-M network
NR NR New Radio (5G)
NBIOT NBIOT Narrowband IoT
iDEN iDEN Integrated Digital Enhanced Network
GSM EDGE Enhanced Data Rates for GSM Evolution
GSM GPRS GPRS access
yes
<ta> integer Timing advance; only for GSM and LTE yes
<psc> integer Primary scrambling code; only for UMTS and TDSCDMA yes
<tac> integer Tracking area code; only for LTE or NR yes
<pci> integer Physical cell Id; only for LTE or NR yes
<sid> integer System identifier; only for CDMA yes
<nid> integer Network id; only for CDMA yes
<bid> integer Base station id; only for CDMA yes
<devn> string Device name as concatenated strings with the manufacturer and the model name; max 50 characters yes
<txp> integer TX power in dBm yes
<tsrf> integer Temperature in the RF module; in degrees Celsius; only with <txp> parameter yes


Error codes

The following error codes might be returned by OpenCellID services:

Error code HTTP code Description
1 200 Cell not found
2 401 Invalid API key
3 400 Invalid input data
4 403 Your API key must be white listed in order to run this operation. This service is free of charge as long as your application contributes to the OpenCellID project. Should your application meet this requirement, please contact [email protected] for the authorisation of your API key.

For further details please visit:
http://wiki.opencellid.org/wiki/Commercial_users
http://wiki.opencellid.org/wiki/Request_whitelisting

You can alternatively download the entire database here:
http://opencellid.org/downloads/
5 500 Internal server error
6 503 Too many requests. Try later again.
7 429 Daily limit 1000 requests exceeded for your API key.

For further details please visit:
http://wiki.opencellid.org/wiki/Commercial_users

You can alternatively download the entire database here:
http://opencellid.org/downloads/

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>&act=<act>&ta=<ta>&psc=<psc>&tac=<tac>&pci=<pci>&sid=<sid>&nid=<nid>&bid=<bid>&devn=<devn>&txp=<txp>&tsrf=<tsrf>

Where


Response

Upon successful insert, HTTP 200 is returned 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 a Mongo driver.
The user is deduced from the API key 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. This collection currently cannot be accessed. The suspect data is rechecked every now and then after the filters have been updated in order to check if some initially supsect data can be recovered.

Example

http://opencellid.org/measure/add?key=xxx&lat=10.11&lon=11.12&mcc=100&mnc=10&lac=11&cellid=12&rating=10&direction=90&act=GPRS
http://opencellid.org/measure/add?key=xxx&lat=10.11&lon=11.12&mcc=100&mnc=10&lac=11&cellid=12&rating=10.1&direction=90.3&speed=12.3&act=GPRS&ta=3
http://opencellid.org/measure/add?key=xxx&lat=10.11&lon=11.12&mcc=100&mnc=10&lac=11&cellid=12&rating=10.1&direction=90.3&speed=12.3&act=HSPA+&psc=3
http://opencellid.org/measure/add?key=xxx&lat=10.11&lon=11.12&mcc=100&mnc=10&lac=11&cellid=12&rating=10.1&direction=90.3&speed=12.3&act=LTE&pci=3
http://opencellid.org/measure/add?key=xxx&lat=10.11&lon=11.12&mcc=100&mnc=10&tac=11&cellid=12&rating=10.1&direction=90.3&speed=12.3&act=LTE&pci=3
http://opencellid.org/measure/add?key=xxx&lat=10.11&lon=11.12&mcc=100&mnc=10&lac=11&cellid=12&rating=10.1&direction=90.3&speed=12.3&act=1xRTT
http://opencellid.org/measure/add?key=xxx&lat=10.11&lon=11.12&mcc=100&sid=10&nid=11&bid=12&rating=10.1&direction=90.3&speed=12.3&act=1xRTT
http://opencellid.org/measure/add?key=xxx&lat=10.11&lon=11.12&sid=10&nid=11&bid=12&rating=10.1&direction=90.3&speed=12.3&act=eHRPD
http://opencellid.org/measure/add?key=xxx&lat=10.11&lon=11.12&mcc=100&mnc=10&lac=11&cellid=12&act=GSM&devn=Samsung%20GT-S5830L&txp=-45&tsrf=22

Time needed for processing newly uploaded measurements

After uploading new measurements to the OpenCellID community servers they are added to our waiting queues and processed in the background. We aim the real-time processing, but maximum time depends on traffic on OpenCellID servers. Current throughput of our servers is around 15000 measurements per second.

Measurements are processed in 3 steps:

  1. parsing and filtering raw data
  2. updating measurement statistics and storing measurements in the database
  3. updating existing cell towers information or adding new cell towers to the database

Our waiting queues for cell towers and for measurements are independent, so you can see your measurements in the OpenCellID database but related cell towers might be not updated yet. This means that if you upload a measurement of a cell tower that was not in the database before and the waiting queue for cell towers has some data to process, you have to expect some times (usually few minutes) until the queue delivers the newly uploaded cell tower information.

Uploading measurements from a 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,act,ta,psc,tac,pci,sid,nid,bid
100,2,434,9200,9.436598,52.892139,4,1389472208000,5.4,0,0,GPRS,3,,,,,,
100,2,434,9200,9.441658,52.890351,4,1389472225000,20.1,10.4,90.1,HSPA+,,4,,,,,
100,2,434,9200,9.441658,52.890351,4,1389472225000,20.1,10.4,90.1,LTE,,,,4,,,
100,2,,9200,9.441658,52.890351,4,1389472225000,20.1,10.4,90.1,LTE,,,434,4,,,
100,2,432,9200,9.441658,52.890351,4,1389472225000,20.1,10.4,90.1,LTE,,,432,4,,,
100,1234,432,9201,9.441658,52.890351,4,1389472225000,20.1,10.4,90.1,eHRPD,,,,,,,
100,1234,432,9201,9.441658,52.890351,4,1389472225000,20.1,10.4,90.1,eHRPD,,,,,1234,432,9201
100,,,,9.441658,52.890351,4,1389472225000,20.1,10.4,90.1,1xRTT,,,,,1234,432,9201
,,,,9.441658,52.890351,4,1389472225000,20.1,10.4,90.1,eHRPD,,,,,1234,432,9201
...

Column names recognised:
mcc, mnc, lac, cellid, lat, lon, signal, measured_at, rating, speed, direction, act, ta, psc, tac, pci, sid, nid, bid

Maximum file size:
2 MB; upload multiple files if you want to upload more data.

Supplemented by the parameter key=<apiKey> as form POST field, which is the user's API key.


Response

Upon successful insert, HTTP 200 is returned with the string "0,OK".

Business logic

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

cURL command

curl -F "key=apiKey" -F "[email protected]/path/to/file/mydata.csv;type=text/plain" http://opencellid.org/measure/uploadCsv

Time needed for processing newly uploaded measurements

After uploading new measurements to the OpenCellID community servers they are added to our waiting queues and processed in the background. We aim the real-time processing, but maximum time depends on traffic on OpenCellID servers. Current throughput of our servers is around 15000 measurements per second.

Measurements are processed in 3 steps:

  1. parsing and filtering raw data
  2. updating measurement statistics and storing measurements in the database
  3. updating existing cell towers information or adding new cell towers to the database

Our waiting queues for cell towers and for measurements are independent, so you can see your measurements in the OpenCellID database but related cell towers might be not updated yet. This means that if you upload a measurement of a cell tower that was not in the database before and the waiting queue for cell towers has some data to process, you have to expect some times (usually few minutes) until the queue delivers the newly uploaded cell tower information.

FAQ

What does "optional" mean?
"optional" means that this field is not required in the csv file.
Minimal csv file looks as follows:

mcc,mnc,lac,cellid,lon,lat
262,2,434,9200,9.436598,52.892139

What does "Supplemented by the parameter key=<apiKey> as form POST field, which is the user's API key" mean?
This means that the user must send his data (apiKey and csv file) in the same way as from the following form:

<form method="post" action="http://opencellid.org/measure/uploadCsv" enctype="multipart/form-data">
  apiKey: <input type="text" name="key" />
  CSV (max 2MB): <input type="file" name="datafile" />
  <input type="submit" name="upload" value="Upload"/>
</form>

What does the following error mean?

<?xml version="1.0" encoding="UTF-8"?>
<rsp stat="fail"><err info="cell not found" code="1"/></rsp>

This error message means that no cell was found for the given user criteria (mcc-mnc-lac-cid combination was not found in database).

Can I upload CDMA using mcc-mnc-lac-cellid parameters?
Yes, you can use mnc as sid, lac as nid and cellid as bid.

Uploading measurements from a JSON file

POST request to

http://<WebServiceURL>/measure/uploadJson

Parameters

<WebServiceURL>: the URL to the web service

Payload

JSON file (send in datafile parameter) of the following format:

{
    "measurements": [
        {
            "lon": 9.436598,
            "lat": 52.892139,
            "mcc": 100,
            "mnc": 2,
            "lac": 434,
            "cellid": 9200,
            "measured_at": 1389472224000,
            "signal": -80,
            "rating": 5.4,
            "speed": 2.32,
            "direction": 93.22,
            "act": "EDGE",
            "ta": 3
        },
        {
            "lon": 9.441658,
            "lat": 52.890351,
            "mcc": 100,
            "mnc": 2,
            "lac": 3,
            "cellid": 9200,
            "measured_at": 1389472225000,
            "signal": -80,
            "speed": 11.21,
            "act": "HSDPA",
            "psc": 2
        },
        {
            "lon": 9.441658,
            "lat": 52.890351,
            "mcc": 100,
            "mnc": 2,
            "lac": 321,
            "cellid": 9200,
            "measured_at": 1389472226000,
            "signal": -80,
            "rating": 11.21,
            "act": "LTE",
            "pci": 2
        },
        {
            "lon": 9.441658,
            "lat": 52.890351,
            "mcc": 100,
            "mnc": 2,
            "tac": 321,
            "cellid": 9200,
            "measured_at": 1389472227000,
            "signal": -80,
            "act": "LTE"
        },
        {
            "lon": 9.441658,
            "lat": 52.890351,
            "mcc": 100,
            "mnc": 12345,
            "lac": 1,
            "cellid": 2,
            "measured_at": 1389472228000,
            "signal": -80,
            "act": "eHRPD"
        },
        {
            "lon": 9.441658,
            "lat": 52.890351,
            "mcc": 100,
            "sid": 12345,
            "nid": 1,
            "bid": 2,
            "measured_at": 1389472229000,
            "signal": -80,
            "act": "EVDO_0"
        }
    ]
}

Field names recognised:
mcc, mnc, lac, cellid, lat, lon, signal, measured_at, rating, speed, direction, act, ta, psc, tac, pci, sid, nid, bid

Maximum file size:
2 MB; upload multiple files if you want to upload more data.

Supplemented by the parameter key=<apiKey> as form POST field, which is the user's API key.

Response

Upon successful insert, HTTP 200 is returned with application/json content type and following json document as a content: {"code":0,"status":"OK"}

Business logic

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

cURL command

curl -F "key=apiKey" -F "[email protected]/path/to/file/mydata.json;type=text/plain" http://opencellid.org/measure/uploadJson

Time needed for processing newly uploaded measurements

After uploading new measurements to the OpenCellID community servers they are added to our waiting queues and processed in the background. We aim the real-time processing, but maximum time depends on traffic on OpenCellID servers. Current throughput of our servers is around 15000 measurements per second.

Measurements are processed in 3 steps:

  1. parsing and filtering raw data
  2. updating measurement statistics and storing measurements in the database
  3. updating existing cell towers information or adding new cell towers to the database

Our waiting queues for cell towers and for measurements are independent, so you can see your measurements in the OpenCellID database but related cell towers might be not updated yet. This means that if you upload a measurement of a cell tower that was not in the database before and the waiting queue for cell towers has some data to process, you have to expect some times (usually few minutes) until the queue delivers the newly uploaded cell tower information.

FAQ

What does "optional" mean?
"optional" means that this field is not required in the json file.
Minimal json file looks as follows:

{
    "measurements": [
        {
            "lon": 9.436598,
            "lat": 52.892139,
            "mcc": 262,
            "mnc": 2,
            "lac": 434,
            "cellid": 9200
        }
    ]
}

What does "Supplemented by the parameter key=<apiKey> as form POST field, which is the user's API key" mean?
This means that the user must send his data (apiKey and json file) in the same way as from the following form:

<form method="post" action="http://opencellid.org/measure/uploadJson" enctype="multipart/form-data">
  apiKey: <input type="text" name="key" />
  JSON (max 2MB): <input type="file" name="datafile" />
  <input type="submit" name="upload" value="Upload"/>
</form>

What does the following error mean?

<?xml version="1.0" encoding="UTF-8"?>
<rsp stat="fail"><err info="cell not found" code="1"/></rsp>

This error message means that no cell was found for the given user criteria (mcc-mnc-lac-cid combination was not found in database).

Can I upload CDMA using mcc-mnc-lac-cellid parameters?
Yes, you can use mnc as sid, lac as nid and cellid as bid.

Uploading measurements from CLF3 file

POST request to

http://<WebServiceURL>/measure/uploadClf

Parameters

<WebServiceURL>: The URL to the web service

Payload

CLF version 3.0 file (to be sent in datafile parameter) of the following format:

//mcc+mnc;cellid;lac;rnc;lat;lon;ratio;data;rfu
26202;07812;03101;0;45.894375;31.51312;0;City Square;0

Columns are semicolon separated and have the following strict order:
mcc+mnc, lac, cellid, rnc, lat, lon, ratio, data, rfu

There is no header in CLF3 files. Therefore the columns must be provided in the order given above and all values must be there.

You can add comments to CLF3 files.
Comments in CLF3 start with // and extend to the end of the physical line.

Maximum file size:
2 MB; upload multiple files if you want to upload more data.

Supplemented by the parameter key=<apiKey> as form POST field, which is the user's API key

Supported columns:
Column name Data type Description Optional
<mcc+mnc> string Mobile country code and mobile network code no
lac integer Local area code no
cellid integer Cell tower id no
rnc integer Radio network controller;
provide "0", (zero, without the quotation marks) or an empty string in case there is no rnc value.
no
lat double Latitude no
lon double Latitude no
ratio integer Accuracy of the cell coordinates. Use -1 for the exact position. yes
data string Short cell description yes
rfu string Not really used; use 0 if unknown yes

Response

On successful insert return HTTP 200 with the string "0,OK".

Business logic

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

Time needed for processing newly uploaded measurements

After uploading new measurements to the OpenCellID community servers they are added to our waiting queues and processed in the background. We aim the real-time processing, but maximum time depends on traffic on OpenCellID servers. Current throughput of our servers is around 15000 measurements per second.

Measurements are processed in 3 steps:

  1. parsing and filtering raw data
  2. updating measurement statistics and storing measurements in the database
  3. updating existing cell towers information or adding new cell towers to the database

Our waiting queues for cell towers and for measurements are independent, so you can see your measurements in the OpenCellID database but related cell towers might be not updated yet. This means that if you upload a measurement of a cell tower that was not in the database before and the waiting queue for cell towers has some data to process, you have to expect some times (usually few minutes) until the queue delivers the newly uploaded cell tower information.

Getting cell position

GET/POST request to

http://<WebServiceURL>/cell/get

Parameters

<WebServiceURL>: the URL to the web service

Headers

JSON:
Content-Type: application/json;charset=UTF-8

XML:
Content-Type: text/xml;charset=utf-8

AT:
Content-Type: text/plain;charset=utf-8

Payload

key=<apiKey>&mcc=<mcc>&mnc=<mnc>&lac=<lac>&cellid=<cellid>&radio=<radio>&format=<format>

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 or system identifier no
<lac> integer Local area code, tracking area code or network id no
<cellid> integer Cell id or base station id no
<radio> string You can specifiy GSM, UMTS, LTE, NBIOT, NR or CDMA as the radio of returned cell. Otherwise first matched cell will be returned. yes
<format> string You can specifiy xml, at or json as output. Default is xml. yes

Response

XML

Upon successful request, HTTP 200 is returned 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="-81" 
        range="123" 
        samples="13" 
        changeable="1" 
        radio="GSM"/>
</rsp>


<?xml version="1.0" encoding="UTF-8"?>
<rsp stat="ok">
  <cell lat="51.206" 
        lon="20.424" 
        mcc="260" 
        mnc="2" 
        lac="52712" 
        cellid="59350690" 
        averageSignalStrength="-96" 
        range="1234" 
        samples="5" 
        changeable="1" 
        radio="UMTS" 
        rnc="905" 
        cid="40610"/>
</rsp>


<?xml version="1.0" encoding="UTF-8"?>
<rsp stat="ok">
  <cell lat="51.90994" 
        lon="19.505" 
        mcc="260" 
        mnc="6" 
        lac="12" 
        cellid="864246" 
        averageSignalStrength="-100" 
        range="12345" 
        samples="4" 
        changeable="1" 
        radio="LTE" 
        tac="12"/>
</rsp>


<?xml version="1.0" encoding="UTF-8"?>
<rsp stat="ok">
  <cell lat="42.46" 
        lon="-73.245" 
        mcc="310" 
        mnc="119" 
        lac="48" 
        cellid="4127" 
        averageSignalStrength="-90" 
        range="123" 
        samples="5" 
        changeable="1" 
        radio="CDMA" 
        sid="119" 
        nid="48" 
        bid="4127"/>
</rsp>

JSON

{
  "lon": -73.245,
  "lat": 42.46,
  "mcc": 310,
  "mnc": 119,
  "lac": 48,
  "cellid": 4127,
  "averageSignalStrength": -90,
  "range": 123,
  "samples": 5,
  "changeable": true,
  "radio": "CDMA",
  "sid": 119,
  "nid": 48,
  "bid": 4127
}

AT

+Location:42.46,-73.245,1483228800

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://opencellid.org/cell/get?key=xxx&mcc=260&mnc=2&lac=10250&cellid=26511
http://opencellid.org/cell/get?key=xxx&mcc=260&mnc=2&lac=10250&cellid=26511&radio=UMTS
http://opencellid.org/cell/get?key=xxx&mcc=260&mnc=2&lac=10250&cellid=26511&format=json

Availability

This feature is available free of charge in case your application contributes data to OpenCellID at the same time.
In case you want to use this service without contributing to OpenCellID please refer to the commercial users guideline.
An automated check for providing this service to white-listed apiKeys only was activated on Jun 15th, 2014

Getting 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>&radio=<radio>&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 or system identifier; If you want to restrict the result yes
<lac> integer Local area code, tracking area code or network id; If you want to restrict the result yes
<radio> string You can specifiy GSM, UMTS, LTE, NR, NBIOT or CDMA as the radio of returned cells. Otherwise cells with any radios will be returned. 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 specify kml, xml, csv or json as output. Default is kml.
In csv type of output, there is a first line defining the content of the list.
yes

For the total number of cells in a specified area, please use /cell/getInAreaSize (described below).

Response

Upon successful request, HTTP 200 is returned with one of 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="-70" 
        range="123" 
        samples="12" 
        changeable="1" 
        radio="GSM"/>
  <cell lat="52.9463072" 
        lon="9.258809" 
        mcc="262" 
        mnc="2" 
        lac="1434" 
        cellid="17276" 
        averageSignalStrength="-98" 
        range="1234" 
        samples="11" 
        changeable="1" 
        radio="LTE" 
        tac="1434"/>
  <cell lat="52.9367185" 
        lon="9.27343925" 
        mcc="260" 
        mnc="16256" 
        lac="1434" 
        cellid="17272" 
        averageSignalStrength="-93" 
        range="12345" 
        samples="12" 
        changeable="1" 
        radio="CDMA" 
        sid="16256" 
        bid="1434" 
        nid="17272"/>
</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>-73</b><br/>
                            range: <b>123</b><br/>
                            samples: <b>12</b><br/>
                            changeable: <b>1</b><br/>
                            radio: <b>GSM</b><br/>
                            rnc: <b></b><br/>
                            cid: <b></b><br/>
                            tac: <b></b><br/>
                            sid: <b></b><br/>
                            nid: <b></b><br/>
                            bid: <b></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>21.1525</b><br/>
                            mcc: <b>260</b><br/>
                            mnc: <b>2</b><br/>
                            lac: <b>1434</b><br/>
                            cellid: <b>17272</b><br/>
                            averageSignalStrength: <b>-83</b><br/>
                            range: <b>1234</b><br/>
                            samples: <b>11</b><br/>
                            changeable: <b>1</b><br/>
                            radio: <b>LTE</b><br/>
                            rnc: <b></b><br/>
                            cid: <b></b><br/>
                            tac: <b>1434</b><br/>
                            sid: <b></b><br/>
                            nid: <b></b><br/>
                            bid: <b></b>]]>
      </description>
      <Point><coordinates>21.1525,52.9463072,0</coordinates></Point>
    </Placemark>
    <Placemark>
      <name></name>
      <description><![CDATA[lat: <b>53.9367185</b><br/>
                            lon: <b>12.27343925</b><br/>
                            mcc: <b>262</b><br/>
                            mnc: <b>16256</b><br/>
                            lac: <b>1434</b><br/>
                            cellid: <b>17272</b><br/>
                            averageSignalStrength: <b>-91</b><br/>
                            range: <b>12345</b><br/>
                            samples: <b>2</b><br/>
                            changeable: <b>1</b><br/>
                            radio: <b>CDMA</b><br/>
                            rnc: <b></b><br/>
                            cid: <b></b><br/>
                            tac: <b></b><br/>
                            sid: <b>16256</b><br/>
                            nid: <b>1434</b><br/>
                            bid: <b>17272</b>]]>
      </description>
      <Point><coordinates>12.27343925,53.9367185,0</coordinates></Point>
    </Placemark>
    <Placemark>
      <name></name>
      <description><![CDATA[lat: <b>52.1322157</b><br/>
                            lon: <b>21.065345</b><br/>
                            mcc: <b>260</b><br/>
                            mnc: <b>2</b><br/>
                            lac: <b>1434</b><br/>
                            cellid: <b>42042781</b><br/>
                            averageSignalStrength: <b>-89</b><br/>
                            range: <b>1231</b><br/>
                            samples: <b>5</b><br/>
                            changeable: <b>1</b><br/>
                            radio: <b>UMTS</b><br/>
                            rnc: <b>641</b><br/>
                            cid: <b>34205</b><br/>
                            tac: <b></b><br/>
                            sid: <b></b><br/>
                            nid: <b></b><br/>
                            bid: <b></b>]]>
      </description>
      <Point><coordinates>21.065345,52.1322157,0</coordinates></Point>
    </Placemark>
  </Document>
</kml>

CSV

lat,lon,mcc,mnc,lac,cellid,averageSignalStrength,range,samples,changeable,radio,rnc,cid,tac,sid,nid,bid
52.275505,21.016382,260,2,45080,21728,-55,123,2,1,GSM,,,,,,
52.201454,21.065345,260,2,58140,42042781,-59,1234,3,1,UMTS,641,34205,,,,
52.207123,21.029972,260,6,58,119093,-80,122,2,1,LTE,,,58,,,
52.274612,21.034485,260,16256,45,22613,-98,134,2,1,CDMA,,,,16256,45,22613

JSON

{
  "count": 3,
  "cells": [
    {
      "lon": 21.014,
      "lat": 52.278,
      "mcc": 260,
      "mnc": 2,
      "lac": 45080,
      "cellid": 22613,
      "averageSignalStrength": -70,
      "range": 123,
      "samples": 2,
      "changeable": true,
      "radio": "GSM" 
    },
    {
      "lon": 21.04,
      "lat": 52.2234,
      "mcc": 260,
      "mnc": 2,
      "lac": 58140,
      "cellid": 42042781,
      "averageSignalStrength": -90,
      "range": 125,
      "samples": 2,
      "changeable": true,
      "radio": "UMTS",
      "rnc": 641,
      "cid": 34205
    },
    {
      "lon": 21.5604,
      "lat": 52.284,
      "mcc": 260,
      "mnc": 2,
      "lac": 581,
      "cellid": 42048,
      "averageSignalStrength": -90,
      "range": 12345,
      "samples": 9,
      "changeable": true,
      "radio": "LTE",
      "tac": 581
    }
  ]
}

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&lac=45070&limit=4&offset=16&format=kml
http://www.opencellid.org/cell/getInArea?key=xxx&BBOX=52.0,21.0,52.5,21.5&mcc=260&mnc=2&lac=45070&radio=CDMA&limit=4&offset=16&format=json

Availability

This feature is available free of charge in case your application contributes data to OpenCellID at the same time.
In case you want to use this service without contributing to OpenCellID please refer to the commercial users guideline.
An automated check for providing this service to white-listed apiKeys only was activated on Jun 15th, 2014

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>&radio=<radio>&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 or system identifier; If you want to restrict the result yes
<lac> integer Local area code, tracking area code or network id; If you want to restrict the result yes
<radio> string You can specifiy GSM, UMTS, LTE, NR or CDMA as the radio of returned data. Otherwise any cells will be returned. yes
<format> string You can specifiy xml or json as output. Default is xml. yes

Response

Upon successful request, HTTP 200 is returned with XML in the following format:

XML

<?xml version="1.0" encoding="UTF-8"?>
<rsp stat="ok">
  <cells count="5"/>
</rsp>

JSON

{
  "count": 123
}

Business logic

The request is handled by de.enaikoon.gpssuite.web.measure.CellController.

Example

http://www.opencellid.org/cell/getInAreaSize?key=xxx&BBOX=52.0,21.0,52.5,21.5&mcc=260&mnc=2&lac=45070
http://www.opencellid.org/cell/getInAreaSize?key=xxx&BBOX=52.0,21.0,52.5,21.5&mcc=260&mnc=2&lac=45070&radio=CDMA&format=json

Availability

This feature is available free of charge in case your application contributes data to OpenCellID at the same time.
In case you want to use this service without contributing to OpenCellID please refer to the commercial users guideline.
An automated check for providing this service to white-listed apiKeys only was activated on Jun 15th, 2014