---
title: "Geocode a Place to Coordinates and Timezone"
method: GET
path: "/v1/utils/geocode"
tags: ["Utilities"]
---

# Geocode a Place to Coordinates and Timezone

`GET /v1/utils/geocode`

## Request

- Base URL: `https://api.asterwise.com`
- URL: `https://api.asterwise.com/v1/utils/geocode`
- Auth: HTTP bearer

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

## Query parameters

- `q` string, required: City or location name. Use comma for disambiguation: 'Fatehabad,Haryana'
- `limit` integer: Maximum results to return
- `country` string, nullable: ISO country code to narrow results, e.g. 'in', 'us'

## Response `200`

Successful Response

- ApiResponseGeocodeResponse
  - `success` boolean: True if the request succeeded
  - `message` string: Human-readable status message
  - `data` GeocodeResponse, required
    - `query` string, required: The search query as received.
    - `count` integer, required: Number of results returned.
    - `ambiguous` boolean, required: True if multiple locations matched the query.
    - `results` GeocodeResult[], required: List of matching locations, best match first. Repeat matches for one place (same city, state and country within 5 km) are listed once.
      - `label` string, required: Human-readable location label.
      - `city` string, nullable: City name.
      - `state` string, nullable: State or region.
      - `country` string, nullable: Country name.
      - `latitude` number, required: Latitude in decimal degrees.
      - `longitude` number, required: Longitude in decimal degrees.
      - `timezone` string, required: IANA timezone identifier.
      - `place_id` string, required: Nominatim place ID.
    - `tip` string, nullable: Disambiguation hint when ambiguous is True.

## Other responses

- `401`: Authentication failed
- `403`: Authorization failed
- `404`: Resource not found
- `413`: Payload too large
- `422`: Validation error
- `429`: Rate limit exceeded
- `500`: Internal error
- `502`: Upstream provider error
- `503`: Service unavailable

---

[API](https://skmtc.dev/asterwise/apis/asterwise-api.md) · [All operations](https://skmtc.dev/asterwise/apis/asterwise-api/llms.txt) · [OpenAPI document](https://skmtc.dev/asterwise/apis/asterwise-api/revisions/3c4bbb1194e2?raw)