Combain Location API

CPS - The Combain Location Service

Welcome to Combain Location API, see how it works here. We are backward compatible with other geolocation APIs such as Google, Mozilla Location Service and others. Switching to Combain Location API (CPS) is easy, just change to your API key and URL as described below. For full Combain Location API features like fallback control you should consult this API documentation.

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 utilizes both WiFi and Bluetooth beacons. If you are interested in enhancing your indoor location accuracy, we have the tools in our Combain Indoor Suite. Contact us for more information.

To minimize transfered data, use our original HTTP GET CPS API, often refered to as v1. Click here for the v1 specification, CPS Original API specification.

Try it out

Below are different example requests for Cell, WiFi and Bluetooth positioning. Click through the list and find your use case. Leaving the API Key field blank will show example requests.

To make requests using your own API key paste in your API key and your request data, in the same format as the examples. Descriptions of different key-value pairs are described below.

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" : "application/json" }
conn = HTTPSConnection("apiv2.combain.com")
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 Endpoint

API requests should use the following endpoint:

https://apiv2.combain.com
Method: POST
Content-Type: application/json

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

You must replace YOUR_API_KEY with your personal API key.

Best Practices

Avoid unnecessary requests – if you receive response 404: “notFound”, then the cell or wifi does not exist in our database. In that cas we suggest waiting 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 or on your own servers, for up to normally seven days. Check your license agreement for how long caching period you are allowed to have. Multi cell requests are hard to cache since neighboring cells and signal strength are never the same, and you will always get better quality of data if you request the API since locations and accuracy figures are continuously updated in the online database.

Avoid infinite loops – avoid unnecessary server load by making sure your code handles unsuccessful result from the Combain server without retrying the exact same request again.

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 send all availible data, including neighboring cells and WiFis and Bluetooth beacons in same request. If the WiFi or Bluetooh fails, then the cell may serve as a fallback.

Request and Response

Request Parameters

Only the API key is required for a succesful post. Id and nr are both optional 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

Depending on your devices capabilities and use case you can select to send many different types of sensor data and settings. If your device has GPS it's advised to always include it.

Positioning Information

Parameter	Required	Type	Description
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.
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 successful requests.
fallbacks	false	object	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.

Advanced Positioning Information

Parameter	Required	Type	Values	Default	Description
sensors	false	array			An array of sensor parameters to improve positioning accuracy.

Address Information

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.
address	false	integer	0..1	Depending on key setting	If set to 1 a reverse geocode lookup will be made on the calculated location. If successful the address information will be returned in the response. A successful response will count as an extra request.
indoor	false	integer	0..1	Depending on key setting	Ask for indoor information in the response. If information is found and provided it will be counted as an extra request.

Settings and Filters

Parameter	Required	Type	Values	Default	Description
lastLocation	false	object			A previously known location to be used for speed filtering.
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.
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.
speedLimit	false	decimal		Depending on key setting	Override speedLimit set on the key to the provided value (m/s).

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.
ratf	falase	integer	0..1	If the cell is not found search different radio types.
cidf	false	integer	0..1	If the cell is not found, search with just MCC, MNC, CID.

Successful Response

The 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. See below for details.
accuracy	integer	The accuracy is the estimated median error in meters, i.e. the radius in a circle with 50% confidence level.
heading	decimal	Heading for GPS location if available
altitude	decimal	Altitude for GPS location if available
speed	decimal	Speed for GPS location if available (m/s).
calculatedSpeed	integer	Calculated speed between this and previous location (m/s).
geoname	array	If geoname is set in the request the geoname object will be returned if available. See below for details.
indoor	array	If indoor is set in the request the indoor object will be returned if available. See below for details.
address	array	If address is set in the request the address object will be returned if available. See the Reverse Geocoding for example of possible address fields.
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.

Location

The location object contains the following fields.

Parameter	Type	Description
lat	decimal	The latitude of the estimated location.
lng	decimal	The longitude of the estimated location.

Geoname

The geoname object can contain the following fields.

Parameter	Type	Description
town	string	Town of the location.
country	string	Country of the location.
country_code	string	Country code of the location according to ISO 3166.

Indoor

The indoor object can contain the following fields.

Parameter	Type	Description
buildingModelId	integer	The ID of the building model used to calculate the location.
buildingId	integer	The ID of the building that the used building model belongs to.
building	string	The name of the building that the used building model belongs to.
floorIndex	integer	The index of the calculated floor if available. 0 means ground level.
floorLabel	string	The name of the calculated floor if available.
room	string	The name of the calculated room if available.

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.

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	true	integer	0..999	The Mobile Network Code (MNC).
locationAreaCode	true	integer	0..65535	The Location Area Code (LAC).
cellId	true	integer	0..65535	The Cell ID (CID).
signalStrength	recommended	integer	-120--25	The measured signal strength for this cell tower in dBm.
timingAdvance	recommended	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	false	integer	0..999	The Mobile Country Code (MCC).
mobileNetworkCode	true	integer	0..32767	The SystemID (SID).
locationAreaCode	recommended	integer	0..65535	The Network ID (NID).
cellId	true	integer	0..65535	The Basestation ID (BID).
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	true	integer	0..999	The Mobile Network Code (MNC).
locationAreaCode	recommended	integer	0..65535	The Location Area Code (LAC).
cellId	true	integer	0..268435455	The Cell ID (CID). Required at least once in a request including neighbouring cells.
signalStrength	recommended	integer	-130--25	The measured signal strength for this cell tower in dBm.
primaryScramblingCode	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	true	integer	0..999	The Mobile Network Code (MNC).
locationAreaCode	recommended	integer	0..65535	The Location Area Code (LAC).
cellId	true	integer	0..268435455	The Cell ID (CID). Required at least once in a request including neighbouring cells.
signalStrength	recommended	integer	-140--25	The measured signal strength for this cell tower in dBm.
primaryScramblingCode	recommended	integer	0..511	The primary scrambling code for WCDMA and physical CellId for LTE.
timingAdvance	recommended	integer	0..1282	The timing advance value for this cell tower when available in units of 16Ts (see 3GPP TS 36.213 Section 4.2.3).
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	true	integer	0..999	The Mobile Network Code (MNC).
locationAreaCode	recommended	integer	0..65535	The Location Area Code (LAC).
cellId	true	integer	0..268435455	The Cell ID (CID). Required at least once in a request including neighbouring cells.
signalStrength	recommended	integer	-140--25	The measured signal strength for this cell tower in dBm.
primaryScramblingCode	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)

A sample request for positioning with NR (5G):

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

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	true	integer	0..999	The Mobile Network Code (MNC).
locationAreaCode	recommended	integer	0..65535	The Location Area Code (LAC).
cellId/newRadioCellId	true	integer	0..68719476735	The Cell ID (CID). Required at least once in a request including neighbouring cells.
signalStrength	recommended	integer	-140--25	The measured signal strength for this cell tower in dBm.
primaryScramblingCode	recommended	integer	0..1023	The primary scrambling code for WCDMA and physical CellId for LTE.
timingAdvance	recommended	integer	0..3938304	The timing advance value for this cell tower when available in units of Tc (see 3GPP TS 38.213 Section 4.2).
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 and Bluetooth Parameters

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.
ssidHex	recommended	string		The SSID of the Wifi network in a hex string format. Each byte of the SSID is represented by two HEX characters.
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

A sample request for positioning with iBeacon UUID, major and minor:

curl "https://apiv2.combain.com?key=YOUR_API_KEY&id=12345678" \
    -X POST                                \
    -H "Content-Type: application/json"    \
    -d '{
  "bluetoothBeacons": [
    {
      "uuid": "E2C56DB5-DFFB-48D2-B060-D0F5A71096E0",
      "major": 253,
      "minor": 7435,
      "signalStrength": -80
    },
    {
      "uuid": "E2C56DB5-DFFB-48D2-B060-D0F5A71096E0",
      "major": 253,
      "minor": 7438,
      "signalStrength": -80
    }
  ]
}'

There are 2 ways to identify Bluetooth beacons for positioning: macAddress or for iBeacons: UUID,major,minor

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.

GPS and Sensor Parameters

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.

LastLocation Parameters

Used to send a previously known location of the devices to be used for speed filtering.

Parameter	Required	Type	Values	Description
lat	true	decimal	-90..90	The last known latitude.
lng	true	decimal	-180..180	The last known longitude
accuracy	true	integer	0..255	The accuracy of last known location in meters.
timestamp	true	integer/string	timestamp/date	Unix timestamp or date in RFC3339/ISO8601 format for example "2006-01-02T15:04:05Z" .

Sensor Parameters

These parameters are only used in indoor positioning mode with continuous tracking mode (max every 5s). Contact Combain support for details.

Parameter	Required	Type	Values	Description
pressure	false	integer		The ambient air pressure in hPa or mbar. Normally 1013 at sea level.
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	0..359	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.

Reverse Geocoding

API endpoint

A sample request:

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

$apiKey = "YOUR_API_KEY";

// Make request to server
$c = curl_init("https://apiv2.combain.com/reverse?key=$apiKey&lat=55.717569&lon=13.213676");
curl_setopt_array($c, array(
    CURLOPT_RETURNTRANSFER => TRUE
));
$response = curl_exec($c);
if ($response === FALSE) {
    die(curl_error($c));
}

// Decode result
var_dump(json_decode($response, true));

from http.client import HTTPSConnection
import json

apiKey = "YOUR_API_KEY"

conn = HTTPSConnection("apiv2.combain.com")
conn.request("GET", "/reverse?key="+apiKey+"&lat=55.717569&lon=13.213676")
response = conn.getresponse()
result = json.load(response)

print(result)

$.getJSON(
    "https://apiv2.combain.com/reverse?key=YOUR_API_KEY&lat=55.717569&lon=13.213676", 
    function (data){
        console.log(data);
    }
);

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

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

You must replace YOUR_API_KEY with your personal 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.

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

Forward Geocoding

API endpoint

A sample request:

curl "https://apiv2.combain.com/search?key=YOUR_API_KEY&q=Ideon%2CGateway"

$apiKey = "YOUR_API_KEY";

// Make request to server
$c = curl_init("https://apiv2.combain.com/search?key=$apiKey&q=Ideon%2CGateway");
curl_setopt_array($c, array(
    CURLOPT_RETURNTRANSFER => TRUE
));
$response = curl_exec($c);
if ($response === FALSE) {
    die(curl_error($c));
}

// Decode result
var_dump(json_decode($response, true));

from http.client import HTTPSConnection
import json

apiKey = "YOUR_API_KEY"

conn = HTTPSConnection("apiv2.combain.com")
conn.request("GET", "/search?key="+apiKey+"&q=Ideon%2CGateway")
response = conn.getresponse()
result = json.load(response)

print(result)

$.getJSON(
    "https://apiv2.combain.com/search?key=YOUR_API_KEY&q=Ideon%2CGateway", 
    function (data){
        console.log(data);
    }
);

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

API requests should use the following endpoint:

https://apiv2.combain.com/search
Method: GET

Authentication

Combain Forward 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 Forward 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/search?key=YOUR_API_KEY

You must replace YOUR_API_KEY with your personal API key.

Request Parameters

Parameter	Required	Type	Description
key	true	string	The unique key for the account, received from Combain.
q	true	string	The search string.

Successful Response

The above request returns a JSON structure like this:

[
  {
    "boundingbox": [
      "55.7173367",
      "55.7178233",
      "13.2134434",
      "13.2142254"
    ],
    "category": "building",
    "display_name": "Ideon Gateway, 27, Scheelevägen, Ideon Pålsjö, Norr, Lund, Lunds kommun, Skåne län, 22370, Sverige",
    "importance": 0.353150759043076,
    "lat": "55.717575350000004",
    "licence": "Data © OpenStreetMap contributors, ODbL 1.0. https://osm.org/copyright",
    "lon": "13.21384294598949",
    "osm_id": 154029218,
    "osm_type": "way",
    "place_id": 137767568,
    "place_rank": 30,
    "type": "office"
  }
]

[
  {
    "boundingbox": [
      "55.7173367",
      "55.7178233",
      "13.2134434",
      "13.2142254"
    ],
    "category": "building",
    "display_name": "Ideon Gateway, 27, Scheelevägen, Ideon Pålsjö, Norr, Lund, Lunds kommun, Skåne län, 22370, Sverige",
    "importance": 0.353150759043076,
    "lat": "55.717575350000004",
    "licence": "Data © OpenStreetMap contributors, ODbL 1.0. https://osm.org/copyright",
    "lon": "13.21384294598949",
    "osm_id": 154029218,
    "osm_type": "way",
    "place_id": 137767568,
    "place_rank": 30,
    "type": "office"
  }
]

[
  {
    "boundingbox": [
      "55.7173367",
      "55.7178233",
      "13.2134434",
      "13.2142254"
    ],
    "category": "building",
    "display_name": "Ideon Gateway, 27, Scheelevägen, Ideon Pålsjö, Norr, Lund, Lunds kommun, Skåne län, 22370, Sverige",
    "importance": 0.353150759043076,
    "lat": "55.717575350000004",
    "licence": "Data © OpenStreetMap contributors, ODbL 1.0. https://osm.org/copyright",
    "lon": "13.21384294598949",
    "osm_id": 154029218,
    "osm_type": "way",
    "place_id": 137767568,
    "place_rank": 30,
    "type": "office"
  }
]

[
  {
    "boundingbox": [
      "55.7173367",
      "55.7178233",
      "13.2134434",
      "13.2142254"
    ],
    "category": "building",
    "display_name": "Ideon Gateway, 27, Scheelevägen, Ideon Pålsjö, Norr, Lund, Lunds kommun, Skåne län, 22370, Sverige",
    "importance": 0.353150759043076,
    "lat": "55.717575350000004",
    "licence": "Data © OpenStreetMap contributors, ODbL 1.0. https://osm.org/copyright",
    "lon": "13.21384294598949",
    "osm_id": 154029218,
    "osm_type": "way",
    "place_id": 137767568,
    "place_rank": 30,
    "type": "office"
  }
]

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

Error Codes

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.
500	Internal Server Error -- What did you do!?

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.

Version history

Version	Date	Description
2.3.8	2025-02-04	Algorithm updates and performance improvements.
2.3.7	2025-01-17	Algorithm updates and bug fixes.
2.3.6	2024-12-16	Algorithm updates.
2.3.5	2024-11-19	Support for AI Outdoor.
2.3.4	2024-08-27	Bug fixes and algorithm updates.
2.3.3	2024-06-25	Bug fixes.
2.3.2	2024-05-10	Document structure changes and examples updates
2.3.1	2024-04-02	Algorithm updates.
2.3.0	2024-02-22	Algorithm updates.
2.2.9	2024-02-07	Improved speed filter algorithms.
2.2.8	2023-12-11	Improved algorithms and syncing for OnPrem location servers.
2.2.7	2023-11-20	Improved algorithms and added support for NB-IOT and NR for original API format.
2.2.6	2023-01-31	Improved cell fallbacks and added support for newRadioCellId.
2.2.5	2022-11-21	Improved indoor building selection algorithms.
2.2.4	2022-11-11	Added lastLocation and improved indoor algorithms.
2.2.3	2022-09-13	Added forward geocoding, indoor and address parameters.
2.2.2	2022-08-23	Key handling fixes, improved server status, added calculatedSpeed to response and using speedFilter on GPS.
2.2.1	2022-06-22	Lookup TPS optimization, added reporting of server status.
2.2.0	2022-05-05	Syncing and logging optimization.
2.1.9	2022-03-28	Do not return floor as -99 (unknown).
2.1.8	2022-03-02	Added location source, logging updates and improved error handling.
2.1.7	2022-03-02	Added location sources.
2.1.6	2022-02-24	Performance, speed filter, fallback and location source updates.
2.1.3	2021-09-28	Minor updates and bug fixes
2.1.2	2021-08-18	Internal release
2.1.1	2021-04-14	Internal release
2.1.0	2021-01-15	Added iBeacon location support
2.0.9	2021-01-04	Default country check for cell id lookups
2.0.8	2020-12-07	Added NR(5G) and NB-IoT support