API Reference

World Geo: Countries, Cities & Time Zones (GeoNames)

World geography reference category: 252 countries with ISO2/ISO3 codes, capital, currency, languages, calling code and population; 69,991 cities (cities5000: population above 5,000 or an administrative seat) with coordinates, first-level division, population and time zone; nearest-city search from a coordinate; and 418 IANA time zones with GMT/DST offsets and the current local time. The data is the official GeoNames dump, licensed CC BY 4.0, so it may be used commercially as long as the attribution is kept.

Data as of · Source: GeoNames dump

Main endpoint
GET https://use.apiindonesia.id/api/v1/geo/negara
Endpoints
7
Authentication
x-api-key header (create one free in the dashboard)
Price
2 credits (Rp2) per successful request; failed requests are free
Format
JSON (REST), with cURL, JavaScript and Python examples
Data source
Data source: GeoNames (https://www.geonames.org), the daily dump at https://download.geonames.org/export/dump/ (countryInfo.txt, cities5000.zip, admin1CodesASCII.txt, timeZones.txt), licensed under Creative Commons Attribution 4.0 International (CC BY 4.0) per the dump readme.txt. Every successful response carries meta.attribution with the GeoNames credit and link, the licence name and link, a link to the source files and the statement of changes, so you only need to pass that object through in any redistribution. What API Indonesia changed: the dump files were normalised to JSON, first-level division names were joined onto the cities, the alternatenames column and the alternateNamesV2 file are not included, and the local time on the time zone endpoint is computed by API Indonesia. The GeoNames web services and the Zillow data are not used.
Product Brief

What this API gives you

World geography reference category: 252 countries with ISO2/ISO3 codes, capital, currency, languages, calling code and population; 69,991 cities (cities5000: population above 5,000 or an administrative seat) with coordinates, first-level division, population and time zone; nearest-city search from a coordinate; and 418 IANA time zones with GMT/DST offsets and the current local time. The data is the official GeoNames dump, licensed CC BY 4.0, so it may be used commercially as long as the attribution is kept.

Data source: GeoNames (https://www.geonames.org), the daily dump at https://download.geonames.org/export/dump/ (countryInfo.txt, cities5000.zip, admin1CodesASCII.txt, timeZones.txt), licensed under Creative Commons Attribution 4.0 International (CC BY 4.0) per the dump readme.txt. Every successful response carries meta.attribution with the GeoNames credit and link, the licence name and link, a link to the source files and the statement of changes, so you only need to pass that object through in any redistribution. What API Indonesia changed: the dump files were normalised to JSON, first-level division names were joined onto the cities, the alternatenames column and the alternateNamesV2 file are not included, and the local time on the time zone endpoint is computed by API Indonesia. The GeoNames web services and the Zillow data are not used.

Coverage
7

ready-to-use endpoints in this product, with JSON responses and consistent error handling.

Access
API key

Can be tried with the 3,000 credit signup bonus, then used in production through one API Indonesia key.

Sample resource
https://use.apiindonesia.id/api/v1/geo/negara

Returns the 252 countries and territories in GeoNames countryInfo, ordered by name: ISO2, ISO3, numeric code, capital, continent, area, population, currency, calling code (without +), languages, TLD, postal code format and neighbours.

Example product scenarios

This section separates the product page from the docs. The docs explain how to call endpoints; this page explains why the endpoints make sense for your feature.

  • International forms & checkout: country dropdowns with calling code and currency, then cities per country.
  • Scheduling & global HR apps: show the local time and time zone offset of colleagues or customers abroad.
  • Logistics & travel: find the nearest city to a coordinate for coarse reverse geocoding or location grouping.

Example Usage

Request
curl "https://use.apiindonesia.id/api/v1/geo/negara?q=indo" \
  -H "x-api-key: YOUR_API_KEY"
Response · 200 OK
{
  "success": true,
  "data": [
    { "iso2": "ID", "iso3": "IDN", "iso_numeric": "360", "fips": "ID", "name": "Indonesia", "capital": "Jakarta", "continent": "AS", "area_km2": 1919440, "population": 285721236, "currency": { "code": "IDR", "name": "Rupiah" }, "phone_code": "62", "languages": ["id", "en", "nl", "jv"], "tld": ".id", "postal_code_format": "#####", "postal_code_regex": "^(\\d{5})$", "neighbours": ["PG", "TL", "MY"], "geonameid": 1643084 }
  ],
  "meta": {
    "total": 1, "page": 1, "per_page": 50, "total_pages": 1,
    "attribution": {
      "source": "GeoNames (https://www.geonames.org)",
      "license": "CC BY 4.0",
      "license_url": "https://creativecommons.org/licenses/by/4.0/",
      "source_url": "https://download.geonames.org/export/dump/",
      "attribution_page": "https://www.geonames.org",
      "notice": "Data diubah: subset cities5000, countryInfo, admin1 dan timeZones dinormalisasi ke format JSON API Indonesia; waktu lokal dihitung oleh API Indonesia"
    }
  }
}

Related Articles

Pricing 2 credits (Rp2) per successful request; failed requests are free. One-time 3,000 credit signup bonus, no credit card, no monthly allowance.

World Geo: Countries, Cities & Time Zones (GeoNames) API questions

Where do the country, city and time zone data come from?

From the official GeoNames dump (download.geonames.org/export/dump), licensed CC BY 4.0. The GeoNames web services are not used.

Which cities are covered?

The cities5000 file: populated places above 5,000 people or administrative seats, 69,991 cities in total including 485 in Indonesia.

Is the local time on the time zone endpoint always current?

Yes, the local time and current offset are computed on every request and are not cached. The GeoNames file offsets are included for reference.

Get Started

Start Integrating
Today

Sign up for free and get a 3,000 credit bonus (Rp3,000) once your email is verified, grab an API key, and call your first endpoint right away. No credit card, no tedious approval process.

Dot wave visualization