API

From OpenCellID wiki
Revision as of 13:41, 6 July 2014 by Msemm (Talk | contribs)

Jump to: navigation, search

Contents

API

This wiki page describes all available API functions.
Please contact Markus 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.

In the examples below "apiKey" is used 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.
Suspect data is inserted into a database table with suspect data which can be re-examined at a later stage if required.

Parameter Rules
MCC must be known in the database
MCC must be in the range: (100..999)
MNC must be known in the database
MNC must be > 0
LAC must be > 0 and LAC!=2147483647
CID must be > 0 and LAC!=2147483647
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
act 1xRTT, CDMA, eHRPD, EVDO_0, EVDO_A, EVDO_B, UMTS, HSPA+, HSDPA, HSUPA, HSPA, LTE, iDEN, EDGE, GPRS

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 401 Your API key must be whitelisted 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 authorization of your API key.
5 500 Internal server error
6 503 Too many requests. Try later again.

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>

Where

Parameter Data type Description Optional
<apiKey> string API key assigned to the user submitting the measurement no
<lat> double Latitude no
<lon> double Longitude no
<mcc> integer Mobile country code no
<mnc> integer Mobile network code no
<lac> integer Local area code no
<cellid> integer Cell tower id no
<signal> integer Signal level: 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, EVDO_0, EVDO_A, EVDO_B, UMTS, HSPA+, HSDPA, HSUPA, HSPA, LTE, iDEN, EDGE, GPRS
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)
LTE LTE Long term evolution
iDEN iDEN Integrated Digital Enhanced Network
GSM EDGE Enhanced Data Rates for GSM Evolution
GSM GPRS GPRS access
yes

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.

Example

http://www.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

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
262,2,434,9200,9.436598,52.892139,4,1389472208000,5,0,0,GPRS
262,2,434,9200,9.441658,52.890351,4,1389472225000,20,10,90,EDGE
...

Column names recognised:
mcc, mnc, lac, cellid, lat, lon, signal, measured_at, rating, speed, direction, act

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.

Where

Parameter Data type Description Optional
<lat> double Latitude no
<lon> double Longitude no
<mcc> integer Mobile country code no
<mnc> integer Mobile network code no
<lac> integer Local area code no
<cellid> integer Cell tower id no
<signal> integer Signal level; 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, EVDO_0, EVDO_A, EVDO_B, UMTS, HSPA+, HSDPA, HSUPA, HSPA, LTE, iDEN, EDGE, GPRS
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)
LTE LTE Long term evolution
iDEN iDEN Integrated Digital Enhanced Network
GSM EDGE Enhanced Data Rates for GSM Evolution
GSM GPRS GPRS access
yes

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 "datafile=@/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<br>
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" /><br/> 
CSV (max 2MB): 
<input type="file" name="datafile" /><br/> 
<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).

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": 262,
            "mnc": 2,
            "lac": 434,
            "cellid": 9200,
            "measured_at": 1389472208000,
            "signal": -60,
            "rating": 5.4,
            "speed": 2.32,
            "direction": 93.22,
            "act": "EDGE"
        },
        {
            "lon": 9.441658,
            "lat": 52.890351,
            "mcc": 262,
            "mnc": 2,
            "lac": 434,
            "cellid": 9200,
            "measured_at": 1389472225000,
            "signal": -50,
            "rating": 11.21,
            "act": "GPRS"
        }
    ]
}

Fieldbnames recognised:
mcc, mnc, lac, cellid, lat, lon, signal, measured_at, rating, speed, direction, act

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.

Where

Parameter Data type Description Optional
<lat> double Latitude no
<lon> double Longitude no
<mcc> integer Mobile country code no
<mnc> integer Mobile network code no
<lac> integer Local area code no
<cellid> integer Cell tower id no
<signal> integer Signal level; 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, EVDO_0, EVDO_A, EVDO_B, UMTS, HSPA+, HSDPA, HSUPA, HSPA, LTE, iDEN, EDGE, GPRS
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)
LTE LTE Long term evolution
iDEN iDEN Integrated Digital Enhanced Network
GSM EDGE Enhanced Data Rates for GSM Evolution
GSM GPRS GPRS access
yes

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 "datafile=@/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<br>
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" /><br/> 
CSV (max 2MB): 
<input type="file" name="datafile" /><br/> 
<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).

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;00000;45.894375;31.51312;0;City Square;0

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

There is no header, but you can add a comment. 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

Where

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

Payload

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

Where

Parameter Data type Description Optional
<apiKey> string API key assigned to the user no
<mcc> integer Mobile country code no
<mnc> integer Mobile network code no
<lac> integer Local area code no
<cellid> integer Cell tower id no

Response

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="4" samples="13" changeable="1"/>
</rsp>

Business logic

The request is handled by de.enaikoon.gpssuite.web.cell.CellController.
It uses de.enaikoon.m2m.gsmcellmanagment.dao.mongodb.GsmCellDao to calculate the average cell measurement, and builds an XML string to return to the user.

Example

http://www.opencellid.org/cell/get?key=xxx&mcc=260&mnc=2&lac=10250&cellid=26511

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 will be activated on Jun 15th, 2014

Getting the raw measurements used to compute the position of a cell

GET/POST request to 

http://<WebServiceURL>/cell/getMeasures

Parameters

<WebServiceURL>: the URL to the web service

Payload

key=<apiKey>&mcc=<mcc>&mnc=<mnc>&lac=<lac>&cellid=<cellid>&limit=<limit>&offset=<offset>

Where

Parameter Data type Description Optional
<apiKey> string API key assigned to the user no
<mcc> integer Mobile country code no
<mnc> integer Mobile network code no
<lac> integer Local area code no
<cellid> integer Cell tower id no
<limit> integer A number defining max size of the returned list.
Default and max value is 1000. 		yes
<offset> integer The field says to skip that many measurements before beginning to return measurements.
Default is 0. 		yes

For the total number of measurements used to compute the position of a cell, please use /cell/getMeasuresSize (described below).

Response

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

<?xml version="1.0" encoding="UTF-8"?>
<rsp stat="ok">
  <cell lon="9.439112000000002" 
        lat="52.891242" 
        mcc="262" 
        mnc="2" 
        lac="434" 
        cellid="9200" 
        range="0"
        averageSignalStrength="4" 
        samples="3">
    <measure id="52d3db7ccd214d36357b9fee" 
             lat="52.891501" 
             lon="9.438351"
             mcc="262" mnc="2"
             lac="434"
             cellid="9200"
             created_at="1389614776127"
             measured_at="1389477214000"
             signal="4"
             rating="10"
             speed="20"
             direction="90"/>
    <measure id="52d3db7ccd214d36357b9ff2"
             lat="52.890977"
             lon="9.439841"
             mcc="262"
             mnc="2"
             lac="434"
             cellid="9200"
             created_at="1389614776134"
             measured_at="1389477219000"
             signal="4"
             rating="0"
             speed="0"
             direction="0"/>
    <measure id="52d3db7ccd214d36357b9ff6"
             lat="52.890351"          
             lon="9.441658" 
             mcc="262" 
             mnc="2" 
             lac="434" 
             cellid="9200" 
             created_at="1389614776138" 
             measured_at="1389477225000" 
             signal="4" 
             rating="0" 
             speed="0" 
             direction="0"/>
  </cell>
</rsp>

Business logic

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

Example

http://www.opencellid.org/cell/getMeasures?key=xxx&mcc=260&mnc=2&lac=10250&cellid=26511&limit=10&offset=1

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 will be activated on Jun 15th, 2014

Getting the number of all measures used to compute the position of a cell

GET/POST request to 

http://<WebServiceURL>/cell/getMeasuresSize

Parameters

<WebServiceURL>: the URL to the web service

Payload

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

Where

Parameter Data type Description Optional
<apiKey> string API key assigned to the user no
<mcc> integer Mobile country code no
<mnc> integer Mobile network code no
<lac> integer Local area code no
<cellid> integer Cell tower id no

Response

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

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

Business logic

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

Example

http://www.opencellid.org/cell/getMeasuresSize?key=xxx&mcc=260&mnc=2&lac=10250&cellid=26511

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 will be 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>&limit=<limit>&offset=<offset>&format=<format>

Where

Parameter Data type Description Optional
<apiKey> string API key assigned to the user no
<latmin> double Minimal bounding latitude no
<lonmin> double Minimal bounding longitude no
<latmax> double Maximal bounding latitude no
<lonmax> double Maximal bounding longitude no
<mcc> integer Mobile country code; If you want to restrict the result to a specific country yes
<mnc> integer Mobile network code; If you want to restrict the result to a specific operator yes
<lac> integer Local Area Code;If you want to restrict the result to a locale area code yes
<limit> integer A number defining maximum size of the returned list. Default and maximum value is 1000. yes
<offset> integer The field says to skip that many cells before beginning to return cells. Default is 0. yes
<format> string You can specify kml, xml or csv as output. Default is kml.
In CSV type of output, 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="3" 
        samples="12" 
        changeable="1"/>
  <cell lat="52.9463072" 
        lon="9.258809" 
        mcc="262" 
        mnc="2" 
        lac="1434" 
        cellid="17276" 
        averageSignalStrength="3" 
        samples="11" 
        changeable="1"/>
  <cell lat="52.9367185" 
        lon="9.27343925" 
        mcc="262" 
        mnc="2" 
        lac="1434" 
        cellid="17272" 
        averageSignalStrength="3"
        samples="12"
        changeable="1"/>
  <cell lat="52.9322157" 
        lon="9.2847167"
        mcc="262"
        mnc="2"
        lac="1434"
        cellid="29322"
        averageSignalStrength="3"
        samples="5"
        changeable="1"/>
</rsp>

KML (default)

<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://earth.google.com/kml/2.1">
  <Document>
    <name>OpenCellID Cells</name>
    <description>List of available cells</description>
    <Placemark>
      <name></name>
      <description><![CDATA[lat: <b>52.9523755</b><br/>
                            lon: <b>9.252112</b><br/>
                            mcc: <b>262</b><br/>
                            mnc: <b>2</b><br/>
                            lac: <b>1434</b><br/>
                            cellid: <b>17275</b><br/>
                            averageSignalStrength: <b>3</b><br/>
                            samples: <b>12</b><br/>
                            changeable: <b>1</b>]]>
      </description>
      <Point><coordinates>9.252112,52.9523755,0</coordinates></Point>
    </Placemark>
    <Placemark>
      <name></name>
      <description><![CDATA[lat: <b>52.9463072</b><br/>
                            lon: <b>9.258809</b><br/>
                            mcc: <b>262</b><br/>
                            mnc: <b>2</b><br/>
                            lac: <b>1434</b><br/>
                            cellid: <b>17276</b><br/>
                            averageSignalStrength: <b>3</b><br/>
                            samples: <b>11</b><br/>
                            changeable: <b>1</b>]]>
      </description>
      <Point><coordinates>9.258809,52.9463072,0</coordinates></Point>
    </Placemark>
    <Placemark>
      <name></name>
      <description><![CDATA[lat: <b>52.9367185</b><br/>
                            lon: <b>9.27343925</b><br/>
                            mcc: <b>262</b><br/>
                            mnc: <b>2</b><br/>
                            lac: <b>1434</b><br/>
                            cellid: <b>17272</b><br/>
                            averageSignalStrength: <b>3</b><br/>
                            samples: <b>12</b><br/>
                            changeable: <b>1</b>]]>
      </description>
      <Point><coordinates>9.27343925,52.9367185,0</coordinates></Point>
    </Placemark>
    <Placemark>
      <name></name>
      <description><![CDATA[lat: <b>52.9322157</b><br/>
                            lon: <b>9.2847167</b><br/>
                            mcc: <b>262</b><br/>
                            mnc: <b>2</b><br/>
                            lac: <b>1434</b><br/>
                            cellid: <b>29322</b><br/>
                            averageSignalStrength: <b>3</b><br/>
                            samples: <b>5</b><br/>
                            changeable: <b>1</b>]]>
      </description>
      <Point><coordinates>9.2847167,52.9322157,0</coordinates></Point>
    </Placemark>
  </Document>
</kml>

CSV

lat,lon,mcc,mnc,lac,cellid,averageSignalStrength,samples,changeable
52.9523755,9.252112,262,2,1434,17275,3,12,1
52.9463072,9.258809,262,2,1434,17276,3,11,1
52.9367185,9.27343925,262,2,1434,17272,3,12,1
52.9322157,9.2847167,262,2,1434,29322,3,5,1

Business logic

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

Example

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

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 will be 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>

Where

Parameter Data type Description Optional
<apiKey> string API key assigned to the user no
<latmin> double Minimal bounding latitude no
<lonmin> double Minimal bounding longitude no
<latmax> double Maximal bounding latitude no
<lonmax> double Maximal bounding longitude no
<mcc> integer Mobile country code; If you want to restrict the result to a specific country yes
<mnc> integer Mobile network code; If you want to restrict the result to a specific operator yes
<lac> integer Local Area Code;If you want to restrict the result to a locale area code yes

Response

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>

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

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 will be activated on Jun 15th, 2014

Deleting a measurement

POST request to 

http://<WebServiceURL>/measure/delete

Parameters

<WebServiceURL>: the URL to the web service

<id>: ID of the measure to delete

Payload

key=<apiKey>&id=<id>

Where

Parameter Data type Description Optional
<apiKey> string API key assigned to the user no
<id> string ID of the measure to delete no

Response

Upon successful deletion, HTTP 200 is returned with the string "Measurement with id=<id> has been deleted."

Business logic

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

Example

http://www.opencellid.org/measure/delete?key=xxx&id=123abc4567890123abcd1234

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 will be activated on Jun 15th, 2014

Listing a user's measurements

GET request to 

http://<WebServiceURL>/measure/list

Parameters

<WebServiceURL>: the URL to the web service

Payload

key=<apikey>&limit=<limit>&offset=<offset>&format=<format>

Where

Parameter Data type Description Optional
<apiKey> string API key assigned to the user no
<limit> integer A number defining maximum size of the returned list.
Default and maximum value is 1000. 		yes
<offset> integer The field says to skip that many measurements before beginning to return measurements.
Default is 0. 		yes
<format> string You can specify csv, xml or kml as output. Default is csv.
In csv type of output, a first line defining the content of the list. 		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:

CSV (default)

id,mcc,mnc,lac,cellid,lat,lon,created_at,measured_at,signal,rating,speed,direction
5213db7abcda4d36357b9f12,262,2,434,9200,52.892139,9.436598,1311615996112,1311512208000,4,10,10,90
5213db7abcda4d36357b9f15,262,2,1434,17271,52.96261,9.241319,1311615996122,1311511534000,3,20,11,90

XML

<?xml version="1.0" encoding="UTF-8"?>
<rsp stat="ok">
  <measure id="5213db7abcda4d36357b9f12" 
           lat="52.892139" 
           lon="9.436598" 
           mcc="262"
           mnc="2"
           lac="434"
           cellid="9200"
           created_at="1311615996112"
           measured_at="1311512208000"
           signal="4"
           rating="10"
           speed="10"
           direction="90"/>
  <measure id="5213db7abcda4d36357b9f15"
           lat="52.96261"
           lon="9.241319"
           mcc="262"
           mnc="2"
           lac="1434"
           cellid="17271"
           created_at="1311615996122"
           measured_at="1311511534000"
           signal="3"
           rating="20"
           speed="11"
           direction="90"/>
</rsp>

KML

<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://www.opengis.net/kml/2.2">
  <Document>
    <name>OpenCellID measurements</name>
    <description>List of user's measurements</description>
    <Placemark>
      <name></name>
      <description><![CDATA[id: <b>5213db7abcda4d36357b9f12</b><br/>
                            mcc: <b>262</b><br/>
                            mnc: <b>2</b><br/>
                            lac: <b>434</b><br/>
                            cellid: <b>9200</b><br/>
                            lat: <b>52.892139</b><br/>
                            lon: <b>9.436598</b><br/>
                            created_at: <b>1311615996112</b><br/>
                            measured_at: <b>1311512208000</b><br/>
                            signal: <b>4</b><br/>
                            rating: <b>3</b><br/>
                            speed: <b>0</b><br/>
                            direction: <b>0</b>]]>
      </description>
      <Point><coordinates>9.436598,52.892139,0</coordinates></Point>
    </Placemark>
    <Placemark>
      <name></name>
      <description><![CDATA[id: <b>5213db7abcda4d36357b9f15</b><br/>
                            mcc: <b>262</b><br/>
                            mnc: <b>2</b><br/>
                            lac: <b>1434</b><br/>
                            cellid: <b>17271</b><br/>
                            lat: <b>52.96261</b><br/>
                            lon: <b>9.241319</b><br/>
                            created_at: <b>1311615996112</b><br/>
                            measured_at: <b>1311511534000</b><br/>
                            signal: <b>3</b><br/>
                            rating: <b>4</b><br/>
                            speed: <b>0</b><br/>
                            direction: <b>0</b>]]>
      </description>
      <Point><coordinates>9.241319,52.96261,0</coordinates></Point>
    </Placemark>
  </Document>
</kml>

Business logic

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

Example

http://www.opencellid.org/measure/list?key=xxx&limit=2&offset=128&format=xml

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 will be activated on Jun 15th, 2014

Getting the number of measurements from a user

GET/POST request to 

http://<WebServiceURL>/measure/listSize

Parameters

<WebServiceURL>: the URL to the web service

Payload

key=<apiKey>

Where

Parameter Data type Description Optional
<apiKey> string API key assigned to the user no

Response

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

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

Business logic

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

Example

http://www.opencellid.org/measure/listSize?key=xxx

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 will be activated on Jun 15th, 2014

Retrieved from "http://wiki.opencellid.org/index.php?title=API&oldid=3099"