sthan.io API Documentation

Quick Start

Make your first API call in under 5 minutes.

1

Create a Free Account

Sign up at sthan.io and subscribe to the Free tier. No credit card required. The free tier covers 100 requests a month for verification, parsing and geocoding, 100,000 for autocomplete, and 50,000 for IP geolocation.

2

Get an API Key

Create an API key in your dashboard (it looks like sthan_live_...) and send it as Authorization: Bearer YOUR_API_KEY on every request. A JWT from /Auth/Token still works if you prefer the original flow.

3

Make Your First Call

Copy any example below and replace YOUR_TOKEN with your API key from step 2. That's it!

Authentication

Two methods are supported. API key (recommended): create one in the dashboard and send Authorization: Bearer sthan_live_... on every request; keys do not expire and work with the CLI, the MCP server and AI agents. JWT token (original flow): obtain a token from /Auth/Token with your profile credentials and send it as a Bearer token; tokens last 60 minutes. The steps below show the JWT flow.

Step 1: Get Your Token

GET /Auth/Token

Send your profileName and profilePassword as request headers. The API returns a JWT access token and its expiration time.

Request Headers

Header	Type	Required	Description
profileName	string	Required	Your access profile identifier. Case-sensitive.
profilePassword	string	Required	Your access profile password. Case-sensitive.

                    
                    
                    
                    
                    
                    
                    
                    
                
Request

curl -X GET \
  "https://api.sthan.io/Auth/Token" \
  -H "profileName: YOUR_PROFILE_NAME" \
  -H "profilePassword: YOUR_PROFILE_PASSWORD"
                

const response = await fetch("https://api.sthan.io/Auth/Token", {
  headers: {
    "profileName": "YOUR_PROFILE_NAME",
    "profilePassword": "YOUR_PROFILE_PASSWORD"
  }
});
const { Result } = await response.json();
const { access_token, expiration } = Result;
// Use access_token in subsequent requests
                

import requests

resp = requests.get(
    "https://api.sthan.io/Auth/Token",
    headers={
        "profileName": "YOUR_PROFILE_NAME",
        "profilePassword": "YOUR_PROFILE_PASSWORD"
    }
)
token = resp.json()["Result"]["access_token"]
# Use token in subsequent requests
                

using var client = new HttpClient();
client.DefaultRequestHeaders.Add("profileName", "YOUR_PROFILE_NAME");
client.DefaultRequestHeaders.Add("profilePassword", "YOUR_PROFILE_PASSWORD");

var json = await client.GetStringAsync("https://api.sthan.io/Auth/Token");
// Deserialize, then read the token at Result.access_token
                

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.sthan.io/Auth/Token"))
    .header("profileName", "YOUR_PROFILE_NAME")
    .header("profilePassword", "YOUR_PROFILE_PASSWORD")
    .build();
HttpResponse<String> resp = client.send(request,
    HttpResponse.BodyHandlers.ofString());
// Parse JSON, then read the token at Result.access_token
                

$ch = curl_init("https://api.sthan.io/Auth/Token");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "profileName: YOUR_PROFILE_NAME",
    "profilePassword: YOUR_PROFILE_PASSWORD"
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
$data = json_decode($response, true);
$token = $data["Result"]["access_token"];
                

require 'net/http'
require 'json'

uri = URI("https://api.sthan.io/Auth/Token")
req = Net::HTTP::Get.new(uri)
req["profileName"] = "YOUR_PROFILE_NAME"
req["profilePassword"] = "YOUR_PROFILE_PASSWORD"
resp = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http|
  http.request(req)
}
token = JSON.parse(resp.body)["Result"]["access_token"]
                

req, _ := http.NewRequest("GET", "https://api.sthan.io/Auth/Token", nil)
req.Header.Set("profileName", "YOUR_PROFILE_NAME")
req.Header.Set("profilePassword", "YOUR_PROFILE_PASSWORD")

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
// Parse JSON, then read the token at Result.access_token
                

200 Response

{
  "Id": "a1b2c3d4-0000-0000-0000-000000000000",
  "Result": {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJodHRwOi8vc2NoZW1hcy5...",
    "expiration": "2026-02-19T03:45:00.0000000"
  },
  "ClientSessionId": null,
  "StatusCode": 200,
  "IsError": false,
  "Errors": []
}
                

Response Fields

Field	Type	Description
Result.access_token	string	JWT Bearer token, nested under the `Result` field of the response envelope. Include in `Authorization` header for all API calls.
Result.expiration	datetime	Token expiration timestamp (server local time, America/Los_Angeles), nested under `Result`. Request a new token before this time.

Try it — get your token

Enter your access profile credentials to get a real JWT token. Your credentials are sent to the API via a server-side proxy and are not stored.

Step 2: Use the Token

Include the access_token as a Bearer token in the Authorization header of every subsequent API request.

                All Subsequent Requests
                
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJodHRwOi8vc2NoZW1hcy5...
Content-Type: application/json

Response Envelope

All API responses are wrapped in a standard envelope. The examples in this documentation show only the Result field contents for clarity.

Envelope Format

{
  "Id": "unique-request-id",
  "Result": { /* endpoint-specific data shown in examples below */ },
  "ClientSessionId": "your-session-id",
  "StatusCode": 200,
  "IsError": false,
  "Errors": []
}
                

Rate Limits

API requests are rate-limited per subscription plan. When you exceed your limit, the API returns 429 Too Many Requests. The response includes a Retry-After header indicating when you can retry.

Product	Free	Basic	Starter	Business
Address Verification	100 / mo 10 / min	10,000 / mo 500 / min	50,000 / mo 2,500 / min	150,000 / mo 7,500 / min
Address Parser	100 / mo 10 / min	10,000 / mo 500 / min	50,000 / mo 2,500 / min	150,000 / mo 7,500 / min
Geocoding (forward + reverse)	100 / mo 10 / min	10,000 / mo 500 / min	50,000 / mo 2,500 / min	150,000 / mo 7,500 / min
Address Autocomplete	100,000 / mo 5,000 / min	100,000 / mo 5,000 / min	1,000,000 / mo 50,000 / min	5,000,000 / mo 250,000 / min
IP Geolocation	50,000 / mo 2,000 / min	100,000 / mo 4,000 / min	1,000,000 / mo 40,000 / min	5,000,000 / mo 200,000 / min

Larger Basic, Starter and Business volumes (up to 3,000,000 a month for address products, 100,000,000 for autocomplete) are on the pricing page. Enterprise volumes and higher per-minute rates are quoted on request.

            429 Response Headers
        

HTTP/1.1 429 Too Many Requests
Retry-After: 30
X-RateLimit-Limit: 100000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1708300800
        

GET

Address Autocomplete

/AutoComplete/USA/Address/{text}

Returns real-time address suggestions as the user types. Handles abbreviations, apartment/suite numbers, and partial input. Ideal for checkout forms and address fields.

Parameters

Name	Type	Required	Description
text	string	Required	Partial address to search. URL-encoded. Min 3 chars for best results.

Response Codes

200 Success 400 Bad Request 401 Unauthorized 429 Rate Limited

                
                
                
                
                
                
                
                
            
Request

curl -X GET \
  "https://api.sthan.io/AutoComplete/USA/Address/123%20main%20st" \
  -H "Authorization: Bearer YOUR_TOKEN"
            

const response = await fetch(
  "https://api.sthan.io/AutoComplete/USA/Address/123%20main%20st",
  { headers: { "Authorization": "Bearer YOUR_TOKEN" } }
);
const data = await response.json();
// ["123 Main St APT 1, Andover, MA 01810-3816", "123 Main St APT 1, Delhi, NY 13753-1257", ...]
            

import requests

response = requests.get(
    "https://api.sthan.io/AutoComplete/USA/Address/123%20main%20st",
    headers={"Authorization": "Bearer YOUR_TOKEN"}
)
print(response.json())
# ["123 Main St APT 1, Andover, MA 01810-3816", "123 Main St APT 1, Delhi, NY 13753-1257", ...]
            

using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", "YOUR_TOKEN");

var json = await client.GetStringAsync(
    "https://api.sthan.io/AutoComplete/USA/Address/123%20main%20st");
// ["123 Main St APT 1, Andover, MA 01810-3816", "123 Main St APT 1, Delhi, NY 13753-1257", ...]
            

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.sthan.io/AutoComplete/USA/Address/123%20main%20st"))
    .header("Authorization", "Bearer YOUR_TOKEN")
    .build();
HttpResponse<String> resp = client.send(request,
    HttpResponse.BodyHandlers.ofString());
            

$ch = curl_init("https://api.sthan.io/AutoComplete/USA/Address/123%20main%20st");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer YOUR_TOKEN"
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
$addresses = json_decode($response, true);
            

require 'net/http'
require 'json'

uri = URI("https://api.sthan.io/AutoComplete/USA/Address/123%20main%20st")
req = Net::HTTP::Get.new(uri)
req["Authorization"] = "Bearer YOUR_TOKEN"
resp = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http|
  http.request(req)
}
addresses = JSON.parse(resp.body)
            

req, _ := http.NewRequest("GET",
    "https://api.sthan.io/AutoComplete/USA/Address/123%20main%20st", nil)
req.Header.Set("Authorization", "Bearer YOUR_TOKEN")

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
// ["123 Main St APT 1, Andover, MA 01810-3816", "123 Main St APT 1, Delhi, NY 13753-1257", ...]
            

200 Response

[
  "123 Main St APT 1, Andover, MA 01810-3816",
  "123 Main St APT 1, Delhi, NY 13753-1257",
  "123 Main St STE 1, Caldwell, ID 83605-5476",
  "123 Main St STE 1, Corinth, NY 12822-1010",
  "123 Main St STE 1, Delhi, NY 13753-1258"
]
            

Try it live

Need more than just the full address string? Explore related APIs:

Address Parser

From $8/mo

Break addresses into components: street, city, state, ZIP, county.

View docs →

Address Verification

From $12/mo

Verify deliverability with DPV confirmation, carrier routes, ZIP+4.

View docs →

Forward Geocoding

From $5/mo

Convert addresses to latitude/longitude. High-accuracy coordinate resolution.

View docs →

GET

Address Parser

/v2/address-parser/usa/speculative/{address}

Parses a raw address string into structured components (street number, street name, unit, city, state, ZIP, county). Returns USPS-standardized results with confidence scores.

Parameters

Name	Type	Required	Description
address	string	Required	Full or partial US address to parse. URL-encoded.

                
                
                
                
                
                
                
                
            
Request

curl -X GET \
  "https://api.sthan.io/v2/address-parser/usa/speculative/1600%20pennsylvania%20ave%20nw%20washington%20dc%2020500" \
  -H "Authorization: Bearer YOUR_TOKEN"
            

const response = await fetch(
  "https://api.sthan.io/v2/address-parser/usa/speculative/1600%20pennsylvania%20ave%20nw%20washington%20dc%2020500",
  { headers: { "Authorization": "Bearer YOUR_TOKEN" } }
);
const parsed = await response.json();
console.log(parsed.city);       // "Washington"
console.log(parsed.confidence); // 1
            

import requests

resp = requests.get(
    "https://api.sthan.io/v2/address-parser/usa/speculative/1600%20pennsylvania%20ave%20nw%20washington%20dc%2020500",
    headers={"Authorization": "Bearer YOUR_TOKEN"}
)
parsed = resp.json()
print(f"{parsed['city']}, {parsed['stateCode']} - Confidence: {parsed['confidence']}")
            

using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", "YOUR_TOKEN");

var json = await client.GetStringAsync(
    "https://api.sthan.io/v2/address-parser/usa/speculative/1600%20pennsylvania%20ave%20nw%20washington%20dc%2020500");
// Deserialize to your model class
            

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.sthan.io/v2/address-parser/usa/speculative/1600%20pennsylvania%20ave%20nw%20washington%20dc%2020500"))
    .header("Authorization", "Bearer YOUR_TOKEN")
    .build();
HttpResponse<String> resp = client.send(request,
    HttpResponse.BodyHandlers.ofString());
            

$ch = curl_init("https://api.sthan.io/v2/address-parser/usa/speculative/1600%20pennsylvania%20ave%20nw%20washington%20dc%2020500");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer YOUR_TOKEN"
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$parsed = json_decode(curl_exec($ch), true);
            

require 'net/http'
require 'json'

uri = URI("https://api.sthan.io/v2/address-parser/usa/speculative/1600%20pennsylvania%20ave%20nw%20washington%20dc%2020500")
req = Net::HTTP::Get.new(uri)
req["Authorization"] = "Bearer YOUR_TOKEN"
resp = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http|
  http.request(req)
}
parsed = JSON.parse(resp.body)
            

req, _ := http.NewRequest("GET",
    "https://api.sthan.io/v2/address-parser/usa/speculative/1600%20pennsylvania%20ave%20nw%20washington%20dc%2020500", nil)
req.Header.Set("Authorization", "Bearer YOUR_TOKEN")

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
            

200 Response

{
  "inputAddress": "1600 pennsylvania ave nw washington dc 20500",
  "fullAddress": "1600 Pennsylvania Ave NW, Washington, DC 20500-0005",
  "addressLine1": "1600 Pennsylvania Ave NW",
  "addressLine2": "Washington, DC 20500-0005",
  "addressNumber": "1600",
  "streetName": "Pennsylvania",
  "streetPostType": "Ave",
  "streetPostDir": "NW",
  "city": "Washington",
  "stateCode": "DC",
  "state": "District Of Columbia",
  "zipCode": "20500",
  "zip4": "0005",
  "county": "District Of Columbia",
  "matchMode": "Speculative",
  "matchTier": "Exact",
  "confidence": 1,
  "matchCode": {
    "houseNumber": "Matched",
    "street": "Matched",
    "city": "Matched",
    "state": "Matched",
    "zipCode": "Matched"
  },
  "isError": false,
  "errorMessages": []
}
            

Response Fields

Field	Type	Description
fullAddress	string	Standardized full address with ZIP+4
addressNumber	string	House/building number
streetName	string	Standardized street name
unitType	string?	APT, STE, UNIT, etc.
county	string	County name
confidence	float	Match confidence score (0.0 – 1.0)

Try it live

GET

Address Verification

/v2/address-verification/usa/speculative/{address}

Verifies a US address and returns deliverability information including DPV confirmation, carrier route, ZIP+4, delivery point, and record type.

Parameters

Name	Type	Required	Description
address	string	Required	US address to verify. URL-encoded.

                
                
                
                
                
                
                
                
            
Request

curl -X GET \
  "https://api.sthan.io/v2/address-verification/usa/speculative/6000%20j%20st%20sacramento%20ca%2095819" \
  -H "Authorization: Bearer YOUR_TOKEN"
            

const response = await fetch(
  "https://api.sthan.io/v2/address-verification/usa/speculative/6000%20j%20st%20sacramento%20ca%2095819",
  { headers: { "Authorization": "Bearer YOUR_TOKEN" } }
);
const result = await response.json();
console.log(result.dpvConfirmation); // "Y" = deliverable
            

import requests

resp = requests.get(
    "https://api.sthan.io/v2/address-verification/usa/speculative/6000%20j%20st%20sacramento%20ca%2095819",
    headers={"Authorization": "Bearer YOUR_TOKEN"}
)
result = resp.json()
print(f"Deliverable: {result['dpvConfirmation'] == 'Y'}")
            

using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", "YOUR_TOKEN");

var result = await client.GetFromJsonAsync<VerifiedAddress>(
    "https://api.sthan.io/v2/address-verification/usa/speculative/6000%20j%20st%20sacramento%20ca%2095819");
Console.WriteLine($"DPV: {result.DpvConfirmation}");
            

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.sthan.io/v2/address-verification/usa/speculative/6000%20j%20st%20sacramento%20ca%2095819"))
    .header("Authorization", "Bearer YOUR_TOKEN")
    .build();
HttpResponse<String> resp = client.send(request,
    HttpResponse.BodyHandlers.ofString());
            

$ch = curl_init("https://api.sthan.io/v2/address-verification/usa/speculative/6000%20j%20st%20sacramento%20ca%2095819");
curl_setopt($ch, CURLOPT_HTTPHEADER, ["Authorization: Bearer YOUR_TOKEN"]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$result = json_decode(curl_exec($ch), true);
echo $result["dpvConfirmation"]; // "Y"
            

require 'net/http'
require 'json'

uri = URI("https://api.sthan.io/v2/address-verification/usa/speculative/6000%20j%20st%20sacramento%20ca%2095819")
req = Net::HTTP::Get.new(uri)
req["Authorization"] = "Bearer YOUR_TOKEN"
resp = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http|
  http.request(req)
}
result = JSON.parse(resp.body)
            

req, _ := http.NewRequest("GET",
    "https://api.sthan.io/v2/address-verification/usa/speculative/6000%20j%20st%20sacramento%20ca%2095819", nil)
req.Header.Set("Authorization", "Bearer YOUR_TOKEN")

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
            

200 Response

{
  "inputAddress": "6000 j st sacramento ca 95819",
  "fullAddress": "6000 J St, Sacramento, CA 95819-2605",
  "addressLine1": "6000 J St",
  "addressLine2": "Sacramento, CA 95819-2605",
  "unitType": "",
  "unitNumber": "",
  "city": "Sacramento",
  "stateCode": "CA",
  "zipCode": "95819",
  "zip4": "2605",
  "county": "Sacramento",
  "dpvConfirmation": "Y",
  "carrierRoute": "C007",
  "deliveryPoint": "00",
  "recordType": "S",
  "deliverableStatus": "Confirmed",
  "matchMode": "Speculative",
  "matchTier": "Exact",
  "confidence": 1,
  "matchCode": {
    "houseNumber": "Matched",
    "street": "Matched",
    "city": "Matched",
    "state": "Matched",
    "zipCode": "Matched"
  },
  "isError": false,
  "errorMessages": []
}
            

Response Fields

Field	Type	Description
deliverableStatus	enum	`Confirmed` = safe to ship, `ConfirmedPrimaryOnly` = primary OK but secondary unit missing or invalid, `NotDeliverable` = postal authority rejected, `Unknown` = no postal confirmation on file. Single field for client routing logic; derived from `dpvConfirmation`.
dpvConfirmation	string	Raw postal DPV code: `Y` = confirmed deliverable, `N` = not deliverable, `S` = secondary (apt) missing, `D` = vacant
carrierRoute	string	USPS carrier route code (e.g., C001 = city route 1)
deliveryPoint	string	2-digit delivery point code appended to ZIP+4
recordType	string	`S` = street, `H` = highrise, `F` = firm, `R` = rural route, `P` = PO box
zip4	string	4-digit ZIP extension for precise delivery routing
unitType	string	Confirmed secondary-unit designator split out of the standardized address, for example `APT`, `STE`, `UNIT`. Empty when the address has no secondary unit. Only a postal-confirmed unit appears here.
unitNumber	string	Confirmed secondary-unit number, for example `142`. Empty when the address has no secondary unit.

Try it live

GET

City Autocomplete

/AutoComplete/USA/City/DisplayType/{displayType}/{text}

Returns real-time US city name suggestions as the user types. Supports multiple display formats combining city name with state code or full state name.

Parameters

Name	Type	Required	Description
displayType	int	Required	`0` = City, StateCode (e.g., Sacramento, CA) `1` = City, State (e.g., Sacramento, California)
text	string	Required	Partial city name to search. URL-encoded.

                
                
                
                
                
                
                
                
            
Request

curl -X GET \
  "https://api.sthan.io/AutoComplete/USA/City/DisplayType/0/sacram" \
  -H "Authorization: Bearer YOUR_TOKEN"
            

const response = await fetch(
  "https://api.sthan.io/AutoComplete/USA/City/DisplayType/0/sacram",
  { headers: { "Authorization": "Bearer YOUR_TOKEN" } }
);
const cities = await response.json();
// ["Sacramento, CA", "Sacramento, NM", ...]
            

import requests

resp = requests.get(
    "https://api.sthan.io/AutoComplete/USA/City/DisplayType/0/sacram",
    headers={"Authorization": "Bearer YOUR_TOKEN"}
)
print(resp.json())
            

using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", "YOUR_TOKEN");

var json = await client.GetStringAsync(
    "https://api.sthan.io/AutoComplete/USA/City/DisplayType/0/sacram");
            

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.sthan.io/AutoComplete/USA/City/DisplayType/0/sacram"))
    .header("Authorization", "Bearer YOUR_TOKEN")
    .build();
HttpResponse<String> resp = HttpClient.newHttpClient()
    .send(request, HttpResponse.BodyHandlers.ofString());
            

$ch = curl_init("https://api.sthan.io/AutoComplete/USA/City/DisplayType/0/sacram");
curl_setopt($ch, CURLOPT_HTTPHEADER, ["Authorization: Bearer YOUR_TOKEN"]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$cities = json_decode(curl_exec($ch), true);
            

uri = URI("https://api.sthan.io/AutoComplete/USA/City/DisplayType/0/sacram")
req = Net::HTTP::Get.new(uri)
req["Authorization"] = "Bearer YOUR_TOKEN"
resp = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http|
  http.request(req)
}
cities = JSON.parse(resp.body)
            

req, _ := http.NewRequest("GET",
    "https://api.sthan.io/AutoComplete/USA/City/DisplayType/0/sacram", nil)
req.Header.Set("Authorization", "Bearer YOUR_TOKEN")
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
            

200 Response

[
  "Sacramento, CA",
  "Sacramento, KY",
  "Sacramento, NM",
  "Sacramento, PA"
]
            

Try it live

Display Type

City Name

GET

ZIP Code Autocomplete

/AutoComplete/USA/ZipCode/DisplayType/{displayType}/{text}

Returns real-time ZIP code suggestions for US addresses. Supports 4 display formats with varying levels of detail. Covers all ~42,000 active US ZIP codes.

Parameters

Name	Type	Required	Description
displayType	int	Required	`0` = ZipCode, City, StateCode `1` = ZipCode, City, State `2` = ZipCode-Zip4, City, StateCode `3` = ZipCode-Zip4, City, State
text	string	Required	Partial ZIP code or city name. URL-encoded.

                
                
                
                
                
                
                
                
            
Request

curl -X GET \
  "https://api.sthan.io/AutoComplete/USA/ZipCode/DisplayType/0/9582" \
  -H "Authorization: Bearer YOUR_TOKEN"
            

const response = await fetch(
  "https://api.sthan.io/AutoComplete/USA/ZipCode/DisplayType/0/9582",
  { headers: { "Authorization": "Bearer YOUR_TOKEN" } }
);
const zips = await response.json();
            

import requests

resp = requests.get(
    "https://api.sthan.io/AutoComplete/USA/ZipCode/DisplayType/0/9582",
    headers={"Authorization": "Bearer YOUR_TOKEN"}
)
print(resp.json())
            

using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", "YOUR_TOKEN");

var json = await client.GetStringAsync(
    "https://api.sthan.io/AutoComplete/USA/ZipCode/DisplayType/0/9582");
            

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.sthan.io/AutoComplete/USA/ZipCode/DisplayType/0/9582"))
    .header("Authorization", "Bearer YOUR_TOKEN")
    .build();
HttpResponse<String> resp = HttpClient.newHttpClient()
    .send(request, HttpResponse.BodyHandlers.ofString());
            

$ch = curl_init("https://api.sthan.io/AutoComplete/USA/ZipCode/DisplayType/0/9582");
curl_setopt($ch, CURLOPT_HTTPHEADER, ["Authorization: Bearer YOUR_TOKEN"]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$zips = json_decode(curl_exec($ch), true);
            

uri = URI("https://api.sthan.io/AutoComplete/USA/ZipCode/DisplayType/0/9582")
req = Net::HTTP::Get.new(uri)
req["Authorization"] = "Bearer YOUR_TOKEN"
resp = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http|
  http.request(req)
}
zips = JSON.parse(resp.body)
            

req, _ := http.NewRequest("GET",
    "https://api.sthan.io/AutoComplete/USA/ZipCode/DisplayType/0/9582", nil)
req.Header.Set("Authorization", "Bearer YOUR_TOKEN")
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
            

200 Response

[
  "95820, Sacramento, CA",
  "95821, Sacramento, CA",
  "95822, Sacramento, CA",
  "95825, Sacramento, CA"
]
            

Try it live

Display Type

ZIP Code or City

GET

Forward Geocoding

/Geocoding/USA/Forward/{address}

Converts a US street address into geographic coordinates (latitude and longitude). Returns matched address components along with high-accuracy coordinates.

Parameters

Name	Type	Required	Description
address	string	Required	Full US address to geocode. URL-encoded.

                
                
                
                
                
                
                
                
            
Request

curl -X GET \
  "https://api.sthan.io/Geocoding/USA/Forward/1600%20Pennsylvania%20Ave%20NW%20Washington%20DC" \
  -H "Authorization: Bearer YOUR_TOKEN"
            

const response = await fetch(
  "https://api.sthan.io/Geocoding/USA/Forward/1600%20Pennsylvania%20Ave%20NW%20Washington%20DC",
  { headers: { "Authorization": "Bearer YOUR_TOKEN" } }
);
const geo = await response.json();
console.log(`${geo.latitude}, ${geo.longitude}`); // 38.8977, -77.0365
            

import requests

resp = requests.get(
    "https://api.sthan.io/Geocoding/USA/Forward/1600%20Pennsylvania%20Ave%20NW%20Washington%20DC",
    headers={"Authorization": "Bearer YOUR_TOKEN"}
)
geo = resp.json()
print(f"Lat: {geo['latitude']}, Lng: {geo['longitude']}")
            

using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", "YOUR_TOKEN");

var geo = await client.GetFromJsonAsync<GeoResult>(
    "https://api.sthan.io/Geocoding/USA/Forward/1600%20Pennsylvania%20Ave%20NW%20Washington%20DC");
Console.WriteLine($"({geo.Latitude}, {geo.Longitude})");
            

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.sthan.io/Geocoding/USA/Forward/1600%20Pennsylvania%20Ave%20NW%20Washington%20DC"))
    .header("Authorization", "Bearer YOUR_TOKEN")
    .build();
HttpResponse<String> resp = HttpClient.newHttpClient()
    .send(request, HttpResponse.BodyHandlers.ofString());
            

$ch = curl_init("https://api.sthan.io/Geocoding/USA/Forward/1600%20Pennsylvania%20Ave%20NW%20Washington%20DC");
curl_setopt($ch, CURLOPT_HTTPHEADER, ["Authorization: Bearer YOUR_TOKEN"]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$geo = json_decode(curl_exec($ch), true);
            

uri = URI("https://api.sthan.io/Geocoding/USA/Forward/1600%20Pennsylvania%20Ave%20NW%20Washington%20DC")
req = Net::HTTP::Get.new(uri)
req["Authorization"] = "Bearer YOUR_TOKEN"
resp = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http|
  http.request(req)
}
geo = JSON.parse(resp.body)
            

req, _ := http.NewRequest("GET",
    "https://api.sthan.io/Geocoding/USA/Forward/1600%20Pennsylvania%20Ave%20NW%20Washington%20DC", nil)
req.Header.Set("Authorization", "Bearer YOUR_TOKEN")
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
            

200 Response

{
  "inputAddress": "1600 Pennsylvania Ave NW Washington DC",
  "formattedAddress": "1600 Pennsylvania Ave NW, Washington, DC 20500",
  "location": {
    "latitude": 38.897676,
    "longitude": -77.036530
  },
  "confidence": 0.95,
  "accuracy": {
    "type": "rooftop"
  },
  "components": {
    "streetNumber": "1600",
    "street": "Pennsylvania Ave NW",
    "city": "Washington",
    "state": "DC",
    "zip": "20500",
    "country": "US"
  },
  "source": "11"
}
            

Try it live

GET

Reverse Geocoding

/Geocoding/USA/Reverse/{lat}/{lon}

Converts geographic coordinates (latitude/longitude) into a human-readable street address. Returns the nearest matched address with city, state, ZIP, and county information.

Parameters

Name	Type	Required	Description
lat	double	Required	Latitude coordinate (-90 to 90)
lon	double	Required	Longitude coordinate (-180 to 180)

                
                
                
                
                
                
                
                
            
Request

curl -X GET \
  "https://api.sthan.io/Geocoding/USA/Reverse/38.897676/-77.036530" \
  -H "Authorization: Bearer YOUR_TOKEN"
            

const response = await fetch(
  "https://api.sthan.io/Geocoding/USA/Reverse/38.897676/-77.036530",
  { headers: { "Authorization": "Bearer YOUR_TOKEN" } }
);
const addr = await response.json();
console.log(addr.fullAddress);
            

import requests

resp = requests.get(
    "https://api.sthan.io/Geocoding/USA/Reverse/38.897676/-77.036530",
    headers={"Authorization": "Bearer YOUR_TOKEN"}
)
addr = resp.json()
print(addr['fullAddress'])
            

using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", "YOUR_TOKEN");

var addr = await client.GetFromJsonAsync<ReverseGeoResult>(
    "https://api.sthan.io/Geocoding/USA/Reverse/38.897676/-77.036530");
Console.WriteLine(addr.FullAddress);
            

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.sthan.io/Geocoding/USA/Reverse/38.897676/-77.036530"))
    .header("Authorization", "Bearer YOUR_TOKEN")
    .build();
HttpResponse<String> resp = HttpClient.newHttpClient()
    .send(request, HttpResponse.BodyHandlers.ofString());
            

$ch = curl_init("https://api.sthan.io/Geocoding/USA/Reverse/38.897676/-77.036530");
curl_setopt($ch, CURLOPT_HTTPHEADER, ["Authorization: Bearer YOUR_TOKEN"]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$addr = json_decode(curl_exec($ch), true);
            

uri = URI("https://api.sthan.io/Geocoding/USA/Reverse/38.897676/-77.036530")
req = Net::HTTP::Get.new(uri)
req["Authorization"] = "Bearer YOUR_TOKEN"
resp = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http|
  http.request(req)
}
addr = JSON.parse(resp.body)
            

req, _ := http.NewRequest("GET",
    "https://api.sthan.io/Geocoding/USA/Reverse/38.897676/-77.036530", nil)
req.Header.Set("Authorization", "Bearer YOUR_TOKEN")
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
            

200 Response

{
  "latitude": 38.897676,
  "longitude": -77.036530,
  "fullAddress": "1600 Pennsylvania Ave NW, Washington, DC 20500",
  "city": "Washington",
  "stateCode": "DC",
  "state": "District of Columbia",
  "zipCode": "20500",
  "county": "District of Columbia"
}
            

Try it live

Latitude

Longitude

GET

IP Geolocation

/IpGeolocation/{ip}

Look up any IPv4 or IPv6 address. Returns country, region, city, coordinates, postal code, timezone with current local time, flag, currency, calling code, network (ASN, ISP, organisation), mobile/proxy/hosting flags, reverse DNS and a confidence score. confidence is 0 to 1 and is absent when the address is new to us (ask again in a few seconds) or when the sources did not agree on a city; precision says whether the answer goes down to a city, a region or only a country.

Parameters

Name	Type	Required	Description
ip	string	Required	IPv4 or IPv6 address (e.g., `8.8.8.8`)

                
                
                
                
                
                
                
                
            
Request

curl -X GET \
  "https://api.sthan.io/IpGeolocation/8.8.8.8" \
  -H "Authorization: Bearer YOUR_TOKEN"
            

const response = await fetch(
  "https://api.sthan.io/IpGeolocation/8.8.8.8",
  { headers: { "Authorization": "Bearer YOUR_TOKEN" } }
);
const geo = await response.json();
console.log(`${geo.city}, ${geo.region}`);
            

import requests

resp = requests.get(
    "https://api.sthan.io/IpGeolocation/8.8.8.8",
    headers={"Authorization": "Bearer YOUR_TOKEN"}
)
geo = resp.json()
print(f"{geo['city']}, {geo['region']}, {geo['country']}")
            

using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", "YOUR_TOKEN");

var geo = await client.GetFromJsonAsync<GeoLocation>(
    "https://api.sthan.io/IpGeolocation/8.8.8.8");
Console.WriteLine($"{geo.City}, {geo.Country}");
            

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.sthan.io/IpGeolocation/8.8.8.8"))
    .header("Authorization", "Bearer YOUR_TOKEN")
    .build();
HttpResponse<String> resp = HttpClient.newHttpClient()
    .send(request, HttpResponse.BodyHandlers.ofString());
            

$ch = curl_init("https://api.sthan.io/IpGeolocation/8.8.8.8");
curl_setopt($ch, CURLOPT_HTTPHEADER, ["Authorization: Bearer YOUR_TOKEN"]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$geo = json_decode(curl_exec($ch), true);
            

uri = URI("https://api.sthan.io/IpGeolocation/8.8.8.8")
req = Net::HTTP::Get.new(uri)
req["Authorization"] = "Bearer YOUR_TOKEN"
resp = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http|
  http.request(req)
}
geo = JSON.parse(resp.body)
            

req, _ := http.NewRequest("GET", "https://api.sthan.io/IpGeolocation/8.8.8.8", nil)
req.Header.Set("Authorization", "Bearer YOUR_TOKEN")
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
            

200 Response

{
  "ipAddress": "8.8.8.8",
  "country": "United States",
  "countryCode": "US",
  "region": "California",
  "regionCode": "CA",
  "city": "Mountain View",
  "postalCode": "94043",
  "latitude": 37.422,
  "longitude": -122.085,
  "continent": "North America",
  "continentCode": "NA",
  "timezone": "America/Los_Angeles",
  "timezoneDetail": { "id": "America/Los_Angeles", "utcOffset": "-07:00", "offsetSeconds": -25200, "isDst": true, "currentLocalTime": "2026-10-01T13:13:59-07:00" },
  "type": "IPv4",
  "precision": "city",
  "countryNativeName": "United States",
  "isEu": false,
  "callingCode": "+1",
  "capital": "Washington, D.C.",
  "borders": ["CA", "MX"],
  "currency": { "code": "USD", "name": "United States dollar", "symbol": "$" },
  "languages": ["English"],
  "tld": ".us",
  "flag": { "emoji": "🇺🇸", "svg": "https://sthan.io/flags/us.svg" },
  "asn": 15169,
  "asName": "GOOGLE",
  "isp": "Google LLC",
  "organization": "Google Public DNS",
  "isMobile": false,
  "isProxy": true,
  "isHosting": true,
  "reverseDns": "dns.google",
  "confidence": 0.78
}
            

Try it live

GET

City Autocomplete (India)

/AutoComplete/Ind/City/DisplayType/{displayType}/{text}

Returns real-time city name suggestions for India. Covers all 700+ districts across 28 states and 8 UTs.

Parameters

Name	Type	Required	Description
displayType	int	Required	`0` = City, State `1` = City, District, State
text	string	Required	Partial city name. URL-encoded.

                
                
                
                
                
                
                
                
            
Request

curl -X GET \
  "https://api.sthan.io/AutoComplete/Ind/City/DisplayType/0/mumbai" \
  -H "Authorization: Bearer YOUR_TOKEN"
            

const response = await fetch(
  "https://api.sthan.io/AutoComplete/Ind/City/DisplayType/0/mumbai",
  { headers: { "Authorization": "Bearer YOUR_TOKEN" } }
);
const cities = await response.json();
            

import requests

resp = requests.get(
    "https://api.sthan.io/AutoComplete/Ind/City/DisplayType/0/mumbai",
    headers={"Authorization": "Bearer YOUR_TOKEN"}
)
print(resp.json())
            

using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", "YOUR_TOKEN");

var json = await client.GetStringAsync(
    "https://api.sthan.io/AutoComplete/Ind/City/DisplayType/0/mumbai");
            

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.sthan.io/AutoComplete/Ind/City/DisplayType/0/mumbai"))
    .header("Authorization", "Bearer YOUR_TOKEN")
    .build();
HttpResponse<String> resp = HttpClient.newHttpClient()
    .send(request, HttpResponse.BodyHandlers.ofString());
            

$ch = curl_init("https://api.sthan.io/AutoComplete/Ind/City/DisplayType/0/mumbai");
curl_setopt($ch, CURLOPT_HTTPHEADER, ["Authorization: Bearer YOUR_TOKEN"]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$cities = json_decode(curl_exec($ch), true);
            

uri = URI("https://api.sthan.io/AutoComplete/Ind/City/DisplayType/0/mumbai")
req = Net::HTTP::Get.new(uri)
req["Authorization"] = "Bearer YOUR_TOKEN"
resp = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http|
  http.request(req)
}
cities = JSON.parse(resp.body)
            

req, _ := http.NewRequest("GET",
    "https://api.sthan.io/AutoComplete/Ind/City/DisplayType/0/mumbai", nil)
req.Header.Set("Authorization", "Bearer YOUR_TOKEN")
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
            

200 Response

[
  "Mumbai, Maharashtra",
  "Mumbai Suburban, Maharashtra",
  "Navi Mumbai, Maharashtra",
  "Mumbai City, Maharashtra"
]
            

Try it live

Display Type

City Name

GET

Locality Autocomplete (India)

/AutoComplete/Ind/Locality/DisplayType/{displayType}/{text}

Returns real-time locality (area/neighborhood) suggestions for Indian addresses. Localities are sub-city areas commonly used in Indian addressing.

Parameters

Name	Type	Required	Description
displayType	int	Required	`0` = Locality, City, State `1` = Locality, City, District, State
text	string	Required	Partial locality name. URL-encoded.

                
                
                
                
                
                
                
                
            
Request

curl -X GET \
  "https://api.sthan.io/AutoComplete/Ind/Locality/DisplayType/0/koramangala" \
  -H "Authorization: Bearer YOUR_TOKEN"
            

const response = await fetch(
  "https://api.sthan.io/AutoComplete/Ind/Locality/DisplayType/0/koramangala",
  { headers: { "Authorization": "Bearer YOUR_TOKEN" } }
);
const localities = await response.json();
            

import requests

resp = requests.get(
    "https://api.sthan.io/AutoComplete/Ind/Locality/DisplayType/0/koramangala",
    headers={"Authorization": "Bearer YOUR_TOKEN"}
)
print(resp.json())
            

using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", "YOUR_TOKEN");

var json = await client.GetStringAsync(
    "https://api.sthan.io/AutoComplete/Ind/Locality/DisplayType/0/koramangala");
            

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.sthan.io/AutoComplete/Ind/Locality/DisplayType/0/koramangala"))
    .header("Authorization", "Bearer YOUR_TOKEN")
    .build();
HttpResponse<String> resp = HttpClient.newHttpClient()
    .send(request, HttpResponse.BodyHandlers.ofString());
            

$ch = curl_init("https://api.sthan.io/AutoComplete/Ind/Locality/DisplayType/0/koramangala");
curl_setopt($ch, CURLOPT_HTTPHEADER, ["Authorization: Bearer YOUR_TOKEN"]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$localities = json_decode(curl_exec($ch), true);
            

uri = URI("https://api.sthan.io/AutoComplete/Ind/Locality/DisplayType/0/koramangala")
req = Net::HTTP::Get.new(uri)
req["Authorization"] = "Bearer YOUR_TOKEN"
resp = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http|
  http.request(req)
}
localities = JSON.parse(resp.body)
            

req, _ := http.NewRequest("GET",
    "https://api.sthan.io/AutoComplete/Ind/Locality/DisplayType/0/koramangala", nil)
req.Header.Set("Authorization", "Bearer YOUR_TOKEN")
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
            

200 Response

[
  "Koramangala, Bengaluru, Karnataka",
  "Koramangala 1st Block, Bengaluru, Karnataka",
  "Koramangala 2nd Block, Bengaluru, Karnataka",
  "Koramangala 3rd Block, Bengaluru, Karnataka",
  "Koramangala 4th Block, Bengaluru, Karnataka"
]
            

Try it live

Display Type

Locality Name

GET

PIN Code Autocomplete (India)

/AutoComplete/Ind/PinCode/DisplayType/{displayType}/{text}

Returns real-time PIN code suggestions for India. India uses a 6-digit PIN code system covering over 150,000 post offices.

Parameters

Name	Type	Required	Description
displayType	int	Required	`0` = PinCode, City, State `1` = PinCode, City, District, State
text	string	Required	Partial PIN code or city name. URL-encoded.

                
                
                
                
                
                
                
                
            
Request

curl -X GET \
  "https://api.sthan.io/AutoComplete/Ind/PinCode/DisplayType/0/400001" \
  -H "Authorization: Bearer YOUR_TOKEN"
            

const response = await fetch(
  "https://api.sthan.io/AutoComplete/Ind/PinCode/DisplayType/0/400001",
  { headers: { "Authorization": "Bearer YOUR_TOKEN" } }
);
const pins = await response.json();
            

import requests

resp = requests.get(
    "https://api.sthan.io/AutoComplete/Ind/PinCode/DisplayType/0/400001",
    headers={"Authorization": "Bearer YOUR_TOKEN"}
)
print(resp.json())
            

using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", "YOUR_TOKEN");

var json = await client.GetStringAsync(
    "https://api.sthan.io/AutoComplete/Ind/PinCode/DisplayType/0/400001");
            

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.sthan.io/AutoComplete/Ind/PinCode/DisplayType/0/400001"))
    .header("Authorization", "Bearer YOUR_TOKEN")
    .build();
HttpResponse<String> resp = HttpClient.newHttpClient()
    .send(request, HttpResponse.BodyHandlers.ofString());
            

$ch = curl_init("https://api.sthan.io/AutoComplete/Ind/PinCode/DisplayType/0/400001");
curl_setopt($ch, CURLOPT_HTTPHEADER, ["Authorization: Bearer YOUR_TOKEN"]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$pins = json_decode(curl_exec($ch), true);
            

uri = URI("https://api.sthan.io/AutoComplete/Ind/PinCode/DisplayType/0/400001")
req = Net::HTTP::Get.new(uri)
req["Authorization"] = "Bearer YOUR_TOKEN"
resp = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http|
  http.request(req)
}
pins = JSON.parse(resp.body)
            

req, _ := http.NewRequest("GET",
    "https://api.sthan.io/AutoComplete/Ind/PinCode/DisplayType/0/400001", nil)
req.Header.Set("Authorization", "Bearer YOUR_TOKEN")
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
            

200 Response

[
  "400001, Mumbai, Maharashtra",
  "400002, Mumbai, Maharashtra",
  "400003, Mumbai, Maharashtra",
  "400004, Mumbai, Maharashtra",
  "400005, Mumbai, Maharashtra"
]
            

Try it live

Display Type

PIN Code or City

Error Handling

All endpoints return consistent error responses. Check the IsError field and StatusCode for error detection.

HTTP Status Codes

Code	Meaning	Common Cause
200	Success	Request processed successfully
400	Bad Request	Invalid parameters or empty address
401	Unauthorized	Missing or invalid auth token
403	Forbidden	Token lacks permission for this endpoint
429	Rate Limited	Too many requests. Slow down or upgrade plan.
500	Server Error	Internal error. Contact support if persistent.

Error Response Example

{
  "StatusCode": 400,
  "IsError": true,
  "Errors": [
    "Arguments cannot be null or empty"
  ]
}
        