GET/v1/utils/geocode

Geocode a Place to Coordinates and Timezone

Resolve a city or place name to coordinates and timezone. Returns up to limit matches (default 5, at most 10). When a query is ambiguous (e.g. 'Fatehabad' exists in multiple states), multiple results are returned so the developer can present a disambiguation UI or use the first result. Repeat matches for one place (same city, state and country within 5 km) are listed once. Examples: ?q=Mumbai, ?q=Rome Italy, ?q=New York USA, ?q=London UK Pass state/country for precise results: ?q=Fatehabad,Haryana or ?q=Fatehabad&country=in

Request parameters

qrequired

string

City or location name. Use comma for disambiguation: 'Fatehabad,Haryana'

limitoptional

integer

Maximum results to return

countryoptional

string | null

ISO country code to narrow results, e.g. 'in', 'us'

Response fields

success

boolean

True if the request succeeded

message

string

Human-readable status message

data

object

data.query

string

The search query as received.

data.count

integer

Number of results returned.

data.ambiguous

boolean

True if multiple locations matched the query.

data.results

array[object]

List of matching locations, best match first. Repeat matches for one place (same city, state and country within 5 km) are listed once.

data.results[].label

string

Human-readable location label.

data.results[].city

string | null

City name.

data.results[].state

string | null

State or region.

data.results[].country

string | null

Country name.

data.results[].latitude

number

Latitude in decimal degrees.

data.results[].longitude

number

Longitude in decimal degrees.

data.results[].timezone

string

IANA timezone identifier.

data.results[].place_id

string

Nominatim place ID.

data.tip

string | null

Disambiguation hint when ambiguous is True.

Errors

api_key_invalid

Invalid API key format.

api_key_missing

API key is missing. Include it in the Authorization header as 'Bearer YOUR_KEY'.

api_key_not_found

The provided API key was not found. Verify the key in your Asterwise dashboard.

api_key_revoked

This API key has been revoked.

burst_limit_exceeded

Too many requests per minute. Please slow down.

internal_error

Something went wrong on our end. Please try again, or contact [email protected] if the problem persists. Include your request_id when contacting support.

ip_rate_limit_exceeded

Too many requests from this IP address. Please slow down.

monthly_usage_limit_exceeded

Monthly API call limit reached. Upgrade your plan to continue.

payload_too_large

Request body exceeds maximum allowed size of 64KB.

subscription_expired

Your subscription has expired. Please renew at asterwise.com/dashboard to continue.

validation_error

The request couldn't be processed. See the 'details' field for specific field-level issues.

Related endpoints

• IANA Timezone for Coordinates

Request

GET·application/json

curl

curl -X GET "https://api.asterwise.com/v1/utils/geocode?q=Mumbai&limit=3" \
  -H "Authorization: Bearer YOUR_API_KEY"

Python

import asterwise
from asterwise.api.utilities_api import UtilitiesApi

configuration = asterwise.Configuration(
    host="https://api.asterwise.com",
    access_token="YOUR_API_KEY",
)

with asterwise.ApiClient(configuration) as client:
    api = UtilitiesApi(client)
    result = api.geocode(q="Mumbai",
    limit=3)
    print(result)

TypeScript

import { createClient, createConfig, geocode } from 'asterwise';

const client = createClient(createConfig({
  baseUrl: 'https://api.asterwise.com',
  headers: { Authorization: 'Bearer YOUR_API_KEY' },
}));

const result = await geocode({
  client,
  query: {
      "q": "Mumbai",
      "limit": 3
  },
});

console.log(result.data);

Response

200 OK·application/jsonsigned

{
  "success": true,
  "message": "success",
  "data": {
    "query": "Mumbai",
    "count": 1,
    "ambiguous": false,
    "results": [
      {
        "label": "Mumbai, Maharashtra, India",
        "city": "Mumbai",
        "state": "Maharashtra",
        "country": "India",
        "latitude": 19.054999,
        "longitude": 72.8692035,
        "timezone": "Asia/Kolkata",
        "place_id": "246861342"
      }
    ],
    "tip": null
  }
}