NAV
shell php python javascript

Combain Location API

Welcome to Combain Location API. See how it works If you have already implemented any other geolocation API (Google, Mozilla Location Service, etc), we are backward compatible with these. Thus to switch to Combain Location API just change to your key and url and it will work! However, you will not get all Combain Location API features like fallback control etc.

NOTE: Our WiFi positioning service for outdoor wide area positioning for new customers via prepaid credits has been discontinued. Please contact us for more information if you are interested in such WiFi positioning service.

Our Combain indoor location service using both WiFi and Bluetooth beacons is included in our Combain Location API. If you are interested in enhancing your indoor location accuracy and get floor level, we have the tools in our Combain Indoor Suite. Contact us for more information.

If you want to minimize transfered data, we still support our original HTTP GET CPS API. Here is the specification CPS Original API spec.

Try it out

API endpoint

A sample request:

curl "https://apiv2.combain.com?key=YOUR_API_KEY&id=12345678" \
    -X POST                                \
    -H "Content-Type: application/json"    \
    -d '{
    "radioType": "gsm",
    "cellTowers": [{
        "mobileCountryCode": 240,
        "mobileNetworkCode": 1,
        "locationAreaCode": 3012,
        "cellId": 11950,
        "signalStrength": -64
    }]
}'
<?php

$apiKey = "YOUR_API_KEY";
$data = array(
    "radioType" => "gsm",
    "cellTowers" => array(
        array(
            "mobileCountryCode" => 240,
            "mobileNetworkCode" => 1,
            "locationAreaCode" => 3012,
            "cellId" => 11950,
            "signalStrength" => -64
        )
    )
);

// Make request to server
$c = curl_init("https://apiv2.combain.com?key=$apiKey");
curl_setopt_array($c, array(
    CURLOPT_POST => TRUE,
    CURLOPT_RETURNTRANSFER => TRUE,
    CURLOPT_HTTPHEADER => array('Content-Type: application/json'),
    CURLOPT_POSTFIELDS => json_encode($data)
));
$response = curl_exec($c);
if ($response === FALSE) {
    die(curl_error($c));
}

// Decode result
$result = json_decode($response, true);
if (isset($result['location'])) {
    print "Returned location: ".$result['location']['lat'].", ".$result['location']['lng'];
} else {
    print "The following error occurred: ".$result['error']['message'];
}

?>
from http.client import HTTPSConnection
import json

apiKey = "YOUR_API_KEY"

data = {
    "radioType": "gsm",
    "cellTowers": [{
        "mobileCountryCode": 240,
        "mobileNetworkCode": 1,
        "locationAreaCode": 3012,
        "cellId": 11950,
        "signalStrength": -64
    }]
}
headers = { "Content-Type" : "text/json" }
conn = HTTPSConnection("apiv2.combain.com",443)
conn.request("POST", "/?key="+apiKey, json.dumps(data), headers)
response = conn.getresponse()
result = json.load(response)

if ("location" in result):
    print("Returned location: "+str(result['location']['lat'])+", "+str(result['location']['lng']))
else:
    print("The following error occurred: "+result['error']['message'])
var settings = {
  "async": true,
  "crossDomain": true,
  "url": "apiv2.combain.com",
  "method": "POST",
  "headers": {},
  "processData": false,
  "data": "{\"key\": \"YOUR_API_KEY\",\"radioType\": \"gsm\",\"cellTowers\": [{\"mcc\": 240,\"mnc\": 1,\"lac\": 3012,\"cid\": 11950},\"signalStrength\": -64]}"
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

Make sure to replace YOUR_API_KEY with your own valid API key.

API requests should use the following endpoint:

https://apiv2.combain.com

Method: POST

Content-Type: application/json

NOTE: Always use HTTPS for all interactions with the API.

Authentication

Combain Location API uses an API key as a request parameter to allow access to the API. You can register for a new free test key here.

Combain Location API expects for the API key to be included in all API requests to the server in a the url that looks like the following:

https://apiv2.combain.com?key='YOUR_API_KEY

Request Parameters

Parameter Required Type Description
key true string The unique key for the account, received from Combain.
id false string A unique device id. Used for per-device plans and outlier filtering. Important to be truly unique for the account, otherwise requests may not receive correct position. Max 20 characters in length.
nr false integer Request number set by the device. First request should have 1 and then value should be increased by 1 for each request. Helps to identify correct response to a request if a delay in network or lookup.

Request body

Parameter Required Type Values Default Description
geoname false integer 0..1 0 Request name of location. Disregarded if omitted or 0. If set to 1, the city, country and country code information will be returned in the geoname parameter array in the response.
credits false integer 0..1 0 Request number of credits left for prepaid keys. Disregarded if omitted or 0. If set to 1, the number of credits will be returned in the credit parameter in the response.
cellTowers false array An array of all cell towers. There is no limit on the number of towers, send as many as possible.
wifiAccessPoints false array An array of wifi access points (APs). There is no limit on the number of APs, send as many as possible.
bluetoothBeacons false array An array of bluetooth beacons. There is no limit on the number of beacons, send as many as possible.
sensors false array An array of sensor parameters to improve positioning accuracy.
fallbacks false array Fallback solutions. The request will check different fallback solutions to create a position if none of the submitted cells or wifis are found. These parameters should be used with care since it could potentially return wrong coordinates.
state false string A state parameter that was returned in last request for the specific device id. Improves indoor positioning and enables speed filter that can be set on the key to avoid large errors.
gps false array Latest GPS information. Improves positioning requests with latest GPS position, for example indoor where latest GPS position is normally at the door of the building. If GPS position is older than 600s, it does not add any value and should be omitted. GPS object is also used for contributing to database if age=0 and there is at least one cell or one wifi included. Contributions are not calculated as succesful requests.

Cell Parameters

GSM cells (2G, GSM, EDGE, GPRS)

Parameter Required Type Values Description
radioType recommended string gsm The radio type of this cell tower. Can also be put directly in root JSON element if all cellTowers have same radioType.
mobileCountryCode true integer 0..999 The Mobile Country Code (MCC).
mobileNetworkCode recommended integer 0..999 The Mobile Network Code (MNC) for GSM,WCDMA, LTE, NBIOT and NR(5G). The SystemID (sid) for CDMA.
locationAreaCode recommended integer 0..65535 The Location Area Code (LAC) for GSM,WCDMA, LTE, NBIOT and NR(5G). The Network ID for CDMA
cellId true integer 0..65535 The Cell ID (CID) for GSM, WCDMA, LTE, NBIOT and NR(5G). The Basestation ID for CDMA.
signalStrength recommended integer -120--25 The measured signal strength for this cell tower in dBm.
timingAdvance false integer 0..63 The timing advance value for this cell tower when available.
serving false integer 0..1 Specify with 0/1 if the cell is serving or not. If not specified, the first cell in the array is assumed to be serving.

CDMA cells (CDMA, 1xRTT, EVDO)

Parameter Required Type Values Description
radioType recommended string cdma The radio type of this cell tower. Can also be put directly in root JSON element if all cellTowers have same radioType.
mobileCountryCode true integer 0..999 The Mobile Country Code (MCC).
mobileNetworkCode recommended integer 0..32767 The Mobile Network Code (MNC) for GSM,WCDMA, LTE, NBIOT and NR(5G). The SystemID (sid) for CDMA.
locationAreaCode recommended integer 0..65535 The Location Area Code (LAC) for GSM,WCDMA, LTE, NBIOT and NR(5G). The Network ID for CDMA
cellId true integer 0..65535 The Cell ID (CID) for GSM, WCDMA, LTE, NBIOT and NR(5G). The Basestation ID for CDMA.
signalStrength recommended integer -120--25 The measured signal strength for this cell tower in dBm.
serving false integer 0..1 Specify with 0/1 if the cell is serving or not. If not specified, the first cell in the array is assumed to be serving.

WCDMA cells (3G, WCDMA, UMTS, HSPA, HSDPA)

Parameter Required Type Values Description
radioType recommended string wcdma The radio type of this cell tower. Can also be put directly in root JSON element if all cellTowers have same radioType.
mobileCountryCode true integer 0..999 The Mobile Country Code (MCC).
mobileNetworkCode recommended integer 0..999 The Mobile Network Code (MNC) for GSM,WCDMA, LTE, NBIOT and NR(5G). The SystemID (sid) for CDMA.
locationAreaCode recommended integer 0..65535 The Location Area Code (LAC) for GSM,WCDMA, LTE, NBIOT and NR(5G). The Network ID for CDMA
cellId true integer 0..268435455 The Cell ID (CID) for GSM, WCDMA, LTE, NBIOT and NR(5G). The Basestation ID for CDMA.
signalStrength recommended integer -130--25 The measured signal strength for this cell tower in dBm.
psc recommended integer 0..511 The primary scrambling code for WCDMA and physical CellId for LTE.
serving false integer 0..1 Specify with 0/1 if the cell is serving or not. If not specified, the first cell in the array is assumed to be serving.

LTE cells (4G, LTE, CAT-M1, CAT-M2, LTE-M)

Parameter Required Type Values Description
radioType recommended string lte The radio type of this cell tower. Can also be put directly in root JSON element if all cellTowers have same radioType.
mobileCountryCode true integer 0..999 The Mobile Country Code (MCC).
mobileNetworkCode recommended integer 0..999 The Mobile Network Code (MNC) for GSM,WCDMA, LTE, NBIOT and NR(5G). The SystemID (sid) for CDMA.
locationAreaCode recommended integer 0..65535 The Location Area Code (LAC) for GSM,WCDMA, LTE, NBIOT and NR(5G). The Network ID for CDMA
cellId true integer 0..268435455 The Cell ID (CID) for GSM, WCDMA, LTE, NBIOT and NR(5G). The Basestation ID for CDMA.
signalStrength recommended integer -140--25 The measured signal strength for this cell tower in dBm.
psc recommended integer 0..511 The primary scrambling code for WCDMA and physical CellId for LTE.
serving false integer 0..1 Specify with 0/1 if the cell is serving or not. If not specified, the first cell in the array is assumed to be serving.

NB-IoT cells (NB-IoT, CAT-NB1, CAT-NB2)

Parameter Required Type Values Description
radioType recommended string nbiot The radio type of this cell tower. Can also be put directly in root JSON element if all cellTowers have same radioType.
mobileCountryCode true integer 0..999 The Mobile Country Code (MCC).
mobileNetworkCode recommended integer 0..999 The Mobile Network Code (MNC) for GSM,WCDMA, LTE, NBIOT and NR(5G). The SystemID (sid) for CDMA.
locationAreaCode recommended integer 0..65535 The Location Area Code (LAC) for GSM,WCDMA, LTE, NBIOT and NR(5G). The Network ID for CDMA
cellId true integer 0..268435455 The Cell ID (CID) for GSM, WCDMA, LTE, NBIOT and NR(5G). The Basestation ID for CDMA.
signalStrength recommended integer -140--25 The measured signal strength for this cell tower in dBm.
psc recommended integer 0..511 The primary scrambling code for WCDMA and physical CellId for LTE.
serving false integer 0..1 Specify with 0/1 if the cell is serving or not. If not specified, the first cell in the array is assumed to be serving.

NR cells (5G, New Radio)

Parameter Required Type Values Description
radioType recommended string nr The radio type of this cell tower. Can also be put directly in root JSON element if all cellTowers have same radioType.
mobileCountryCode true integer 0..999 The Mobile Country Code (MCC).
mobileNetworkCode recommended integer 0..999 The Mobile Network Code (MNC) for GSM,WCDMA, LTE, NBIOT and NR(5G). The SystemID (sid) for CDMA.
locationAreaCode recommended integer 0..65535 The Location Area Code (LAC) for GSM,WCDMA, LTE, NBIOT and NR(5G). The Network ID for CDMA
cellId true integer 0..68719476735 The Cell ID (CID) for GSM, WCDMA, LTE, NBIOT and NR(5G). The Basestation ID for CDMA.
signalStrength recommended integer -140--25 The measured signal strength for this cell tower in dBm.
psc recommended integer 0..1023 The primary scrambling code for WCDMA and physical CellId for LTE.
serving false integer 0..1 Specify with 0/1 if the cell is serving or not. If not specified, the first cell in the array is assumed to be serving.

WiFi Parameters

NOTE: For privacy issues, at least 2 wifi access points must be submitted in a query to get a location.

Parameter Required Type Values Description
macAddress true string The mac address also called BSSID of the Wifi router.
ssid recommended string The SSID of the Wifi router.
signalStrength recommended integer -100--20 The measured signal strength for the access point in dBm.
frequency false integer The frequency of the WiFi access point in MHz. Improves indoor location accuracy.
channel false integer The channel measured of the WiFi access point.
age false string Time ago the measurement was made in ms.

Bluetooth Parameters

Parameter Required Type Values Description
macAddress true string The mac address of the Bluetooth beacon.
name recommended string The name of the Bluetooth beacon.
signalStrength recommended integer -100--20 The measured signal strength for the bluetooth beacon in dBm.
age false string Time ago the measurement was made in ms.
uuid false string The uuid identifier of the beacon if iBeacon.
major false integer 0..65535 The major identifier of the beacon if iBeacon.
minor false integer 0..65535 The minor idenifier of the beacon if iBeacon.

Sensor Parameters

Parameter Required Type Values Description
pressure false integer The ambient air pressure in hPa or mbar.
steps false integer The number of steps since last request. For best performance use effective number of steps (=distance). Thus if going 4 steps straight and then 3 steps to the right, the effective number of steps are 5.
heading false integer The heading of the movement in degrees.
activity false string The detected activity in an Android device. Valid values are IN_VEHICLE, ON_BICYCLE, ON_FOOT, RUNNING, STILL, TILTING, UNKNOWN and WALKING.

Fallback Parameters

These parameters should be used with care since it could potentially return wrong coordinates. Associative array with values 1 for on and 0 for off. Parameters for turning individual fallbacks on or off:

Parameter Required Type Values Description
all false integer 0..1 Enable/disable all fallbacks for this request. (This does not include cidxf which has to be activated manually.).
w4f false integer 0..1 Used to support mobile units only able to read a 4 CID Hex digits of a WCDMA CID (normally 8 CID Hex digits). Search the CID but just compare the 4 less significant hex digits.
lacf false integer 0..1 If the CID is not found, return the center and accuracy for the LAC.
nbcidf false integer 0..1 Neighbouring CID. If the cells is not found, it will search for a slightly similar CID.
rncidf false integer 0..1 If the cell is not found, search with MCC, MNC, RNCID (first part of CellId).
mncf false integer 0..1 If the MNC is not found, search for just MCC, LAC and CID.

GPS Parameters

Latest GPS information if available. Improves positioning requests with latest GPS position, for example indoor where latest GPS position is normally at the door of the building. If GPS position is older than 600s, it does not add any value and should be omitted. GPS object is also used for contributing to database if age=0 and there is at least one cell or one wifi included. Contributions are not calculated as succesful requests. Note: To be able to contribute for credits your data has to be qualified. Contact support@combain.com to be a qualified data provider and receive free credits.

Parameter Required Type Values Description
latitude true decimal -90..90 The GPS latitude.
longitude true decimal -180..180 The GPS longitude
accuracy true integer 0..255 The GPS accuracy (horizontal, CEP = 50%) in meters.
sat recommended integer 0..20 The number of satellites seen in the measurement.
age recommended integer 0..600 The age of the GPS location (in seconds).
altitude recommended integer -1000..10000 The altitude of the GPS location.
altitudeAccuracy false integer 0..100 The accuracy of the altitude in meters for the GPS location.
heading recommended integer 0..360 The direction (bearing) of movement for the GPS location in degrees.
speed recommended integer 0..100 The speed of the GPS location in m/s.

Successful Response

The above request returns a JSON like this:

{
    "accuracy": 500,
    "location": {
        "lat": 59.331706,
        "lng": 18.079073
    },
    "logId": 1237798
}
{
    "accuracy": 500,
    "location": {
        "lat": 59.331706,
        "lng": 18.079073
    },
    "logId": 1237798
}
{
    "accuracy": 500,
    "location": {
        "lat": 59.331706,
        "lng": 18.079073
    },
    "logId": 1237798
}
{
    "accuracy": 500,
    "location": {
        "lat": 59.331706,
        "lng": 18.079073
    },
    "logId": 1237798
}

If (indoors or speed filter is set on the key) and (an id is set), a state variable is returned. Include this state variable in next request to improve accuracy and enable speed filter.

{
    "accuracy":500,
    "location":{
        "lat":59.331706,
        "lng":18.079073
    },
    "state":"eyJvcyI6MCwiZmkiOjAsImxyIjpbeyJhY2N1cmFjeSI6NTAwLCJsb2NhdGlvbiI6eyJsYXQiOjU5LjMzMTcwNiwibG5nIjoxOC4wNzkwNzN9LCJ0aW1lc3RhbXAiOjE2MDIyNTA4ODMsImdlb25hbWUiOnsidG93biI6IlN0b2NraG9sbSIsImNvdW50cnkiOiJTd2VkZW4iLCJjb3VudHJ5X2NvZGUiOiJTRSJ9fV19",
    "logId":9265772
}

A successful geolocation request will return a JSON-formatted response defining a location and radius.

Parameter Type Description
location array Array of the estimated location of the device in latitude and longitude.
lat decimal The latitude of the estimated location.
lng decimal The longitude of the estimated location.
accuracy integer The accuracy is the estimated median error in meters, i.e. the radius in a circle with 50% confidence level.
geoname array If geoname is set in the request, an array of town, country and country code is returned.
town string Town of the location.
country string Country of the location.
country_code string Country code of the location according to ISO 3166.
fallback string If this field is included no direct match was found. It shows which fallback was used to generate the response.
state string If this field is included, it should preferably be used in next request for the specific device. The parameter includes positioning history that enhances indoor positioning performance and enables speed filter.
logId integer A logId of the request that could be used for debugging purposes. Requests are stored for maximum 7 days currently and can be downloaded in portal.

Errors

An example of a cell not found error:

{
    "error": {
        "errors": [
            {
                "domain": "geolocation",
                "reason": "notFound",
                "message": "Not Found"
            }
        ],
        "code": 404,
        "message": "Not Found"
    },
    "logId": 1247985
}
{
    "error": {
        "errors": [
            {
                "domain": "geolocation",
                "reason": "notFound",
                "message": "Not Found"
            }
        ],
        "code": 404,
        "message": "Not Found"
    },
    "logId": 1247985
}
{
    "error": {
        "errors": [
            {
                "domain": "geolocation",
                "reason": "notFound",
                "message": "Not Found"
            }
        ],
        "code": 404,
        "message": "Not Found"
    },
    "logId": 1247985
}
{
    "error": {
        "errors": [
            {
                "domain": "geolocation",
                "reason": "notFound",
                "message": "Not Found"
            }
        ],
        "code": 404,
        "message": "Not Found"
    },
    "logId": 1247985
}

In the case of an error, a standard format error response body will be returned and the HTTP status code will be set to an error status.

The response contains an object with a single error object:

Parameter Type Description
error array Error element.
errors arrray All the errors that occurred.
domain string The domain of this error.
reason string The type of error.
message string The message for this error.
code integer Error code. 400 = Parse Error / Invalid key. 403 = Out of credits. 404 = Not found / Speed Filter
message string The error message.
logId integer A logId of the request that could be used for debugging purposes. Requests are stored for maximum 7 days currently and can be downloaded in portal.

Best Practices

Avoid unnecessary requests – If you not receive a successful result, you receive message “notFound”, then the cell or wifi does not exist in our database. It makes no sense to send the exact same query directly again. We suggest you wait at least 24h hours before trying the exact same query again. The database grows with around 3 million observations per day.

Avoid unnecessary costs – to avoid unnecessary costs (normally charged per successful request) you are allowed to cache the result from a successful request in your devices and on your own servers, for up to normally seven days. Check your license agreement for how long caching period you are allowed to have. But note, multi cell requests are hard to cache since neighboring cells and signal strength is never the same, and you will always have better quality of data if you request the API since locations and accuracy figures are continuously updated in the online database.

Avoid infinite loops – to avoid unnecessary load on your own servers and on our servers, make sure your code do not end up in an infinite loop if you not receive a successful result from the Combain server.

Be flexible – never hardcode an URL to apiv2.combain.com in any devices you ship to end-customers. The recommendation is that you setup your own subdomain apiv2.yourcompanyname.com that redirects to apiv2.combain.com by using proper DNS settings or by using a relaying server. If you for some reason need to modify your requests to us, and you do not have access to the software in the shipped devices, you can then do that on your own server before sending the requests to us.

Improve accuracy – for best results, make sure you always send all your data, including neighboring cells and WiFis and Bluetooth beacons in same request.

Reverse Geocoding

API endpoint

A sample request:

curl https://apiv2.combain.com/reverse?key=YOUR_API_KEY&lat=55.717569&lon=13.213676



Make sure to replace YOUR_API_KEY with your own valid API key.

API requests should use the following endpoint:

https://apiv2.combain.com/reverse

Method: GET

NOTE: Always use HTTPS for all interactions with the API.

Authentication

Combain Reverse Geocoding API uses an API key as a request parameter to allow access to the API. You can register for a new free test key here.

Combain Reverse Geocoding API expects for the API key to be included in all API requests to the server in a the url that looks like the following:

https://apiv2.combain.com/reverse?key='YOUR_API_KEY

Request Parameters

Parameter Required Type Description
key true string The unique key for the account, received from Combain.
lat true decimal The latitude value in WGS-84 format specifying the location for which you wish to obtain the closest, human-readable address.
lon true decimal The longitude value in WGS-84 format specifying the location for which you wish to obtain the closest, human-readable address.
zoom false integer The level of detail. Zoom value lies between 0-18, where 0 is country and 18 is house/building, default: 18.

Response

The above request returns a JSON structure like this:

{
    "address": {
        "building": "Ideon Gateway",
        "city_block": "Stockholmsledet",
        "city_district": "Norr",
        "country": "Sverige",
        "country_code": "se",
        "county": "Skåne län",
        "house_number": "27",
        "municipality": "Lunds kommun",
        "neighbourhood": "Ideon Pålsjö",
        "postcode": "22370",
        "road": "Scheelevägen",
        "state": "Götaland",
        "town": "Lund"
    }
}
{
    "address": {
        "building": "Ideon Gateway",
        "city_block": "Stockholmsledet",
        "city_district": "Norr",
        "country": "Sverige",
        "country_code": "se",
        "county": "Skåne län",
        "house_number": "27",
        "municipality": "Lunds kommun",
        "neighbourhood": "Ideon Pålsjö",
        "postcode": "22370",
        "road": "Scheelevägen",
        "state": "Götaland",
        "town": "Lund"
    }
}
{
    "address": {
        "building": "Ideon Gateway",
        "city_block": "Stockholmsledet",
        "city_district": "Norr",
        "country": "Sverige",
        "country_code": "se",
        "county": "Skåne län",
        "house_number": "27",
        "municipality": "Lunds kommun",
        "neighbourhood": "Ideon Pålsjö",
        "postcode": "22370",
        "road": "Scheelevägen",
        "state": "Götaland",
        "town": "Lund"
    }
}
{
    "address": {
        "building": "Ideon Gateway",
        "city_block": "Stockholmsledet",
        "city_district": "Norr",
        "country": "Sverige",
        "country_code": "se",
        "county": "Skåne län",
        "house_number": "27",
        "municipality": "Lunds kommun",
        "neighbourhood": "Ideon Pålsjö",
        "postcode": "22370",
        "road": "Scheelevägen",
        "state": "Götaland",
        "town": "Lund"
    }
}

A successful geolocation request will return a JSON-formatted response defining the address at the location.

Errors

In the case of an error, a standard format error response body will be returned and the HTTP status code will be set to an error status.

The response contains an object with a single error object:

Parameter Type Description
error array Error element.
errors arrray All the errors that occurred.
domain string The domain of this error.
reason string The type of error.
message string The message for this error.
code integer Error code. 400 = Parse Error / Invalid key. 403 = Out of credits. 404 = Not found.
message string The error message.
logId integer A logId of the request that could be used for debugging purposes. Requests are stored for maximum 7 days currently and can be downloaded in portal.

Errors

The Combain APIs uses the following error codes:

Error Code Meaning
400 Bad Request -- Your request is invalid. Parse error or invalid key.
403 Forbidden -- Out of credits! Buy more.
404 Not Found -- The location could not be found.