Documentation / API reference

Find the right endpoint.

A guide to the files available in API v1, from country lists to city search shards.

API v1Static JSON

Base URL
https://cdn.jsdelivr.net/npm/geo-data-api@latest/dist/api/v1/Paths below are relative to this URL. Use lowercase codes in filenames.

Endpoint reference

Countries

Start with the list, then request a country or browse by region.

GETcountries.json

All countries with essential fields. Open example ↗

GETcountries/{iso2}.json

Full details for a country. Open example ↗

GETcountries/regions.json

Index of regions and their endpoints. Open example ↗

GETcountries/region/{region}.json

Countries in a region, such as asia. Open example ↗

GETcountries/subregion/{subregion}.json

Countries in a subregion.

Endpoint reference

States & provinces

Use country ISO2 codes and ISO 3166-2 state codes in lowercase.

GETstates/all.json

Complete list of states. Open example ↗

GETstates/country/{iso2}.json

States in one country. Open example ↗

GETstates/{iso3166_2}.json

Full details for one state. Open example ↗

GETstates/types.json

Index of available administrative types. Open example ↗

GETstates/type/{type}.json

States for an administrative type. Open example ↗

GETstates/timezones.json

Index of state timezone endpoints. Open example ↗

GETstates/timezone/{timezone}.json

States in a timezone. Use the index to discover filenames.

Endpoint reference

Cities

Use a state list for a picker, or the batch index to look up an individual city.

GETcities/country/{iso2}.json

Complete city list for a country. Open example ↗

GETcities/country/{iso2}/index.json

Chunk index for large countries; omitted for smaller countries.

GETcities/country/{iso2}/{chunk}.json

A chunk listed by the country index.

GETcities/state/{iso3166_2}.json

Cities for one state. Open example ↗

GETcities/batches.json

City ID ranges and API-relative batch filenames. Open example ↗

GETcities/batch/{batch-filename}

Detailed city records keyed by ID. The batch index provides the full path relative to the API base.

GETcities/timezones.json

City timezone index, present only when the dataset supplies city timezones.

GETcities/timezone/{timezone}.json

City timezone files, when available. Use the index to discover filenames.

Endpoint reference

Search indexes

These are static files: fetch an index and filter its records in your application.

GETsearch/countries.json

Searchable country records. Open example ↗

GETsearch/states.json

Searchable state records. Open example ↗

GETsearch/cities/index.json

Available country city-search shards. The index metadata reports whether the global file is available. Open example ↗

GETsearch/cities/country/{iso2}.json

City search records for one country. Open example ↗

GETsearch/cities.json

Complete global city index for ordinary builds. Cloudflare Pages omits this large file; use all country shards for complete global search.

GETsearch/combined-sample.json

A sample, limited to 1,000 states and 5,000 cities. Open example ↗

GETsearch/combined.json

Compatibility alias for the combined sample.

A country without cities may not have a search shard. Names in search indexes include name_normalized for case-insensitive, diacritic-folded matching.

Endpoint reference

Dataset & discovery

Inspect the generated dataset and learn more about the available files.

GETapi-info.json

Dataset statistics and endpoint index. Open example ↗

GETdocumentation.json

Machine-readable endpoint descriptions. Open example ↗

GETmanifest.json

Dataset version, file inventory, and checksums. Open example ↗

GETbuild-report.json

Source validation and build report. Open example ↗