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. Get 100,000 requests/month instantly.

2

Get Your API Key

Go to your Dashboard and copy your API key. Use it in the Authorization header of every request.

3

Make Your First Call

Copy any example below and replace YOUR_API_KEY with your actual key. That's it!

Authentication

Sthan.io uses a two-step authentication flow. First, obtain a JWT token using your profile credentials. Then, include that token as a Bearer token in all subsequent API requests.

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 { access_token, expiration } = await response.json();
// 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()["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 to get 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 to get 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["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)["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 to get access_token
                

200 Response

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJodHRwOi8vc2NoZW1hcy5...",
  "expiration": "2026-02-19T03:45:00.0000000"
}
                

Response Fields

Field	Type	Description
access_token	string	JWT Bearer token. Include in `Authorization` header for all API calls.
expiration	datetime	UTC expiration timestamp. Request a new token before this time.

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

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.

Plan	Requests / Month	Burst Rate
Free	100,000	10 req/sec
Starter	500,000	50 req/sec
Basic	2,000,000	100 req/sec

            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. Powered by USPS data with support for 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_API_KEY"
            

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

import requests

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

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

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

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_API_KEY")
    .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_API_KEY"
]);
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_API_KEY"
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_API_KEY")

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

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, White Plains, NY 10601-3104",
  "123 Main St, Brockton, MA 02301-6204"
]
            

Try it live

Type-ahead demo — results appear as you type. Calls server-side proxy with demo credentials.

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

Address Parser

From $9/mo

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

View docs →

Address Verification

From $7/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

/AddressParser/USA/Single/{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/AddressParser/USA/Single/1345%20avenue%20of%20americas" \
  -H "Authorization: Bearer YOUR_API_KEY"
            

const response = await fetch(
  "https://api.sthan.io/AddressParser/USA/Single/1345%20avenue%20of%20americas",
  { headers: { "Authorization": "Bearer YOUR_API_KEY" } }
);
const parsed = await response.json();
console.log(parsed.city);       // "New York"
console.log(parsed.confidence); // 0.98
            

import requests

resp = requests.get(
    "https://api.sthan.io/AddressParser/USA/Single/1345%20avenue%20of%20americas",
    headers={"Authorization": "Bearer YOUR_API_KEY"}
)
parsed = resp.json()
print(f"{parsed['city']}, {parsed['stateCode']} - Confidence: {parsed['confidence']}")
            

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

var json = await client.GetStringAsync(
    "https://api.sthan.io/AddressParser/USA/Single/1345%20avenue%20of%20americas");
// Deserialize to your model class
            

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.sthan.io/AddressParser/USA/Single/1345%20avenue%20of%20americas"))
    .header("Authorization", "Bearer YOUR_API_KEY")
    .build();
HttpResponse<String> resp = client.send(request,
    HttpResponse.BodyHandlers.ofString());
            

$ch = curl_init("https://api.sthan.io/AddressParser/USA/Single/1345%20avenue%20of%20americas");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer YOUR_API_KEY"
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$parsed = json_decode(curl_exec($ch), true);
            

require 'net/http'
require 'json'

uri = URI("https://api.sthan.io/AddressParser/USA/Single/1345%20avenue%20of%20americas")
req = Net::HTTP::Get.new(uri)
req["Authorization"] = "Bearer YOUR_API_KEY"
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/AddressParser/USA/Single/1345%20avenue%20of%20americas", nil)
req.Header.Set("Authorization", "Bearer YOUR_API_KEY")

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

200 Response

{
  "inputAddress": "1345 avenue of americas",
  "fullAddress": "1345 Avenue of the Americas, New York, NY 10105-2701",
  "addressLine1": "1345 Avenue of the Americas",
  "addressNumber": "1345",
  "streetName": "Avenue of the Americas",
  "city": "New York",
  "stateCode": "NY",
  "state": "New York",
  "zipCode": "10105",
  "zip4": "2701",
  "county": "New York",
  "isUspsVerified": true,
  "confidence": 0.98
}
            

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
isUspsVerified	bool	Whether USPS confirmed the address exists
confidence	float	Match confidence score (0.0 – 1.0)

Try it live

Live demo — calls server-side proxy with demo credentials. No API key needed.

GET

Address Verification

/AddressVerification/Usa/Single/{address}

Verifies a US address against USPS data 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/AddressVerification/Usa/Single/1111%20howe%20ave%20sacramento%20ca" \
  -H "Authorization: Bearer YOUR_API_KEY"
            

const response = await fetch(
  "https://api.sthan.io/AddressVerification/Usa/Single/1111%20howe%20ave%20sacramento%20ca",
  { headers: { "Authorization": "Bearer YOUR_API_KEY" } }
);
const result = await response.json();
console.log(result.dpvConfirmation); // "Y" = deliverable
            

import requests

resp = requests.get(
    "https://api.sthan.io/AddressVerification/Usa/Single/1111%20howe%20ave%20sacramento%20ca",
    headers={"Authorization": "Bearer YOUR_API_KEY"}
)
result = resp.json()
print(f"Deliverable: {result['dpvConfirmation'] == 'Y'}")
            

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

var result = await client.GetFromJsonAsync<VerifiedAddress>(
    "https://api.sthan.io/AddressVerification/Usa/Single/1111%20howe%20ave%20sacramento%20ca");
Console.WriteLine($"DPV: {result.DpvConfirmation}");
            

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.sthan.io/AddressVerification/Usa/Single/1111%20howe%20ave%20sacramento%20ca"))
    .header("Authorization", "Bearer YOUR_API_KEY")
    .build();
HttpResponse<String> resp = client.send(request,
    HttpResponse.BodyHandlers.ofString());
            

$ch = curl_init("https://api.sthan.io/AddressVerification/Usa/Single/1111%20howe%20ave%20sacramento%20ca");
curl_setopt($ch, CURLOPT_HTTPHEADER, ["Authorization: Bearer YOUR_API_KEY"]);
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/AddressVerification/Usa/Single/1111%20howe%20ave%20sacramento%20ca")
req = Net::HTTP::Get.new(uri)
req["Authorization"] = "Bearer YOUR_API_KEY"
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/AddressVerification/Usa/Single/1111%20howe%20ave%20sacramento%20ca", nil)
req.Header.Set("Authorization", "Bearer YOUR_API_KEY")

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

200 Response

{
  "inputAddress": "1111 howe ave sacramento ca",
  "fullAddress": "1111 Howe Ave, Sacramento, CA 95825-7123",
  "addressLine1": "1111 Howe Ave",
  "city": "Sacramento",
  "stateCode": "CA",
  "county": "Sacramento",
  "zipCode": "95825",
  "zip4": "7123",
  "carrierRoute": "C001",
  "deliveryPoint": "12",
  "dpvConfirmation": "Y",
  "recordType": "S"
}
            

Response Fields

Field	Type	Description
dpvConfirmation	string	`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

Try it live

Live demo — calls server-side proxy with demo credentials. No API key needed.

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_API_KEY"
            

const response = await fetch(
  "https://api.sthan.io/AutoComplete/USA/City/DisplayType/0/sacram",
  { headers: { "Authorization": "Bearer YOUR_API_KEY" } }
);
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_API_KEY"}
)
print(resp.json())
            

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

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_API_KEY")
    .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_API_KEY"]);
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_API_KEY"
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_API_KEY")
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

Type-ahead demo — results appear as you type. Calls server-side proxy with demo credentials.

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_API_KEY"
            

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

import requests

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

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

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_API_KEY")
    .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_API_KEY"]);
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_API_KEY"
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_API_KEY")
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

Type-ahead demo — results appear as you type. Calls server-side proxy with demo credentials.

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_API_KEY"
            

const response = await fetch(
  "https://api.sthan.io/Geocoding/USA/Forward/1600%20Pennsylvania%20Ave%20NW%20Washington%20DC",
  { headers: { "Authorization": "Bearer YOUR_API_KEY" } }
);
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_API_KEY"}
)
geo = resp.json()
print(f"Lat: {geo['latitude']}, Lng: {geo['longitude']}")
            

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

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_API_KEY")
    .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_API_KEY"]);
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_API_KEY"
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_API_KEY")
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
            

200 Response

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

Try it live

Live demo — calls server-side proxy with demo credentials. No API key needed.

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_API_KEY"
            

const response = await fetch(
  "https://api.sthan.io/Geocoding/USA/Reverse/38.897676/-77.036530",
  { headers: { "Authorization": "Bearer YOUR_API_KEY" } }
);
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_API_KEY"}
)
addr = resp.json()
print(addr['fullAddress'])
            

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

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_API_KEY")
    .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_API_KEY"]);
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_API_KEY"
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_API_KEY")
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

Live demo — calls server-side proxy with demo credentials. No API key needed.

GET

IP Geolocation

/IpGeolocation/{ip}

Look up the geographic location of any IPv4 or IPv6 address. Returns country, region, city, coordinates, timezone, and postal code.

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_API_KEY"
            

const response = await fetch(
  "https://api.sthan.io/IpGeolocation/8.8.8.8",
  { headers: { "Authorization": "Bearer YOUR_API_KEY" } }
);
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_API_KEY"}
)
geo = resp.json()
print(f"{geo['city']}, {geo['region']}, {geo['country']}")
            

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

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_API_KEY")
    .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_API_KEY"]);
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_API_KEY"
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_API_KEY")
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",
  "city": "Mountain View",
  "latitude": 37.405991,
  "longitude": -122.078514,
  "timezone": "America/Los_Angeles",
  "postalCode": "94043"
}
            

Try it live

Leave blank and hit Send to look up your own IP. No API key needed.

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_API_KEY"
            

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

import requests

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

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

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_API_KEY")
    .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_API_KEY"]);
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_API_KEY"
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_API_KEY")
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

Type-ahead demo — results appear as you type. Calls server-side proxy with demo credentials.

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_API_KEY"
            

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

import requests

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

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

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_API_KEY")
    .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_API_KEY"]);
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_API_KEY"
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_API_KEY")
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

Type-ahead demo — results appear as you type. Calls server-side proxy with demo credentials.

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_API_KEY"
            

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

import requests

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

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

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_API_KEY")
    .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_API_KEY"]);
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_API_KEY"
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_API_KEY")
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

Type-ahead demo — results appear as you type. Calls server-side proxy with demo credentials.

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 API key
403	Forbidden	API key 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"
  ]
}
        

Sthan.io API Documentation

Quick Start

Create a Free Account

Get Your API Key

Make Your First Call

Authentication

Step 1: Get Your Token

Step 2: Use the Token

Rate Limits

Address Autocomplete

Try it live

Address Parser

Address Verification

Forward Geocoding

Address Parser

Try it live

Address Verification

Try it live

City Autocomplete

Try it live

ZIP Code Autocomplete

Try it live

Forward Geocoding

Try it live

Reverse Geocoding

Try it live

IP Geolocation

Try it live

City Autocomplete (India)

Try it live

Locality Autocomplete (India)

Try it live

PIN Code Autocomplete (India)

Try it live

Error Handling