Place search (public, no key)

GET

/public/geo/search

Code sample: cURL

request.sh

curl 'https://api.astroway.info/v1/public/geo/search?q=Kiev&lang=uk&limit=1'

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

• Production

The same answer as GET /geo/search without a key, for a birthplace field in a widget or a static page: candidates with coordinates, IANA zone, population and names in our 21 languages. Costs 1 unit of the public bucket (30 an hour per address without a key), so search after the visitor pauses typing rather than on every key. Cache-Control: public, max-age=86400. Attribution is in the body: displaying the data carries the GeoNames CC BY 4.0 credit. Reverse lookup and the offset on a date stay keyed (GET /geo/reverse, GET /geo/timezone).

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

OK

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

_footer

Free-tier watermark, present on every public response. Keys on a paid plan do not receive it.

string

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."
    }
  },
  "_footer": "Powered by astroway.api - get your own key at https://api.astroway.info"
}

400

Invalid sign or date

Media type application/json

Example

{
  "ok": false,
  "error": {
    "code": "INVALID_SIGN",
    "message": "sign must be one of the 12 zodiac signs"
  }
}