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

Endpoint

GET /v1/utils/geocode

Request parameters

Field	Type	Required	Description
q	string	Yes	City or location name. Use comma for disambiguation: 'Fatehabad,Haryana'
limit	integer	No	Maximum results to return
country	string | null	No	ISO country code to narrow results, e.g. 'in', 'us'

Example request

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);

Example response

{
  "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
  }
}

Response fields

Field	Type	Description
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

Code	Description	Reference
authentication_failed	Missing or invalid API key.	authentication_failed
ephemeris_unavailable	Upstream ephemeris service error.	ephemeris_unavailable
insufficient_tier	API key tier does not include this endpoint.	insufficient_tier
internal_error	Unexpected server error.	internal_error
ip_rate_limit_exceeded	Too many requests in a short window.	ip_rate_limit_exceeded
payload_too_large	Request body exceeds the size limit.	payload_too_large
resource_not_found	Referenced resource was not found.	resource_not_found
validation_error	Request body failed schema validation.	validation_error

Related endpoints

• Return the IANA timezone for a given coordinate pair