API documentation

Your first request

Use the origin of this website followed by /api/GeoData. Responses are JSON. Contact us for API access, then supply your key with each request:

curl "https://YOUR-HOST/api/GeoData/country/SI" \
  -H "Authorization: Bearer YOUR_API_KEY"

YOUR-HOST is the host where this service is deployed. Keys are private credentials; keep them on your server, outside public client code. This header carries an API key, not a JWT.

Open interactive Swagger ↗

Countries

GET /countries

All imported countries and territories, including ISO codes, capital, currency and population.

GET /countries/dropdown

Compact id and name options for country selectors.

GET /country/{code}

One country by its two-letter ISO code, such as SI, GB or DE. Example response excerpt:

{ "isoAlpha2": "SI", "name": "Slovenia", "capital": "Ljubljana" }

Cities & places

GET /cities/{countryCode}

Every imported populated place in the country (GeoNames feature class P). Includes villages and smaller settlements, with no population cutoff. Large countries can return large arrays.

GET /cities/{countryCode}/dropdown

Names and GeoNames identifiers for populated-place selectors.

GET /city/{id}

A detailed record by GeoNames ID. Try /city/3196359 for Ljubljana.

GET /latlong/{name}

Coordinates for geographic features with an exact primary-name match, such as Ljubljana. Names are not unique: expect an array of matches. Latitude and longitude use WGS84 decimal degrees.

Postal codes

GET /postal-codes/{countryCode}

All postal-place records available in the GeoNames postal export for the country. Coverage varies. Shared postal codes retain separate place records.

GET /postal-codes/{countryCode}/{cityName}

Filter by place, for example /postal-codes/SI/Ljubljana. URL-encode names containing spaces or non-ASCII characters.

Alternate names

GET /alternative-names/{geoNameId}

Language-specific names and flags for preferred, short, historic and colloquial names. Example: /alternative-names/3196359. The full source import includes every language.

Time zones

GET /timezones

Available IANA time-zone identifiers for a selector.

GET /timezone/{id}

Use the full identifier, including its slash: /timezone/Europe/Ljubljana. The reported January, July and raw offsets come from the GeoNames snapshot. Use an up-to-date IANA time-zone library for conversion at a particular instant.

Errors & usage limits

Status	Meaning
200	Successful query. An empty collection is returned as `[]`.
400	Invalid request values.
401	Missing or malformed Authorization header.
403	API key is unknown, inactive or has no configured allowance.
404	An individual record was not found.
429	Your configured hourly quota has been exhausted. Retry in the next UTC hour.
500	Unexpected server error.

Quotas are assigned to API-key roles by the operator. The Swagger explorer uses the same limits as other clients. Geographic reads require a key; these documentation pages do not.

Data updates

The API serves a verified geographic snapshot. Coverage varies by location and dataset.

Download the OpenAPI specification ↗