Place search

GET

/geo/search

request.sh

curl -X GET https://api.astroway.info/v1/geo/search?q=Kiev \
  -H "X-Api-Key: aw_live_..." \
  -H "Content-Type: application/json"

▸ Спробувати GET /geo/search

• Production

A place name to candidates with coordinates and the IANA zone, for a birthplace field. Matches a prefix, ignores case, accents and punctuation (krakow finds Kraków, St. Petersburg finds Saint Petersburg), and knows the names GeoNames carries in our 21 languages and older ones such as Kiev. Ranked by population, an exact name counting ten times its size, so an ambiguous name such as Springfield lists every town largest first; q=Springfield, Illinois or Springfield, MA narrows by region or country after the comma. lang names the place, region and country in that language where the data has the name; originalName is then the GeoNames name. Covers populated places of 1000 people or more plus administrative seats, about 172 000 places: a smaller village is absent, not misspelled. Attribution is in the body because displaying the data carries the CC BY credit. A keyless twin for widgets is GET /public/geo/search.

Authorizations

• ApiKeyAuth

Parameters

Query Parameters

q required

string

>= 1 characters <= 100 characters

Example

Kiev

Place name or its beginning, in any of our languages and scripts. Case, accents and punctuation are ignored. Text after the first comma narrows by region or country instead: Springfield, Illinois, Springfield, MA, Paris, US.

lang

string

Allowed values: uk en de pl es pt fr it nl cs ro hu el tr ar hi ja ko vi id ru

Example

uk

Language for name, admin1 and country. Where GeoNames has no name in it, the GeoNames name stays. Matching always covers every language.

limit

integer

default: 10 >= 1 <= 50

Example

5

How many candidates to return.

country

string

/^[A-Za-z]{2}(,[A-Za-z]{2}){0,19}$/

Example

UA,PL

Restrict to these ISO 3166-1 alpha-2 codes, comma separated, up to 20.

fields

string

Comma-separated dotted paths, relative to data, to keep in the response. A path is applied to every element of an array, so planets.name means the name of each planet. Paths that match nothing come back in _fields_unmatched; a list where nothing matches at all is a 400, because an empty object would be a confident wrong answer.

Example

planets.name,planets.longitude

precision

integer

<= 15

Round every non-integer number in the response to this many decimal places. Integers are left alone, because an id is not a measurement. Ecliptic longitudes ship with fourteen decimals by default; 2 is about a tenth of an arcminute.

Example

4

Responses

200

Successful calculation

Media type application/json

object

ok

boolean

data

object

query

string

nullable

lang

string

nullable

count

number

nullable

results

Array<object>

nullable

object

id

number

nullable

name

string

nullable

originalName

string

nullable

admin1

string

nullable

admin1Code

string

nullable

countryCode

string

nullable

country

string

nullable

latitude

number

nullable

longitude

number

nullable

timezone

string

nullable

population

number

nullable

featureCode

string

nullable

matchedName

string

nullable

exact

boolean

nullable

note

string

nullable

dataset

object

source

string

nullable

url

string

nullable

namesUrl

string

nullable

licence

string

nullable

downloaded

string

nullable

count

number

nullable

attribution

object

source

string

nullable

sourceUrl

string

nullable

licence

string

nullable

licenceUrl

string

nullable

notice

string

nullable

Example

{
  "ok": true,
  "data": {
    "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",
      "url": "https://download.geonames.org/export/dump/cities1000.zip",
      "namesUrl": "https://download.geonames.org/export/dump/alternateNamesV2.zip",
      "licence": "CC BY 4.0",
      "downloaded": "2026-11-07",
      "count": 171800
    },
    "attribution": {
      "source": "GeoNames",
      "sourceUrl": "https://www.geonames.org/",
      "licence": "CC BY 4.0",
      "licenceUrl": "https://creativecommons.org/licenses/by/4.0/",
      "notice": "Place names, coordinates and populations from the GeoNames geographical database, used under CC BY 4.0. Displaying this data requires carrying the same credit."
    }
  }
}

400

Validation error

Media type application/json

Example

{
  "ok": false,
  "error": {
    "code": "INVALID_INPUT",
    "message": "Validation failed: date: Date must be YYYY-MM-DD",
    "details": [
      {
        "path": "date",
        "message": "Date must be YYYY-MM-DD"
      }
    ]
  }
}

401

Missing or invalid API key

Media type application/json

Example

{
  "ok": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Invalid API key"
  }
}