Place-name search and reverse lookup against the self-hosted GeoNames index, returning name, region, country, coordinates and IANA timezone with a stable place_id

Place-name search and reverse lookup against the self-hosted GeoNames index, returning name, region, country, coordinates and IANA timezone with a stable place_id. Formats: json, csv. Every response is GeoNames data under CC BY 4.0, so every response carries rights: attribution_required and the credit in meta.attribution.text. The rest of the API is unrestricted. Example: GET /v2/places?q=cambridge&limit=5

get/v2/places

Request

  • Base URL: https://www.cyclecalcs.com
  • URL: https://www.cyclecalcs.com/v2/places
  • Auth: one of:
    • none
    • API key in header X-RapidAPI-Key

Query parameters

qstring

A place name to search for, at least 2 characters after trimming. Mutually exclusive with id and with lat/lon.

idstring

An exact place_id from a previous /v2/places response, for example us-n35198-w111651. Mutually exclusive with q and with lat/lon.

latnumber

Latitude in decimal degrees, north positive. No compass suffix (do not append N or S). Required together with lon, or neither.

lonnumber

Longitude in decimal degrees, east positive. No compass suffix (do not append E or W). Required together with lat, or neither.

countrystring

Restricts a name search to one country: an ISO 3166-1 alpha-2 code (case-insensitive) or a country name.

regionstring

Restricts a name search to one admin region (state or province name) as stored in the index.

limitinteger

Maximum number of place matches to return, 1 to 25.

min_populationinteger

Only return places at or above this population. The index stores population to the nearest 1,000, so the value is rounded up to the next thousand.

radius_kmnumber

Search radius in kilometres for a reverse (lat/lon) lookup. Default 250.

formatstring

Response representation. Each endpoint serves a subset of json, csv and txt; see that operation's description for the exact list, or GET /v2 for every endpoint's formats array. An unsupported value is 400 BAD_FORMAT with the accepted list in supported.

fieldsstring

Comma-separated dot paths into data (for example moon.phase_name,moon.illumination) so only those fields are returned. Up to 64 paths; an array element is addressed by its object key, never by index.

shape'nested' | 'flat'

nested returns the documented object tree. flat returns one object with dotted keys, format=json only.

precisioninteger

Decimal places for numeric fields.

pretty0 | 1

Whether the JSON body is indented (1) or compact (0). Has no effect on csv or txt.

verbosity'full' | 'compact'

full includes prose notes, frame definitions and withheld-field reasons in meta. compact keeps every value and every machine-readable name and drops the prose.

time_format'iso' | 'unix'

How instants are rendered: iso for ISO 8601 strings carrying the effective offset, or unix for integer seconds since the epoch. An ISO offset has no seconds field, so an instant in a pre-1972 local mean time era whose offset has seconds (Moscow +02:30:17 until 1916) is written in UTC with a Z; utc_offset_seconds stays exact, utc_offset_iso rounds it to the nearest minute, and the tzdb_lmt_interval warning says so.

Response

The answer. Every response is GeoNames data under CC BY 4.0, so every response carries rights: attribution_required and the credit in meta.attribution.text. The rest of the API is unrestricted.

endpointstring required

The endpoint path that produced this response.

computed_atstring date-time required

A revision stamp, never a wall clock: identical requests return identical bytes, so a fixed_instant or reference response can be cached for a year and 304 stays reachable.

queryobject required

The request as understood: every resolved input (instant, location, presentation options) plus ignored, in the order spec-00 13.2 defines. Shape is endpoint-specific.

dataunknown required
linksobject required

Related URLs. self reproduces this exact response; docs is always present; others (page, spec, next, first, explain) appear where relevant.

metaobject required

Provenance: engine version, rights and attribution, cache class, accuracy statement, tzdb version, and endpoint-specific conventions (refraction model, horizon definitions, time scales, and so on). Never subject to fields projection.

attributionstring required

The credit line, byte-identical to meta.attribution.text.

docsstring uri required

The human-readable reference section for this endpoint.

Example response

{
  "endpoint": "/v2/sun",
  "computed_at": "2026-08-01T00:00:00.000Z",
  "links": {
    "self": "https://www.cyclecalcs.com/v2/sun?at=2026-06-21&lat=51.4778&lon=-0.0015",
    "docs": "https://www.cyclecalcs.com/api/reference.html#sun",
    "spec": "https://www.cyclecalcs.com/v2/openapi.json",
    "page": "https://www.cyclecalcs.com/sunrise-sunset-calculator.html",
    "explain": "https://www.cyclecalcs.com/learn/seasons.html"
  },
  "attribution": "Computed by CycleCalcs (cyclecalcs.com) with the MIT-licensed Astronomy Engine. Positional astronomy only.",
  "docs": "https://www.cyclecalcs.com/api/reference.html#sun"
}

Changes

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