Terracoding API
Fast, flexible access to the planet earth coding service at any scale in real-time.
Real-time access to the location demographics
GET
Shows Real-time access to the location demographics and metadata for a geographical location
Headers
x-api-key*
String
Authentication Key
Content Type*
String
Application/json
Request Body
Location*
String
Location String with or without commas
Query Structure
curl --request GET --location
'https://api.ghumelu.com/v2/terracoding/?user.locations=[user's latitude1, user's longitude1|user's latitude2, user's longitude2]&key=[YOUR_API_KEY]'
\
--header 'Authorization: Bearer $BEARER_TOKEN' {
"kind": "ghumelu#TerracodingResponse",
"etag": "g2524LdBjHrCj5tu58udI-LCOU0",
"pageInfo": {
"totalResults": 1,
"resultsPerPage": 5
},
"items": {
"terracoding": [
{
"house_number": {
"status": "false",
"label": "Location's House Number"
},
"street": {
"status": "false",
"label": "Location's Street"
},
"locality": {
"status": "false",
"label": "Location's Locality"
},
"sub-locality": {
"status": "false",
"label": "Location's Sub-Locality"
},
"city": {
"status": "true",
"label": "Location's City"
},
"state": {
"status": "true",
"label": "Location's State"
},
"country": {
"status": "true",
"label": "Location's Country"
},
"pincode": {
"status": "true",
"label": "Location's Pincode"
},
"continent": {
"status": "true",
"label": "Location's Continent"
},
"latitude": {
"status": "true",
"label": "Location's Latitude"
},
"longitude": {
"status": "true",
"label": "Location's Longitude"
},
"address": {
"status": "true",
"label": "Location's Complete Address"
}
}
]
}
}Example
curl -X GET --location --header "Accept:application/json" --header "Content-Type: application/json" -H "Authorization: Bearer <YOUR TOKEN>" -d '{"user.locations": "29.962358,77.539901"}' https://api.ghumelu.com/v2/terracoding{"kind":"ghumelu#TerracodingAPIResponse","etag":"39d03fbc985d79eb0bfb9363e76-71f85","pageInfo":{"totalResults":1,"resultsPerPage":1},"items":{"terracoding":[{"house_number":{"status":"false","label":""},"street":{"status":"false","label":""},"locality":{"status":"false","label":""},"sub-locality":{"status":"false","label":""},"city":{"status":"true","label":"Saharanpur"},"state":{"status":"true","label":"Uttar Pradesh"},"country":{"status":"true","label":"India"},"pincode":{"status":"true","label":"247001"},"continent":{"status":"true","label":"Asia"},"latitude":{"status":"true","label":"29.962358482278372"},"longitude":{"status":"true","label":"77.5399011821416"},"address":{"status":"true","label":"Saharanpur, Uttar Pradesh, 247001, India"}}]}}Response Overview
Location Components: Contains an array of address components with a json object containing
{
"componentType": "city",
"confirmationLevel": "CONFIRMED"
}where "componentType" is the name of the component found in the address. where "confirmationLevel" can be confirmed or unconfirmed.
Note:
Component is Confirmed is when the value of the component found has been confirmed by Ghumelu Component is Unconfirmed is when the value of the component found cannot be confirmed by Ghumelu
Missing Components: Contains an array of string, mentions the components not found. Possible Values are
House number
Street
Locality or Sub-locality or micro-locality
Pincode
Note:
Locality or Sub-locality is a single category. If any of these is present, we don't consider any missing. If all are missing we should show Locality as missing
Address Score: Score to rate the completeness of the address (Value Range - 0-100).
Address Length: Length of the address after processing.
Redundancy Score: Measure amount of repetitions in the address. Lower the better.
Address Syntactical: Measure to indicate grammatical, syntactical correctness of the address. Higher the better.
Input Granularity: The granularity of the input address. This is the result of parsing the input address and does not give any validation signals.
Validation Granularity: The granularity level that the API can fully validate the address to.
Multiple City Count: Indicates the presence of multiple cities in the address. Ideal is 1. Higher is worse.
Get your API key
All API requests are authenticated using API key. Any request that doesn't include an API key will return an error.
You can get an API key from your https://developers.ghumelu.com/ dashboard to get started.
Last updated