Geography, made simple.

Geo-Data API turns a geographic dataset into simple JSON files. Fetch only the data your experience needs, then filter or cache it in your own application.

The examples on this page use the API base URL for this deployment. Copy the example into your browser console or application to fetch the country list.

const API_BASE = "https://cdn.jsdelivr.net/npm/geo-data-api@latest/dist/api/v1/";

async function listCountries() {
  const response = await fetch(API_BASE + "countries.json");
  if (!response.ok) throw new Error("Request failed: " + response.status);
  const result = await response.json();
  return result.data;
}

listCountries().then(console.log).catch(console.error);

For another deployment, replace the base URL with that host’s API URL. You can also open the country list directly.

Most endpoints return a data value and a meta object. Lists contain arrays; individual country and state endpoints contain an object. City batches use an object keyed by city ID.

{
  "data": [
    { "id": 1, "name": "Afghanistan", "iso2": "AF", "phonecode": "93" }
  ],
  "meta": { "type": "countries", "count": 1, "api_version": "v1" }
}

This is an abbreviated illustration; actual records and metadata depend on the generated dataset. Check response.ok before reading JSON, because missing files return a non-success status.