Endpoints

Address Validation API

Check whether an address is real and internally consistent, and get a corrected, canonical version back with a confidence score.

POST /api/v1/address/validate

Request body

Send JSON. At least one of address or pincode is required.

{
  "address": "Gomti Nagar Lucknow",
  "pincode": "226010",
  "city": "Lucknow",
  "state": "Uttar Pradesh"
}

house, street, locality, landmark and district are also accepted and improve the result when available.

Request

curl -X POST "https://address.s2coder.com/api/v1/address/validate" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"address":"Gomti Nagar Lucknow","pincode":"226010","city":"Lucknow","state":"Uttar Pradesh"}'

Response

{
  "success": true,
  "valid": true,
  "confidence": 0.96,
  "normalized_address": "Gomti Nagar, Lucknow, Uttar Pradesh, 226010",
  "pincode": "226010",
  "locality": "Gomti Nagar",
  "city": "Lucknow",
  "district": "Lucknow",
  "state": "Uttar Pradesh",
  "country": "IN",
  "latitude": 26.8467,
  "longitude": 80.9462,
  "issues": []
}

How confidence is calculated

The score is additive, so you can always explain why an address scored what it did.

Signal	Weight
PIN code exists in the reference database	0.40
State agrees with the PIN code	0.20
District agrees with the PIN code	0.15
Locality found under that PIN code	0.15
City agrees with the PIN code	0.10

valid is true when confidence reaches 0.60 and nothing in the submitted address contradicts the reference data. A supplied state or district that belongs to a different PIN code fails the address outright, however well the rest of it scores — the address as written cannot be delivered to.

Either way, read issues: it lists exactly what did not line up, in plain language you can show a user.

Example: a mismatched state

{
  "success": true,
  "valid": false,
  "confidence": 0.40,
  "normalized_address": "Gomti Nagar, Lucknow, Uttar Pradesh, 226010",
  "pincode": "226010",
  "city": "Lucknow",
  "district": "Lucknow",
  "state": "Uttar Pradesh",
  "issues": [
    "State \"Maharashtra\" does not match PIN code 226010, which belongs to Uttar Pradesh."
  ]
}

Note that the returned state is the corrected one. The endpoint always hands back its best canonical reading of the address, so you can offer it to the user as a suggested fix.

Normalisation

The same normalisation runs here as during import, so validation and deduplication always agree:

State abbreviations expand — UP becomes Uttar Pradesh.
City aliases and historical names resolve — LKO to Lucknow, Bombay to Mumbai.
Street abbreviations expand — rd to road, nr to near, sec to sector.
Whitespace, punctuation, casing and accents are folded away.
PIN codes are stripped of formatting and checked against the six-digit, 1–8 leading rule.

Previous Magic Checkout Next Pincode API