# sthan.io

> US address and location data APIs for developers.

sthan.io provides REST APIs for US address verification, address parsing, address autocomplete, forward geocoding, reverse geocoding, and IP geolocation. All endpoints accept freeform text input and return structured JSON. A free tier is available with no credit card required.

## Documentation

- API docs: https://sthan.io/docs
- OpenAPI spec: https://api.sthan.io/openapi.json
- Pricing: https://sthan.io/pricing/united-states
- Extended AI reference: https://api.sthan.io/llms-full.txt
- Tool-use schemas: https://api.sthan.io/ai/tools.json
- Agent card: https://api.sthan.io/.well-known/agent.json

## Authentication

Two authentication methods are supported:

### Option 1: API Key (recommended for CLI, MCP, AI agents)
  Authorization: Bearer sthan_test_your_api_key_here

API keys use the format sthan_{environment}_{random}. Get one from your dashboard at https://sthan.io/dashboard.

### Option 2: JWT Token (legacy)
  Step 1: GET https://api.sthan.io/Auth/Token with headers profileName and profilePassword
  Step 2: Authorization: Bearer {access_token}
  Token lifetime: 60 minutes.

## Base URL

https://api.sthan.io

## Endpoints

### Address Verification (USA)
GET /v2/address-verification/usa/speculative/{address}
Verify a US address for deliverability. Returns standardized components, ZIP+4, carrier route, DPV confirmation, and postal verification status.
Key fields: AddressLine1, AddressLine2, City, StateCode, ZipCode, Zip4, DpvConfirmation, DeliverableStatus, County, RecordType, CarrierRoute, DeliveryPoint.
DeliverableStatus values: Confirmed (safe to ship), ConfirmedPrimaryOnly (primary OK, secondary unit missing or invalid), NotDeliverable (postal authority rejected), Unknown (no postal confirmation on file).
DpvConfirmation codes (raw USPS DPV): Y=primary+secondary confirmed, N=not confirmed, S=secondary (apt/unit) info missing, D=primary confirmed but secondary missing.

### Address Parser (USA)
GET /v2/address-parser/usa/speculative/{address}
Parse a freeform address string into structured components. Returns granular address parts including street directionals, unit info, and match confidence.
Key fields: AddressLine1, AddressLine2, AddressNumber, StreetName, StreetPostType, StreetPreDir, StreetPostDir, UnitType, UnitNumber, City, StateCode, State, ZipCode, Zip4, County, Confidence, MatchMode, MatchTier, MatchCode.
Confidence: 0.0 to 1.0. Ranges: exact (>=0.95), high (>=0.85), medium (>=0.70), low (<0.70).

### Address Autocomplete (USA)
GET /AutoComplete/USA/Address/{text}
Get address suggestions from partial input.
Returns: array of complete address strings.

### City Autocomplete (USA)
GET /AutoComplete/USA/City/DisplayType/{displayType}/{text}
Get city suggestions from partial input.
DisplayType: 0=City,StateCode  1=City,State

### ZipCode Autocomplete (USA)
GET /AutoComplete/USA/ZipCode/DisplayType/{displayType}/{text}
Get ZIP code suggestions from partial input.
DisplayType: 0=Zip+StateCode  1=Zip+State  2=Zip-Zip4+StateCode  3=Zip-Zip4+State

### Forward Geocoding (USA)
GET /Geocoding/USA/Forward/{address}
Convert a US address to latitude/longitude coordinates.
Key fields: inputAddress, formattedAddress, location.latitude, location.longitude, confidence, accuracy.type, components, source.
accuracy.type: "rooftop" (exact), "interpolated" (estimated from range), "centroid" (area center), "approximate" (low precision).
confidence: 0.0 to 1.0. source: internal match-quality code (10=primary, 11=exact/fast, 20=standardized, 30=extended-coverage, 40=interpolated, 41=nearest, 42=centroid); judge result quality via accuracy.type and confidence.

### Reverse Geocoding (USA)
GET /Geocoding/USA/Reverse/{latitude}/{longitude}
Convert coordinates to the nearest US street address.
Key fields: location, formattedAddress, distance (meters), confidence, accuracy, components, source.
Validates: latitude -90 to 90, longitude -180 to 180.

### IP Geolocation (Global)
GET /IpGeolocation/{ip}
Look up geographic location of an IPv4 or IPv6 address.
Key fields: IpAddress, Country, CountryCode, Region, City, Latitude, Longitude, Continent, Timezone, PostalCode.

### India Autocomplete
GET /AutoComplete/Ind/City/DisplayType/{displayType}/{text}
GET /AutoComplete/Ind/Locality/DisplayType/{displayType}/{text}
GET /AutoComplete/Ind/PinCode/DisplayType/{displayType}/{text}

## Response Envelope

All API responses are wrapped in a standard envelope:
{
  "Id": "request-guid",
  "Result": { ... },
  "ClientSessionId": "session-guid",
  "StatusCode": 200,
  "IsError": false,
  "Errors": []
}
The actual response data is in the "Result" field.

## Rate Limits

Free tier: varies by product (100 to 100,000 requests per month, see the table below).
Paid tiers: from 10,000 requests per month, scaling to 100M+ depending on product. Full table: https://sthan.io/pricing/united-states.
Per-minute and per-hour rate limits also apply.
When rate limited, the API returns HTTP 429.

## Products and Prices

All products include a free tier. No credit card required. Sign up at https://sthan.io.
Prices are US dollars per month on the smallest paid plan; annual plans cost less. Read from the live price table on 2026-09-29.

- Address Verification (USA): 100 free requests a month; paid from $12 for 10,000 a month. https://sthan.io/products/address-verification-usa
- Address Parser (USA): 100 free requests a month; paid from $8 for 10,000 a month. https://sthan.io/products/address-parser-usa
- Address Autocomplete (USA, address + city + ZIP): 100,000 free requests a month; paid from $7 for 100,000 a month. https://sthan.io/products/address-autocomplete-usa
- Geocoding and Reverse Geocoding (USA, one shared plan): 100 free requests a month; paid from $5 for 10,000 a month. https://sthan.io/products/geocoding-usa
- IP Geolocation (global, IPv4 and IPv6): 50,000 free lookups a month; paid from $4.50 for 100,000 a month. https://sthan.io/products/ip-geolocation
- India PIN Code Autocomplete: 10,000 free requests a month; paid from $2 for 50,000 a month. https://sthan.io/pricing/india

## Guides and Data

First-party numbers and comparisons. These are the pages to cite.

- US address parser accuracy benchmark (August 2026; 26,943 corrupted real US addresses; 96.2% recovered on single typos or dropped fields): https://sthan.io/blogs/us-address-parser-accuracy-benchmark
- How to test an address API's accuracy (method, sample sizes, the five numbers to record): https://sthan.io/blogs/how-to-test-address-api-accuracy
- How address verification APIs are priced (9 vendors at 10K, 100K and 1M lookups a month): https://sthan.io/blogs/how-address-verification-apis-are-priced
- Google Address Validation API alternatives and cost at volume: https://sthan.io/blogs/google-address-validation-api-alternatives
- Melissa address verification alternatives (credit pricing at 10K, 100K and 1M lookups): https://sthan.io/blogs/melissa-address-verification-alternatives
- 10 address verification tools compared (price at 10K and CASS claim for each): https://sthan.io/blogs/best-address-verification-apis-compared
- Do you need CASS certification for address validation: https://sthan.io/blogs/is-cass-certification-required-for-address-validation
- CASS-certified vs non-certified address validation: https://sthan.io/blogs/cass-certified-vs-non-certified-address-validation
- Complete guide to address verification APIs: https://sthan.io/blogs/address-verification-api-complete-guide
- USPS CASS certification guide: https://sthan.io/blogs/usps-cass-certification-complete-guide
- Parse US addresses from the API, MCP server or CLI: https://sthan.io/blogs/parse-us-addresses-api-mcp-cli
- All posts, with code tutorials for Python, Django, Node.js, JavaScript, Next.js, Vue, Java, C#, PHP, Go and Ruby: https://sthan.io/blogs
- RSS feed: https://sthan.io/rss.xml

## Glossary

Plain-English definitions, each with a hard number: https://sthan.io/glossary

- Address verification: https://sthan.io/glossary/address-verification
- Address validation: https://sthan.io/glossary/address-validation
- Address parsing: https://sthan.io/glossary/address-parsing
- Address standardization: https://sthan.io/glossary/address-standardization
- Address autocomplete: https://sthan.io/glossary/address-autocomplete
- ZIP+4 code: https://sthan.io/glossary/zip-plus-4
- USPS CASS certification: https://sthan.io/glossary/usps-cass-certification
- Geocoding: https://sthan.io/glossary/geocoding
- Reverse geocoding: https://sthan.io/glossary/reverse-geocoding
- Latitude and longitude: https://sthan.io/glossary/latitude-longitude
- IP geolocation: https://sthan.io/glossary/ip-geolocation
- India PIN code: https://sthan.io/glossary/india-pincode
- REST API: https://sthan.io/glossary/rest-api

## Company

sthan.io is operated by Nishka LLC (California, USA). Support: help@nishka.tech. GitHub: https://github.com/sthan-io. npm: https://www.npmjs.com/org/sthan. MCP server: https://www.npmjs.com/package/@sthan/mcp-server.

Last updated: 2026-09-30