Endpoints

Autocomplete API

Ranked type-ahead suggestions for a partial address. Designed to be called on every keystroke.

GET /api/v1/address/autocomplete

Parameters

Name	Type	Required	Description
q	string	Yes	The partial text the user has typed.
pincode	string	No	Constrain results to one PIN code.
city	string	No	Constrain results to one city.
district	string	No	Constrain results to one district.
state	string	No	Constrain results to one state. Abbreviations such as `UP` are accepted.
limit	integer	No	1–50. Defaults to 10.

Request

curl "https://address.s2coder.com/api/v1/address/autocomplete?q=gomti+nagar+luc" \
  -H "X-API-Key: YOUR_API_KEY"

Response

{
  "success": true,
  "data": [
    {
      "id": 123,
      "address": "Gomti Nagar",
      "locality": "Gomti Nagar",
      "city": "Lucknow",
      "district": "Lucknow",
      "state": "Uttar Pradesh",
      "pincode": "226010",
      "latitude": 26.8467,
      "longitude": 80.9462
    }
  ],
  "meta": { "count": 1, "query": "gomti nagar luc" }
}

How results are ranked

Suggestions are produced by walking a ladder of strategies, most precise first, and stopping as soon as enough results are collected:

Exact PIN code match
Exact locality match
Locality prefix match
Split match — "gomti nagar luc" becomes locality gomti nagar plus city luc
City prefix match
District prefix match
State prefix match
Normalised full-address prefix match

Each step is a single index-backed query, so latency does not grow with the size of the database. Note that matching is prefix-based: "nagar" will not match "Gomti Nagar", because a leading-wildcard search cannot use an index and would degrade badly at scale.

Integration tips

Debounce input by around 150 ms — you will use far fewer requests without the user noticing.
Send at least 2 characters; shorter queries return an empty list.
Pass state or city when you already know them. Fewer candidates means better suggestions.
Identical queries are cached for 60 seconds, so repeated keystrokes are cheap.

Previous Authentication Next Address Search API