Public

Place search (public, no key)

Changed on

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).

get/public/geo/search

Request

  • Base URL
    https://api.astroway.info/v1
  • Auth
    none required

Query parameters

qstring required
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'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.

limitinteger
Example:5

How many candidates to return.

countrystring
Example:UA,PL

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

fieldsstring

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.

precisioninteger

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.

Response

OK

okboolean
_footerstring

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

Example response

{
  "ok": true,
  "_footer": "Powered by astroway.api - get your own key at https://api.astroway.info"
}

Changes