Sthana.Anantasutra: India Address Normalizer and PIN Code Validator

Sthana.Anantasutra turns messy Indian addresses into clean, structured ones. Paste addresses the way customers type them, in English, Hindi or Hinglish, with or without a PIN code. Each one is split into house, building, street, landmark, locality, tehsil, city, district, state and PIN. The PIN is checked against the India Post directory, and you get back a clean one-line address, a confidence score and a list of problems, each with a machine-readable code.

Everything runs offline inside the Actor against the India Post PIN directory built into the image. No LLM, no geocoding API, and nothing you send is passed to a third party. It is part of the Anantasutra family of small, cheap, honest tools for Indian data (Pramana.Anantasutra validates GSTIN, PAN, IFSC, PIN and UPI IDs).

Who it is for

• E-commerce and D2C brands cleaning checkout addresses from Shopify, WooCommerce, Amazon or Magento before printing courier labels, to cut misroutes and RTO (return to origin) costs.
• Logistics, 3PL and courier operations that need to catch a wrong PIN, a state that contradicts the PIN, or an address with no house number before dispatch.
• CRM and data teams standardising old customer address books (Bombay, Madras, Gurgaon, Orissa, undivided Andhra Pradesh) so records can be deduplicated and segmented by city, district and state.
• Developers and AI agents that need a fast, deterministic address parser with clear error codes.

What it does

• Splits the address into careOf, house, building, street, landmark, locality, subDistrict (tehsil / taluka), city, district, state, stateCode, pincode and country.
• Checks the PIN against the India Post directory: does it exist, does it belong to the state, city and district written in the address, and does the locality's own post office have a different PIN (LOCALITY_PIN_MISMATCH, the most common real delivery error)?
• Reads PINs in every common form: 400021, 400 021, 400-021, Mumbai-400021, (400021), PIN:400021, Devanagari digits (४०००२१) and pandas' 400021.0. A malformed PIN (4OOO21, 40002, 000000) is reported as PIN_INVALID_FORMAT with a suggestion, and the city is still recognised. Postal-zone shorthand such as Laxmi Nagar Delhi 92 or Bangalore 38 gets the full PIN as a suggestion (110092, 560038).
• Modernises names, with an issue that says what changed: old city names (Bombay to Mumbai, Madras to Chennai, Calcutta to Kolkata, Gurgaon to Gurugram, Allahabad to Prayagraj, Poona, Baroda, Simla, Trivandrum, Cochin, Vizag and more), state spellings and abbreviations (KA, UP, raj, Gujrat, Orissa, Uttaranchal, Hindi state names and abbreviations such as उ.प्र. or म.प्र.) and states that were split: a pre-2014 Hyderabad, Andhra Pradesh becomes Telangana and a pre-2019

  Leh, Jammu and Kashmir
  becomes Ladakh (STATE_MODERNIZED warning, the address stays valid).
• Never swaps a town for a different city. Only true aliases are renamed. A town or district written in the address (Kanchipuram, Dharwad, Palwal, Raigad, Chittoor) is kept as written, not replaced by the nearest big city.
• Understands Indian address habits: C/O and S/O names (kept in careOf), landmarks (near, opp, bhd, ke paas, के पास), village / post office / tehsil / district markers (Vill., PO, At Post, Tal., Teh., Dist., PS for police station), Hinglish house markers (Ghar no, Makan, H no) and Hindi ones (मकान नं, फ्लैट). Hindi and other non-Latin words are kept as written; Hindi city and state names are recognised.
• Keeps phone numbers out of the result. A mobile number typed into the address (Mob: 9876543210) is left out of every output field and reported as PHONE_REMOVED.
• Suggests PIN codes when the PIN is missing, malformed, not in the directory or does not match the locality.
• Scores confidence from 0 to 1 so you can route low-confidence addresses to a human or a customer callback.

Input

{
  "addresses": [
    "Flat 302, Sai Krupa Apts, Near Hanuman Mandir, MG Road, Andheri (East), Bombay - 400069",
    "#45, 2nd Cross, 4th Block, Koramangala, Bangalore 560034, KA",
    "मकान नं 12, गांधी नगर, जयपुर, राजस्थान 302001",
    "N/A"
  ],
  "structuredAddresses": [
    { "address1": "Flat 4, Sunshine Residency, 27th Main", "address2": "HSR Layout", "city": "Bangalore", "province": "Karnataka", "zip": "560102", "country": "India" }
  ],
  "outputCase": "title",
  "includePincodeDetails": false,
  "suggestPincode": true
}

• addresses: one complete address per line (free text). A single string with line breaks also works.
• structuredAddresses: addresses you already hold as fields, for example a checkout export. Field names are matched ignoring case, spaces, _, - and ., so Address Line 1, address_1, AddressLine1 and address1 are the same field. Accepted: line1-line3, address1-address3, address_1, AddressLine1-AddressLine3, address, street (a string or a list of lines), house, building, locality, area, landmark, city, district, state / province / region / StateOrRegion (Magento's nested region object too), pincode / pin / zip / postcode / PostalCode, and country / country_code / CountryCode. Names, phone numbers, e-mails and IDs are skipped quietly. Any other filled field is listed in an UNKNOWN_FIELD warning, never silently dropped.
• outputCase: title (Title Case, recommended), upper (UPPER CASE, for courier labels) or original.
• includePincodeDetails: add the PIN's district(s), state and post-office names to each row.
• suggestPincode (default on): suggest PIN codes when the PIN is missing or wrong.

Output

One row per address, in input order (free-text addresses first, then structured ones):

{
  "index": 0,
  "input": "Flat 302, Sai Krupa Apts, Near Hanuman Mandir, MG Road, Andheri (East), Bombay - 400069",
  "formatted": "Flat 302, Sai Krupa Apts, MG Road, Near Hanuman Mandir, Andheri East, Mumbai, Maharashtra 400069, India",
  "confidence": 0.87,
  "valid": true,
  "careOf": null,
  "house": "Flat 302",
  "building": "Sai Krupa Apts",
  "street": "MG Road",
  "landmark": "Near Hanuman Mandir",
  "locality": "Andheri East",
  "subDistrict": null,
  "city": "Mumbai",
  "district": "Mumbai Suburban",
  "state": "Maharashtra",
  "stateCode": "MH",
  "pincode": "400069",
  "country": "India",
  "issues": [{ "code": "CITY_NORMALIZED", "severity": "info", "message": "\"Bombay\" written as \"Mumbai\"." }],
  "filledFromPincode": ["state", "district"]
}

• formatted: the clean one-line address, ready for a label. Repeats are skipped (a district equal to the city, the city of a city-state).
• valid: true only when there is no error-level issue, the PIN is in the India Post directory, and a city, locality or tehsil was found. Warnings do not make a row invalid; filter on them if you need stricter rules.
• confidence: 0 to 1, from how many components were found and whether they agree with each other and the PIN.
• issues: { code, severity, message } with severity error, warning or info.
• suggestedPincodes: up to 5 { pincode, office, district, state } when the PIN is missing or wrong.
• filledFromPincode: which fields came from the PIN directory instead of the address text.
• pincodeDetails (when includePincodeDetails is on) and unparsed (text that could not be placed).

A run summary (valid / invalid / blank counts, issue counts, average confidence, PIN directory version) is saved as the SUMMARY record in the key-value store.

Issue codes

Severity	Codes
error	PIN_NOT_FOUND, PIN_INVALID_FORMAT, PIN_PLACEHOLDER (999999, 111111), STATE_PIN_MISMATCH, CITY_STATE_MISMATCH, CITY_PIN_MISMATCH, COUNTRY_NOT_INDIA, and for rows that were not processed: EMPTY, PLACEHOLDER, TOO_LONG
warning	PIN_MISSING, PIN_ARMY_POSTAL, MULTIPLE_PINS, STATE_MODERNIZED, LOCALITY_PIN_MISMATCH, CITY_DISTRICT_MISMATCH, DISTRICT_PIN_MISMATCH, HOUSE_MISSING, LIKELY_INCOMPLETE, CITY_MISSING, UNRECOGNIZED_LOCATION, COUNTRY_UNRECOGNIZED, UNKNOWN_FIELD, FIELD_IGNORED
info	CITY_NORMALIZED, STATE_NORMALIZED, STATE_FROM_CITY, CITY_NOT_FOUND, PHONE_REMOVED, NON_LATIN_TEXT, UNPARSED_TEXT, PIN_DATA_CONFLICT, DIRECTORY_UNAVAILABLE

LOCALITY_PIN_MISMATCH is a warning when the locality's post office is in the same district as the PIN, and only info when it is in another district of the same city, because big cities repeat locality names (Delhi has a Shastri Nagar in North Delhi, 110052, and a Shastri Nagar post office in East Delhi, 110031).

Pricing

Pay per result. You only pay for addresses that were actually processed.

Event	Price	When
Address normalized	$0.0008 ($0.80 per 1,000)	one result row for an address that was parsed and checked
Actor start	$0.00005	charged by Apify once per run at the default 512 MB memory

Examples: 1,000 addresses cost about $0.80, and 25,000 addresses (the per-run maximum) about $20.

Never charged: blank lines, empty-cell placeholders (N/A, NA, null, None, nan, undefined, -, --, #N/A, #VALUE!, 0, true / false and similar), and lines over 1,000 characters. They still get a row (with EMPTY, PLACEHOLDER or TOO_LONG) so your output lines up with your input. Set "Maximum cost per run" to cap spending: the run stops cleanly at that limit and never bills beyond it.

Limits and what is not verified

• 25,000 addresses per run (free-text and structured together) and 1,000 characters per address. A larger list is rejected up front with a "split the list" message, and nothing is charged.
• Structure and PIN directory, not delivery. Sthana does not geocode, does not confirm that a house or street exists, and does not know whether a courier serves the PIN. valid: true means the address is complete and consistent with the India Post directory.
• PIN directory version: India Post "All India Pincode Directory", as of 2025-10-03 (19,586 PINs, 165,593 post office records, 749 districts). The Docker build downloads the current file from data.gov.in and falls back to this bundled snapshot when data.gov.in is unreachable; the version used is in the run log and the SUMMARY record. PINs created after that date show as PIN_NOT_FOUND.
• Army Postal Service PINs (9xxxxx) are not in the public directory: PIN_ARMY_POSTAL warning, valid: false.
• City names: about 90 major cities with their historic names and spellings are recognised, plus every India Post district name. Other towns and villages are kept as written (with CITY_NOT_FOUND as info when no city is recognised; locality, tehsil and district are given instead).
• District names are India Post's spellings, which can differ from everyday usage or lag behind a renaming (Ahmadabad, 24 Paraganas North).
• Locality checks need a post office of that name. A locality without its own post office cannot be matched to a PIN, so a wrong PIN there is not caught.
• Non-Latin text is kept as written, not transliterated. City and state names in Hindi (and a few other scripts) are recognised; other words in those scripts are labelled by position only.
• Indian addresses only. An address in another country is reported as COUNTRY_NOT_INDIA and never relabelled "India".
• The input field echoes what you sent, so a phone number typed into an address is still visible there; every derived field and formatted leave it out.

Use it from Claude, ChatGPT or Cursor (Apify MCP server)

Sthana works well as a tool for AI agents: the output is deterministic and every problem has a code.

• Claude (Settings > Connectors), Claude Code, Cursor and other MCP clients: add the Apify MCP server https://mcp.apify.com?tools=motivating_bracelet/sthana-anantasutra and sign in with your Apify account, or run it locally with npx -y @apify/actors-mcp-server --actors motivating_bracelet/sthana-anantasutra and your Apify API token in the APIFY_TOKEN environment variable.
• ChatGPT: add https://mcp.apify.com as a custom connector (MCP) where your plan allows it.

Then ask in plain language, for example: "Clean these delivery addresses with motivating_bracelet/sthana-anantasutra and list the ones whose PIN does not match the city." The current setup steps for each client are in Apify's MCP documentation (docs.apify.com, "MCP server").

From code, one synchronous call returns the rows:

curl -s -X POST "https://api.apify.com/v2/acts/motivating_bracelet~sthana-anantasutra/run-sync-get-dataset-items?token=$APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"addresses": ["Flat 5, MG Road, Pune 411001", "Koramangala, Bangalore 560034"]}'

FAQ

Does valid: true mean the parcel will be delivered? No. It means the address has a place name and a PIN that exists, and nothing in it contradicts the India Post directory. It cannot tell whether flat 302 exists.

Why was my town not changed to the district's big city? On purpose. A district such as Kanchipuram or Raigad is not another name for Chennai or Navi Mumbai, and printing the wrong city on a label causes misroutes. Only real aliases (Bombay, Madras, Gurgaon, ...) are renamed, and every change is listed in issues.

My old address says "Hyderabad, Andhra Pradesh". Is it rejected? No. The state is updated to Telangana with a STATE_MODERNIZED warning and the address stays valid. The same applies to Leh or Kargil written with Jammu and Kashmir (now Ladakh) and to the states created in 2000 (Jharkhand, Chhattisgarh, Uttarakhand).

The PIN is "400-021" or "Delhi 92". What happens? 400-021 is read as 400021. Delhi 92 is old postal-zone shorthand: the row gets PIN_INVALID_FORMAT, the city stays Delhi, and 110092 is the first suggested PIN.

Do Hindi addresses work? Yes. Devanagari digits, Hindi state and city names, the abbreviations उ.प्र., म.प्र. and हि.प्र., and Hindi markers such as मकान नं and के पास are understood. Hindi words are kept as written, and city and state come out in English.

Is my data sent anywhere? No. Addresses are processed inside the Actor run and saved only to your own Apify dataset and key-value store.

Is this an official India Post service? No. It is an independent tool built on public data and is not affiliated with the Department of Posts or any government body.

Data sources and licences

• India Post PIN directory: "All India Pincode Directory" by the Department of Posts, Ministry of Communications, Government of India, on data.gov.in, under the Government Open Data License - India (GODL-India, https://www.data.gov.in/Godl). Contains data from the "All India Pincode Directory" published by the Department of Posts, Ministry of Communications, Government of India, on the Open Government Data Platform India (data.gov.in), used under the Government Open Data License - India (GODL-India). The bundled snapshot was compacted from the khush/india-pincodes v1.0.0 redistribution of that dataset. data.gov.in lists the dataset as updated 2025-10-03.
• State names and codes: ISO 3166-2:IN (with the 2023 update) and the official names of states and union territories, verified 2026-10-20.
• City names, historic names and address keywords: compiled for this Actor from official renamings and common spellings; maintained with the source code.