Geocode API

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

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 Sovereign Solutions Solves Address Ambiguity

graph LR
    A[Unstructured Address Input] --> B[Sovereign NLP Normalizer]
    B --> C[Regional Landmark & Pincode Graph]
    C --> D[Precision Coordinate & Administrative Hierarchy]

Input Parsing: Deconstructs raw address strings into building, street, sub-locality, locality, city, state, and postal code.
Graph Matching: Evaluates candidates against Sovereign Solutions' 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

Master list reference: #1

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.

Endpoints

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

All requests need only your API key, as the api-key query parameter - no bearer token:

?api-key=<apiKey>

Geolocation Place Search

POST /geocode/search

Base URL: https://api-gw.sovereignsolutions.com/gateway

Request Parameters

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

Request body

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

Response Schema

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
    }
  ]
}

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

Geocode API - in bounds

POST /geocode/search

Base URL: https://api-gw.sovereignsolutions.com/gateway

Request Parameters

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

Request body

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

Response Schema

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
    }
  ]
}

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.

Geocode API - by coordinates

POST /geocode/search

Base URL: https://api-gw.sovereignsolutions.com/gateway

Request Parameters

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

Request body

{
  "searchKey": "28.7074634, 77.1751171"
}

Response Schema

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"
    }
  ]
}

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.

Example

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}'

Geocode Suggest API

Master list reference: #6

Location and Address Intelligence APIs · API key only

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

Endpoints

All requests need only your API key, as the api-key query parameter - no bearer token:

?api-key=<apiKey>

Suggest places as the user types

POST /geocode/suggest

Base URL: https://api-gw.sovereignsolutions.com/gateway

Request Parameters

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

Request body

{
  "searchKey": "superm"
}

Response Schema

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
    }
  ]
}

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.

Example

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

Overview & Solution​

Key Value Propositions​

Industry Use Cases​

1. E-Commerce & Last-Mile Delivery​

2. Banking, Insurance & FinTech​

3. Telecom & Utility Services​

How Sovereign Solutions Solves Address Ambiguity​

API reference​

Geocode API​

Endpoints​

Geolocation Place Search​

Geocode API - in bounds​

Geocode API - by coordinates​

Example​

Geocode Suggest API​

Endpoints​

Suggest places as the user types​

Example​

Overview & Solution

Key Value Propositions

Industry Use Cases

1. E-Commerce & Last-Mile Delivery

2. Banking, Insurance & FinTech

3. Telecom & Utility Services

How Sovereign Solutions Solves Address Ambiguity

API reference

Geocode API

Endpoints

Geolocation Place Search

Geocode API - in bounds

Geocode API - by coordinates

Example

Geocode Suggest API

Endpoints

Suggest places as the user types

Example