Search for locations by name

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

get/location/autocomplete

Request

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

Query parameters

querystring required

Search query (city name, address, etc.)

Example:San Francisco

limitinteger

Maximum number of suggestions to return

countrystring nullable

Optional ISO 3166-1 alpha-2 country code (e.g., US, GB) used to bias ranking toward that country. Boost, not filter: results in other countries remain reachable.

regionstring nullable

Optional admin1 (state/province/region) qualifier used to bias ranking. Accepts a full name ("Michigan", "Quebec"), an ASCII name, or a GeoNames admin1 code ("MI"). Boost, not filter.

admin1string nullable

Alias for region: admin1 (state/province) qualifier used to bias ranking. region takes precedence if both are supplied.

nearstring nullable

Optional "lat,lon" proximity hint (e.g., "37.77,-122.42") used to bias ranking toward nearby places. Boost, not filter.

Headers

authorizationstring nullable

X-API-Keystring nullable

X-OpenEphemeris-API-Keystring nullable

apikeystring nullable

Response

Successful Response

cachedboolean

True if results were served from cache

querystring required

Original search query

total_resultsinteger required

Number of suggestions returned

Example response

{
  "cached": false,
  "query": "san fran",
  "suggestions": [
    {
      "confidence": 0.97,
      "country_code": "US",
      "display_name": "San Francisco, California, United States",
      "latitude": 37.7749,
      "longitude": -122.4194,
      "place_id": "place.12345",
      "short_name": "San Francisco",
      "timezone": "America/Los_Angeles"
    }
  ],
  "total_results": 1
}

Changes

No recorded changes to this operation across all 1 revision of this API.