Location search

Three lookups for a birthplace field: from a name to coordinates and the time zone, from coordinates to the nearest place, and from a point and a date to the offset the clocks kept that day. All three answer from the GeoNames geographical database and the IANA time zone database.

Search by name

GET /v1/geo/search?q=Kiev&lang=uk&limit=5 HTTP/1.1
X-Api-Key: aw_live_...

• q: required, the name or its beginning, in any of our languages and scripts. Case, accents and punctuation do not matter: krakow finds Kraków, St. Petersburg finds Saint Petersburg, Kiev and Київ find Kyiv.
• Text after the first comma narrows by region or country instead of matching the name: Springfield, Illinois, Springfield, MA, Paris, US.
• lang: optional, one of the 21 site languages. Names the place, region and country in that language where the data has the name. Matching covers every language whatever you pass.
• limit: 1 to 50, 10 by default.
• country: optional, ISO 3166-1 alpha-2 codes, comma separated, up to 20: country=UA,PL.

{
  "query": "Kiev",
  "lang": "uk",
  "count": 1,
  "results": [
    {
      "id": 703448,
      "name": "Київ",
      "originalName": "Kyiv",
      "admin1": "Місто Київ",
      "admin1Code": "12",
      "countryCode": "UA",
      "country": "Україна",
      "latitude": 50.4547,
      "longitude": 30.5238,
      "timezone": "Europe/Kyiv",
      "population": 2952301,
      "featureCode": "PPLC",
      "matchedName": "Kiev",
      "exact": true
    }
  ],
  "note": "Populated places of 1000 people or more and administrative seats. A smaller place is absent, not misspelled.",
  "dataset": { "source": "GeoNames cities1000", "licence": "CC BY 4.0", "downloaded": "2026-11-07", "count": 171800 },
  "attribution": { "source": "GeoNames", "licence": "CC BY 4.0", "notice": "..." }
}

• id is the GeoNames identifier: stable, safe to store.
• originalName appears only when name is a translation.
• matchedName is the form your query matched, for example the older Kiev; exact says whether it matched the whole name or only its beginning.
• featureCode is the GeoNames class: PPLC a capital, PPLA the seat of a first-level region, PPLX a section of a city.

Results are ranked by population, and a whole-name match counts ten times its size: an ambiguous name such as Springfield lists every town of that name largest first, and kyi puts Kyiv above a village called Kyi.

Pass latitude, longitude and timezone from the result straight into a chart. timezone takes the zone name, and the API works out the offset for the birth date itself.

Nearest place to a point

GET /v1/geo/reverse?lat=49.8397&lon=24.0297&lang=en HTTP/1.1
X-Api-Key: aw_live_...

{
  "latitude": 49.8397,
  "longitude": 24.0297,
  "timezone": "Europe/Kyiv",
  "nautical": false,
  "place": { "id": 702550, "name": "Lviv", "countryCode": "UA", "timezone": "Europe/Kyiv", "featureCode": "PPLA", "distanceKm": 0.5 }
}

timezone is the zone of the point itself, which near a border can differ from the place’s. The search is by great-circle distance and works across the 180th meridian and at the poles. At sea nautical is true and the zone is the nautical hour band, for example Etc/GMT+2, which is UTC-2: the sign in these names is inverted by convention. place.distanceKm tells you how far land is.

Offset on a date

GET /v1/geo/timezone?lat=50.45&lon=30.52&date=1990-05-15&time=15:30 HTTP/1.1
X-Api-Key: aw_live_...

{ "timezone": "Europe/Kyiv", "date": "1990-05-15", "time": "15:30", "utcOffset": 4, "utcOffsetText": "+04:00", "standardOffset": 3, "isDst": true, "nautical": false }

The offset comes from the time zone database for that date, never from a fixed table: Kyiv answers +2 in January, +3 in July and +4 in May 1990, when it kept Moscow summer time. date is today by default, time is 12:00 and matters only on the day clocks change: an hour that was skipped resolves to the offset from before the change, an hour that happened twice to its first occurrence. Before 1970 the database is not reliable everywhere; if you know what the local clock read, send timezoneOffset to the chart.

Without a key, for widgets

GET /v1/public/geo/search?q=Kiev&lang=uk&limit=5 HTTP/1.1

The same search answers without a key for a birthplace field on a public page. It counts against the public limit of 30 requests an hour per visitor address, so send the request when the visitor pauses typing rather than on every key. The answer may be cached for a day. Reverse lookup and the offset on a date need a key; for a browser, use a publishable key limited to geo/*.

What is covered

About 172 000 places: every populated place of 1000 people or more, plus seats of administrative regions. A smaller village is absent rather than misspelled, so offer the nearest town or let the user enter coordinates. Names are the ones GeoNames carries in our languages; where a language has no name, the GeoNames name is returned.

Attribution

Place data is from GeoNames under CC BY 4.0. If you show these names or coordinates to your users, carry the same credit: it comes in every answer as attribution.

Price

/v1/geo/search, /v1/geo/reverse and /v1/geo/timezone cost 5 credits each.

The keyless search spends no credits and has the public limit instead.