Geocode API

Transform ambiguous physical addresses, landmarks, and street descriptions into pinpoint spatial coordinates to power accurate mapping, routing, and dispatching.

Where it's used

Use cases, value and how it works

Overview & Solution

Addresses across rapidly growing urban centers and rural territories are often unstructured, inconsistent, or lack standardized numbering. The Geocode API provides intelligent natural language parsing, address normalization, and spatial indexing to convert raw text into exact latitude and longitude coordinates.

Key Value Propositions

Sub-Second Geocoding: Optimized for high-throughput enterprise pipelines during customer onboarding and checkout flows.

Industry Use Cases

1. E-Commerce & Last-Mile Delivery

Instant Address Verification: Validate delivery addresses at the time of checkout to prevent costly returns and failed delivery attempts (RTO).
Driver Dispatch Preparation: Ensure delivery drivers receive accurate coordinates directly navigating them to the customer doorstep.

2. Banking, Insurance & FinTech

KYC & Customer Verification: Pinpoint customer residence and commercial premises to fulfill regulatory Know-Your-Customer (KYC) location checks.
Property Risk & Underwriting: Identify exact geographic positions of collateral or insured properties to evaluate flood and catastrophe risks.

3. Telecom & Utility Services

Service Feasibility Checks: Determine whether a prospective broadband, fiber, or utility subscriber is within coverage reach of existing line infrastructure.

How Intelomatic Solves Address Ambiguity

Input Parsing: Deconstructs raw address strings into building, street, sub-locality, locality, city, state, and postal code.
Graph Matching: Evaluates candidates against Intelomatic's comprehensive geographic database of millions of verified POIs and road networks.
Structured Output: Delivers precise coordinates alongside complete administrative metadata for downstream workflows.

API reference

note

Typeahead suggestion (Geocode Suggest) is part of the same service, so it is documented here.

Geocode API

Location and Address Intelligence APIs · API key only

Converts an address, landmark or place name into latitude/longitude. The optional bounds object restricts results to a map viewport.

Quick try

curl
curl -X POST 'https://api-gw.sovereignsolutions.com/gateway/geocode/search?api-key=$API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"searchKey": "coffee", "skip": 0, "take": 10}'

Endpoints

Method	Path	Purpose
`POST`	`/geocode/search`	Geolocation Place Search
`POST`	`/geocode/search`	Geocode API - in bounds
`POST`	`/geocode/search`	Geocode API - by coordinates

Geolocation Place Search

POST https://api-gw.sovereignsolutions.com/gateway/geocode/search

Auth: api-key query parameter only - no bearer token, no tenant in the URL

Request parameters

Parameter	In	Type	Required	Description
`searchKey`	body	string	-	Search text - an address, landmark or place name. A `"lat, lon"` string instead returns the administrative area at that point.
`skip`	body	integer	-	Number of results to skip.
`take`	body	integer	-	Maximum number of results to return.

Request body
{
  "searchKey": "coffee",
  "skip": 0,
  "take": 10
}

Response

200 OK
{
  "docs": [
    {
      "name": "Fitness Cafe",
      "location_llt": "12.9418354,77.625556",
      "subcategorye": "Fitness Clubs & Centers",
      "categorye": "Sports Center",
      "province": "KARNATAKA",
      "_version_": 1852549247623233500,
      "district": "Bangalore",
      "groupe": "Sport",
      "id": "df6490db-0bc1-40fa-a2a4-51c919d836d8",
      "groupCode": 9,
      "categoryCode": 7320,
      "subCategoryCode": 7320002,
      "longitude": 77.625556,
      "latitude": 12.9418354,
      "resultType": 2
    },
    {
      "name": "Fitness Cafe",
      "location_llt": "12.9925717,77.6834013",
      "subcategorye": "Fitness Clubs & Centers",
      "categorye": "Sports Center",
      "province": "KARNATAKA",
      "_version_": 1852549245644570600,
      "district": "Bangalore",
      "groupe": "Sport",
      "id": "e51e5c14-f87a-415c-83ae-d92cdc32092e",
      "groupCode": 9,
      "categoryCode": 7320,
      "subCategoryCode": 7320002,
      "longitude": 77.6834013,
      "latitude": 12.9925717,
      "resultType": 2
    }
  ]
}

Response fields (17)

Field	Type	Description
`docs`	array	Matches, best first.
`docs[]`	object
`docs[].name`	string	Place name.
`docs[].location_llt`	string	`"lat,lon"` string - the same position as `latitude` / `longitude`.
`docs[].subcategorye`	string	Sub-category name.
`docs[].categorye`	string	Category name.
`docs[].province`	string	State.
`docs[]._version_`	integer	Internal index version. Ignore it.
`docs[].district`	string	District.
`docs[].groupe`	string	Group name.
`docs[].id`	string	Result ID.
`docs[].groupCode`	integer	Numeric group code.
`docs[].categoryCode`	integer	Numeric category code.
`docs[].subCategoryCode`	integer	Numeric sub-category code.
`docs[].longitude`	number	Longitude of the point, decimal degrees.
`docs[].latitude`	number	Latitude of the point, decimal degrees.
`docs[].resultType`	integer	Kind of match. `2` = place / POI match; `3` = coordinate lookup (see the coordinate example).

Errors: non-2xx responses use the standard status codes listed on Errors.

Geocode API - in bounds

POST https://api-gw.sovereignsolutions.com/gateway/geocode/search

Auth: api-key query parameter only - no bearer token, no tenant in the URL

Request parameters

Parameter	In	Type	Required	Description
`searchKey`	body	string	-	Search text - an address, landmark or place name. A `"lat, lon"` string instead returns the administrative area at that point.
`bounds`	body	object	-	Rectangle to search in.
`bounds.lx`	body	number	-	West edge, longitude.
`bounds.ly`	body	number	-	South edge, latitude.
`bounds.rx`	body	number	-	East edge, longitude.
`bounds.ry`	body	number	-	North edge, latitude.

Request body
{
  "searchKey": "Mumbai",
  "bounds": {
    "lx": 72.7,
    "ly": 18.8,
    "rx": 73.1,
    "ry": 19.3
  }
}

Response

200 OK
{
  "docs": [
    {
      "name": "Mumbai Central",
      "location_llt": "18.9696305,72.8193674",
      "subcategorye": "Unspecified",
      "categorye": "Railway Station",
      "province": "MAHARASHTRA",
      "_version_": 1852552040196079600,
      "district": "Mumbai",
      "groupe": "Transport",
      "id": "862104a3-1b8c-41fd-b5b1-deae4ed5de08",
      "groupCode": 11,
      "categoryCode": 7380,
      "subCategoryCode": 7380001,
      "longitude": 72.8193674,
      "latitude": 18.9696305,
      "resultType": 2
    },
    {
      "name": "Mumbai Central",
      "location_llt": "18.9696305,72.8193674",
      "subcategorye": "Unspecified",
      "categorye": "Railway Station",
      "province": "MAHARASHTRA",
      "_version_": 1852552036590026800,
      "district": "Mumbai",
      "groupe": "Transport",
      "id": "bf557f5f-4280-4158-a765-c7d0721ecb21",
      "groupCode": 11,
      "categoryCode": 7380,
      "subCategoryCode": 7380001,
      "longitude": 72.8193674,
      "latitude": 18.9696305,
      "resultType": 2
    }
  ]
}

Response fields (17)

Field	Type	Description
`docs`	array	Matches, best first.
`docs[]`	object
`docs[].name`	string	Place name.
`docs[].location_llt`	string	`"lat,lon"` string - the same position as `latitude` / `longitude`.
`docs[].subcategorye`	string	Sub-category name.
`docs[].categorye`	string	Category name.
`docs[].province`	string	State.
`docs[]._version_`	integer	Internal index version. Ignore it.
`docs[].district`	string	District.
`docs[].groupe`	string	Group name.
`docs[].id`	string	Result ID.
`docs[].groupCode`	integer	Numeric group code.
`docs[].categoryCode`	integer	Numeric category code.
`docs[].subCategoryCode`	integer	Numeric sub-category code.
`docs[].longitude`	number	Longitude of the point, decimal degrees.
`docs[].latitude`	number	Latitude of the point, decimal degrees.
`docs[].resultType`	integer	Kind of match. `2` = place / POI match; `3` = coordinate lookup (see the coordinate example).

bounds restricts results to a rectangle: lx/ly are the west longitude / south latitude, rx/ry the east longitude / north latitude.

Errors: non-2xx responses use the standard status codes listed on Errors.

Geocode API - by coordinates

POST https://api-gw.sovereignsolutions.com/gateway/geocode/search

Auth: api-key query parameter only - no bearer token, no tenant in the URL

Request parameters

Parameter	In	Type	Required	Description
`searchKey`	body	string	-	`"lat, lon"` string, e.g. `"28.7074634, 77.1751171"`.

Request body
{
  "searchKey": "28.7074634, 77.1751171"
}

Response

200 OK
{
  "docs": [
    {
      "latitude": "28.7074634",
      "longitude": "77.1751171",
      "postalCode": "110009",
      "Country": "India",
      "District": "North",
      "PinCode": {
        "OfficeName": "Nirankari Colony",
        "OfficeType": "S.O",
        "Value": "110009"
      },
      "Road": "",
      "State": "DELHI",
      "Status": true,
      "Tehsil": "Model Town",
      "Village": "",
      "location_llt": "28.7074634,77.1751171",
      "country": "India",
      "province": "DELHI",
      "district": "North",
      "ward": "Model Town",
      "resultType": 3,
      "address": "Model Town, North, DELHI",
      "shortAddress": "Model Town, North, DELHI",
      "name": "Model Town, North, DELHI"
    }
  ]
}

Response fields (25)

Field	Type	Description
`docs`	array	One document for the point.
`docs[]`	object
`docs[].latitude`	string	Latitude you sent, as a string.
`docs[].longitude`	string	Longitude you sent, as a string.
`docs[].postalCode`	string	Postal code (PIN).
`docs[].Country`	string
`docs[].District`	string	District.
`docs[].PinCode`	object
`docs[].PinCode.OfficeName`	string	Post office name.
`docs[].PinCode.OfficeType`	string	Post office type, e.g. `S.O` (sub office).
`docs[].PinCode.Value`	string	Postal code (PIN).
`docs[].Road`	string	Nearest road. Empty when none is known.
`docs[].State`	string	State.
`docs[].Status`	boolean	`true` when an address was found.
`docs[].Tehsil`	string	Tehsil (sub-district).
`docs[].Village`	string	Village. Empty when not in a village.
`docs[].location_llt`	string	`"lat,lon"` string.
`docs[].country`	string
`docs[].province`	string
`docs[].district`	string
`docs[].ward`	string
`docs[].resultType`	integer	`3` = coordinate lookup.
`docs[].address`	string	Formatted address.
`docs[].shortAddress`	string	Short formatted address.
`docs[].name`	string	Display name.

Sending a "lat, lon" string as searchKey returns one resultType: 3 document describing the administrative area at that point.

Errors: non-2xx responses use the standard status codes listed on Errors.

Geocode Suggest API

Location and Address Intelligence APIs · API key only

Predicts places as the user types - send the partial text and show the returned suggestions.

Quick try

curl
curl -X POST 'https://api-gw.sovereignsolutions.com/gateway/geocode/suggest?api-key=$API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"searchKey": "superm"}'

Suggest places as the user types

POST https://api-gw.sovereignsolutions.com/gateway/geocode/suggest

Auth: api-key query parameter only - no bearer token, no tenant in the URL

Request parameters

Parameter	In	Type	Required	Description
`searchKey`	body	string	-	Partial text typed so far.

Request body
{
  "searchKey": "superm"
}

Response

200 OK
{
  "docs": [
    {
      "name": "J.D Fresh Supermarket",
      "location_llt": "19.23262075,72.96960290000001",
      "country": "India",
      "categorye": "greengrocer",
      "province": "MAHARASHTRA",
      "_version_": 1852547300003414000,
      "district": "Thane",
      "id": "b8d22390-269a-4a86-aa17-2e52beec00e1",
      "categoryCode": 2528,
      "subCategoryCode": 994875171,
      "longitude": 72.96960290000001,
      "latitude": 19.23262075,
      "resultType": 2
    },
    {
      "name": "Royalmart Supermarket",
      "location_llt": "13.049469035867427,77.50793970982083",
      "country": "India",
      "categorye": "retail",
      "province": "KARNATAKA",
      "_version_": 1852547287804280800,
      "district": "Bangalore",
      "id": "9dd98de3-0b63-4090-a9fa-28da6d71ed20",
      "categoryCode": 7212,
      "subCategoryCode": 726126339,
      "longitude": 77.50793970982083,
      "latitude": 13.049469035867427,
      "resultType": 2
    }
  ]
}

Response fields (15)

Field	Type	Description
`docs`	array	Suggestions, best first.
`docs[]`	object
`docs[].name`	string	Place name.
`docs[].location_llt`	string	`"lat,lon"` string - the same position as `latitude` / `longitude`.
`docs[].country`	string	Country.
`docs[].categorye`	string	Category name.
`docs[].province`	string	State.
`docs[]._version_`	integer	Internal index version. Ignore it.
`docs[].district`	string	District.
`docs[].id`	string	Result ID.
`docs[].categoryCode`	integer	Numeric category code.
`docs[].subCategoryCode`	integer	Numeric sub-category code.
`docs[].longitude`	number	Longitude of the point, decimal degrees.
`docs[].latitude`	number	Latitude of the point, decimal degrees.
`docs[].resultType`	integer	Kind of match. `2` = place / POI.

Errors: non-2xx responses use the standard status codes listed on Errors.

Where it's used​

API reference​

Geocode API​

Quick try​

Endpoints​

Geolocation Place Search​

Geocode API - in bounds​

Geocode API - by coordinates​

Geocode Suggest API​

Quick try​

Suggest places as the user types​

Where it's used

API reference

Geocode API

Quick try

Endpoints

Geolocation Place Search

Geocode API - in bounds

Geocode API - by coordinates

Geocode Suggest API

Quick try

Suggest places as the user types