---
title: "Search for locations by name"
method: GET
path: "/location/autocomplete"
tags: ["location-timezone"]
---

# Search for locations by name

`GET /location/autocomplete`

## Request

- Base URL: `https://api.openephemeris.com`
- URL: `https://api.openephemeris.com/location/autocomplete`
- Auth: HTTP bearer

Returns location suggestions with coordinates and timezone for typeahead search. Results are cached according to backend cache configuration.

## Query parameters

- `query` string, required: Search query (city name, address, etc.)
- `limit` integer: Maximum number of suggestions to return
- `country` string, nullable
- `region` string, nullable
- `admin1` string, nullable
- `near` string, nullable

## Headers

- `authorization` string, nullable
- `X-API-Key` string, nullable
- `X-OpenEphemeris-API-Key` string, nullable
- `apikey` string, nullable

## Response `200`

Successful Response

- LocationAutocompleteResponse: Response for /location/autocomplete endpoint.
  - `cached` boolean: True if results were served from cache
  - `query` string, required: Original search query
  - `suggestions` LocationSuggestion[]: List of matching location suggestions
    - `confidence` number: Optional confidence score from the provider (0-1)
    - `country_code` string: ISO 3166-1 alpha-2 country code (e.g., US, GB)
    - `display_name` string, required: Full human-readable name
    - `latitude` number, required: Latitude in decimal degrees
    - `longitude` number, required: Longitude in decimal degrees
    - `place_id` string, required: Provider-specific place identifier
    - `region` string: Human-readable admin1 (state/province/region) name, e.g. "Michigan", "Quebec". Omitted when it cannot be resolved.
    - `short_name` string, required: Short label suitable for UI chips
    - `timezone` string, required: IANA timezone identifier (e.g., America/Los_Angeles)
  - `total_results` integer, required: Number of suggestions returned

## Other responses

- `400`: Bad Request - Invalid parameters
- `422`: Validation Error
- `503`: Service Unavailable - Geocoding provider down

---

[API](https://skmtc.dev/openephemeris/apis/open-ephemeris-api.md) · [All operations](https://skmtc.dev/openephemeris/apis/open-ephemeris-api/llms.txt) · [OpenAPI document](https://skmtc.dev/openephemeris/apis/open-ephemeris-api/revisions/d195a769cb89?raw)