Response
Geolocation response fields, address detail components and metadata returned when enabled.
Sample JSON response:
{
"status":"ok",
"balance":0,
"lat":39.56764454,
"lon":-105.00728197,
"accuracy":10,
"address":"High Line Canal Trail, Littleton, Douglas County, Colorado, 80129, United States of America"
}The response will be a JSON object and may contain the following elements. Every location is calculated from our large, continuously-updated database of cell and WiFi observations - use the accuracy and fallback fields below to gauge confidence in a given result.
| Parameter | Description |
|---|---|
| status | If the request is successful, ok is returned. Otherwise error is returned |
| message | Contains a specific error message when status is error. This field can be used for programmatic error handling. Read more |
| help | When present, may include additional context about errors for informational purposes. This field is provided for human readability and should not be used for programmatic error handling. |
| balance | Approximate remaining balance on the API token. Requests that return error are not charged. Use the balance endpoint for more accurate values. |
| balance_slots | Approximate remaining balance of device slots. Requests that return error are not charged. A value of -1 indicates an error in retrieving the slots balance. Only appears for device plans. |
| lat | The latitude representing the location |
| lon | The longitude representing the location |
| accuracy | The accuracy of the position is returned in meters |
| address | The physical address of the location |
| address_detail | The physical address of the location broken into sub-components. Read more |
| aged | Shown when the location is based on a single measurement or those older than 90 days or is an LAC fallback |
| fallback | Shown when the location is based on a fallback. Possible options include ipf, lacf, scf, cidf, ncf. |
| metadata | An object that contains additional information about the request or response, if any, and is shown when metadata is set to 1 in the request. Read more |
Address Detail
The API only returns components that have valid values for a location. Component town is normalized to city to make things simple. For more granular control, please use our Geocoding service - LocationIQ.
Components that would be returned are:
arealocalitydistrictcountycitystatecountrycountry_codepostal_code
Metadata
When metadata is enabled, the Geolocation API returns additional information about the request or response. For example, when a gps object is sent in the request, the API response will look similar to the example below.
Sample response with the metadata object
{
"status": "ok",
"balance": 266647,
"lat": 39.56764858,
"lon": -105.00733121,
"accuracy": 120,
"metadata": {
"gps": {
"status": "ok",
"gps_sandbox": 0
}
}
}Since the information inside the metadata object primarily contains debug information, its elements may change without notice. We recommend that you program defensively to avoid breaking your program when these values change.