Address API

Search localities, post offices, districts and states by keyword, or by a partial PIN code. Autocomplete returns compact, display-ready labels and is designed to be called on every keystroke.

Search addresses

GEThttps://superapi.fly.dev/v1/address/search

Parameters

Name	Type	Description
`query` required	string	Keywords or a partial PIN code, e.g. `koramangala` or `5600`.
`state` optional	string	State or union territory name, or its ISO code (e.g. `Telangana` or `TG`).
`limit` optional	integer	Number of results, 1-50. Default `10`.

Sample request

curl "https://superapi.fly.dev/v1/address/search?query=koramangala" \
  -H "X-Api-Key: YOUR_API_KEY"

import requests

resp = requests.get(
    "https://superapi.fly.dev/v1/address/search",
    params={"query": "koramangala"},
    headers={"X-Api-Key": "YOUR_API_KEY"},
    timeout=10,
)
resp.raise_for_status()
print(resp.json())

const params = new URLSearchParams({"query":"koramangala"});
const resp = await fetch(`https://superapi.fly.dev/v1/address/search?${params}`, {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
});
if (!resp.ok) throw new Error((await resp.json()).error);
console.log(await resp.json());

req, _ := http.NewRequest("GET", "https://superapi.fly.dev/v1/address/search?query=koramangala", nil)
req.Header.Set("X-Api-Key", "YOUR_API_KEY")
resp, err := http.DefaultClient.Do(req)
if err != nil {
    log.Fatal(err)
}
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
fmt.Println(string(body))

Sample response

[
  {
    "pincode": "560034",
    "office_name": "Koramangala S.O",
    "locality": "Koramangala",
    "office_type": "Sub Office",
    "delivery": true,
    "division": "Bangalore South",
    "region": "Bangalore HQ",
    "circle": "Karnataka",
    "taluk": "Bangalore South",
    "district": "Bangalore",
    "state": "Karnataka",
    "state_code": "KA",
    "latitude": null,
    "longitude": null
  },
  {
    "pincode": "560095",
    "office_name": "Koramangala VI Bk S.O",
    "locality": "Koramangala VI Bk",
    "office_type": "Sub Office",
    "delivery": true,
    "division": "Bangalore South",
    "region": "Bangalore HQ",
    "circle": "Karnataka",
    "taluk": "Bangalore South",
    "district": "Bangalore",
    "state": "Karnataka",
    "state_code": "KA",
    "latitude": null,
    "longitude": null
  },
  {
    "pincode": "560034",
    "office_name": "Koramangala I Block S.O",
    "locality": "Koramangala I Block",
    "office_type": "Sub Office",
    "delivery": false,
    "division": "Bangalore South",
    "region": "Bangalore HQ",
    "circle": "Karnataka",
    "taluk": "Bangalore South",
    "district": "Bangalore",
    "state": "Karnataka",
    "state_code": "KA",
    "latitude": null,
    "longitude": null
  }
]

Try it

X-Api-Key

query *

state

limit

Autocomplete suggestions

GEThttps://superapi.fly.dev/v1/address/autocomplete

Parameters

Name	Type	Description
`query` required	string	At least 2 characters of a locality, district, state or PIN code.
`state` optional	string	State or union territory name, or its ISO code (e.g. `Telangana` or `TG`).
`limit` optional	integer	Number of suggestions, 1-20. Default `8`.

Sample request

curl "https://superapi.fly.dev/v1/address/autocomplete?query=chan&state=TG" \
  -H "X-Api-Key: YOUR_API_KEY"

import requests

resp = requests.get(
    "https://superapi.fly.dev/v1/address/autocomplete",
    params={"query": "chan", "state": "TG"},
    headers={"X-Api-Key": "YOUR_API_KEY"},
    timeout=10,
)
resp.raise_for_status()
print(resp.json())

const params = new URLSearchParams({"query":"chan","state":"TG"});
const resp = await fetch(`https://superapi.fly.dev/v1/address/autocomplete?${params}`, {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
});
if (!resp.ok) throw new Error((await resp.json()).error);
console.log(await resp.json());

req, _ := http.NewRequest("GET", "https://superapi.fly.dev/v1/address/autocomplete?query=chan&state=TG", nil)
req.Header.Set("X-Api-Key", "YOUR_API_KEY")
resp, err := http.DefaultClient.Do(req)
if err != nil {
    log.Fatal(err)
}
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
fmt.Println(string(body))

Sample response

[
  {
    "label": "Chandanagar, Hyderabad, Telangana - 500050",
    "pincode": "500050",
    "office_name": "Chandanagar S.O",
    "locality": "Chandanagar",
    "district": "Hyderabad",
    "state": "Telangana",
    "state_code": "TG"
  },
  {
    "label": "Chandur S.O (Nalgonda), Nalgonda, Telangana - 508255",
    "pincode": "508255",
    "office_name": "Chandur S.O (Nalgonda)",
    "locality": "Chandur S.O (Nalgonda)",
    "district": "Nalgonda",
    "state": "Telangana",
    "state_code": "TG"
  },
  {
    "label": "Chandi, Medak, Telangana - 502334",
    "pincode": "502334",
    "office_name": "Chandi B.O",
    "locality": "Chandi",
    "district": "Medak",
    "state": "Telangana",
    "state_code": "TG"
  }
]

Try it

X-Api-Key

query *

state

limit

Authentication

Send your API key in the X-Api-Key header (or as Authorization: Bearer <key>). Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and, on metered plans, X-Quota-Limit and X-Quota-Remaining.

Errors

Errors return a JSON body of the form {"error": "message"}.

Status	Meaning
400	A parameter is missing or invalid. The message says which.
401	Missing, invalid or revoked API key.
429	Rate limit or monthly quota exceeded. Honour `Retry-After`.
5xx	Server error. Safe to retry with backoff.