GET/v1/utils/geocode

Resolve a city or place name to latitude, longitude, and timezone

Resolve a city or place name to coordinates and timezone. Returns up to {limit} matches. 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. 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.

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

authentication_failed

Missing or invalid API key.

ephemeris_unavailable

Upstream ephemeris service error.

insufficient_tier

API key tier does not include this endpoint.

internal_error

Unexpected server error.

ip_rate_limit_exceeded

Too many requests in a short window.

payload_too_large

Request body exceeds the size limit.

resource_not_found

Referenced resource was not found.

validation_error

Request body failed schema validation.

Related endpoints

• Return the IANA timezone for a given coordinate pair

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": "230315199"
      }
    ],
    "tip": null
  }
}