{"title":"Geo-Data API Documentation","version":"v1","generated_at":"2025-09-12T09:30:16.000Z","base_url":"https://cdn.jsdelivr.net/npm/geo-data-api@latest/dist/api/v1","overview":{"description":"Static JSON API for countries, states, and cities data with enhanced geographic and administrative information","features":["250+ countries with detailed information","5099+ states/provinces/regions with administrative details","151165+ cities with geographic coordinates","Multi-language support for countries","Timezone information where provided by the source dataset","Currency details with symbols","Geographic coordinates for precise location","Regional and administrative groupings","WikiData integration for cities","Administrative type classification for states","ISO codes and FIPS codes support"]},"authentication":{"type":"None","description":"This is a public API with no authentication required"},"rate_limits":{"description":"No rate limits - cached by CDN","recommendation":"Implement client-side caching for better performance"},"data_quality":{"coordinates":"100.0% of states and 100.0% of cities have coordinates","wikidata":"99.8% of cities have WikiData references","timezones":"352 unique state timezones available"},"endpoints":{"countries":{"GET /countries.json":{"description":"Get list of all countries with essential information","response_fields":["id","name","iso2","phonecode"],"example":"https://cdn.jsdelivr.net/npm/geo-data-api@latest/dist/api/v1/countries.json"},"GET /countries/{iso2}.json":{"description":"Get detailed information for a specific country including timezones and translations","parameters":{"iso2":"Lowercase country ISO2 code"},"response_fields":"All available fields including timezones, translations, and geographic data","example":"https://cdn.jsdelivr.net/npm/geo-data-api@latest/dist/api/v1/countries/af.json"},"GET /countries/region/{region}.json":{"description":"Get countries by region (e.g., Asia, Europe, Africa)","parameters":{"region":"Region name (lowercase, hyphenated)"},"example":"https://cdn.jsdelivr.net/npm/geo-data-api@latest/dist/api/v1/countries/region/asia.json"},"GET /countries/subregion/{subregion}.json":{"description":"Get countries by subregion","parameters":{"subregion":"Subregion name (lowercase, hyphenated)"},"example":"https://cdn.jsdelivr.net/npm/geo-data-api@latest/dist/api/v1/countries/subregion/southern-asia.json"},"GET /countries/regions.json":{"description":"Get index of all available regions with country counts","example":"https://cdn.jsdelivr.net/npm/geo-data-api@latest/dist/api/v1/countries/regions.json"}},"states":{"GET /states/all.json":{"description":"Get all states (full list, not paginated)","note":"States are provided as a full list (no pagination)","example":"https://cdn.jsdelivr.net/npm/geo-data-api@latest/dist/api/v1/states/all.json"},"GET /states/country/{country_iso2}.json":{"description":"Get states for a specific country with administrative details","parameters":{"country_iso2":"Lowercase country ISO2 code"},"response_fields":["id","name","iso2","iso3166_2"],"example":"https://cdn.jsdelivr.net/npm/geo-data-api@latest/dist/api/v1/states/country/us.json"},"GET /states/type/{type}.json":{"description":"Get states by administrative type (province, state, region, etc.)","parameters":{"type":"Administrative type (lowercase, hyphenated)"},"example":"https://cdn.jsdelivr.net/npm/geo-data-api@latest/dist/api/v1/states/type/province.json"},"GET /states/timezone/{timezone}.json":{"description":"Get states by timezone","parameters":{"timezone":"Timezone name with non-alphanumeric characters replaced by hyphens"},"example":"https://cdn.jsdelivr.net/npm/geo-data-api@latest/dist/api/v1/states/timezone/Asia-Kabul.json"},"GET /states/{iso3166_2}.json":{"description":"Get detailed information for a specific state","parameters":{"iso3166_2":"Lowercase ISO 3166-2 subdivision code"},"example":"https://cdn.jsdelivr.net/npm/geo-data-api@latest/dist/api/v1/states/af-bds.json"},"GET /states/types.json":{"description":"Get index of all state types with counts","example":"https://cdn.jsdelivr.net/npm/geo-data-api@latest/dist/api/v1/states/types.json"},"GET /states/timezones.json":{"description":"Get index of available state timezones","example":"https://cdn.jsdelivr.net/npm/geo-data-api@latest/dist/api/v1/states/timezones.json"}},"cities":{"GET /cities/country/{country_iso2}.json":{"description":"Get cities for a specific country (full list, not paginated)","parameters":{"country_iso2":"Lowercase country ISO2 code"},"note":"Cities are provided as a full list (no pagination)","example":"https://cdn.jsdelivr.net/npm/geo-data-api@latest/dist/api/v1/cities/country/us.json"},"GET /cities/state/{state_iso3166_2}.json":{"description":"Get cities for a specific state","parameters":{"state_iso3166_2":"State ISO 3166-2 code (format: {country_iso2}-{state_code})"},"example":"https://cdn.jsdelivr.net/npm/geo-data-api@latest/dist/api/v1/cities/state/us-ca.json"},"GET /cities/country/{country_iso2}/index.json":{"description":"Index of smaller country city chunks, generated only for countries larger than the configured shard size","note":"Use the index filenames relative to the API base URL. The full country file remains available."},"GET /cities/batches.json":{"description":"Get batch index for efficient single city access","note":"Contains batch filenames and ID ranges for city lookup","response_fields":["filename","start_id","end_id","count"],"example":"https://cdn.jsdelivr.net/npm/geo-data-api@latest/dist/api/v1/cities/batches.json"},"GET /cities/batch/{filename}":{"description":"Get a specific batch of cities (100 cities per batch)","parameters":{"filename":"Batch basename including .json (e.g., batch-57900-58006.json)"},"note":"The batch index filename is already a path relative to the API base URL; cities are keyed by ID in the batch data","example":"https://cdn.jsdelivr.net/npm/geo-data-api@latest/dist/api/v1/cities/batch/batch-57900-58006.json"}},"search":{"GET /search/countries.json":{"description":"Searchable countries index for client-side filtering","searchable_fields":["name","name_normalized","iso2","iso3","native","capital","currency","region","subregion"],"usage":"Download once and filter client-side using any searchable field","example":"https://cdn.jsdelivr.net/npm/geo-data-api@latest/dist/api/v1/search/countries.json"},"GET /search/states.json":{"description":"Searchable states index for client-side filtering","searchable_fields":["name","name_normalized","iso2","country_name","country_code","type","timezone"],"example":"https://cdn.jsdelivr.net/npm/geo-data-api@latest/dist/api/v1/search/states.json"},"GET /search/cities/index.json":{"description":"Manifest of country city-search shards and their relative filenames","note":"meta.global_index_available indicates whether search/cities.json is present; all country shards together cover every city","example":"https://cdn.jsdelivr.net/npm/geo-data-api@latest/dist/api/v1/search/cities/index.json"},"GET /search/cities/country/{iso2}.json":{"description":"Searchable cities for one country; use unknown.json for records without a usable country code","parameters":{"iso2":"Lowercase two-letter country code"},"searchable_fields":["name","name_normalized","state_name","country_name","state_code","country_code","wikiDataId"],"example":"https://cdn.jsdelivr.net/npm/geo-data-api@latest/dist/api/v1/search/cities/country/in.json"},"GET /search/combined.json":{"description":"Combined search index across all entity types (limited dataset)","limitations":"Includes at most the first 1,000 states and 5,000 cities","example":"https://cdn.jsdelivr.net/npm/geo-data-api@latest/dist/api/v1/search/combined.json"},"GET /search/combined-sample.json":{"description":"Combined search sample; the legacy combined.json endpoint is an identical alias","example":"https://cdn.jsdelivr.net/npm/geo-data-api@latest/dist/api/v1/search/combined-sample.json"}}},"response_format":{"structure":{"data":"Array or Object containing the requested data","meta":{"type":"Type of data (countries, states, cities, etc.)","count":"Number of items in data array (for arrays)","generated_at":"Stable ISO release timestamp (configurable using SOURCE_DATE_EPOCH)","api_version":"API version","...additional_meta":"Context-specific metadata"}},"example":{"data":[{"id":3901,"name":"Badakhshan","iso2":"BDS","iso3166_2":"AF-BDS"}],"meta":{"type":"states","count":1,"country_id":1,"country_name":"Afghanistan","generated_at":"2024-01-01T00:00:00.000Z","api_version":"v1"}}},"client_examples":{"javascript":{"basic_fetch":"\n// Get all countries\nconst response = await fetch('https://cdn.jsdelivr.net/npm/geo-data-api@latest/dist/api/v1/countries.json');\nconst data = await response.json();\nconsole.log(data.data); // Array of countries\n        ","get_states_by_country":"\n// Get states for USA (country_iso2: us)\nconst response = await fetch('https://cdn.jsdelivr.net/npm/geo-data-api@latest/dist/api/v1/states/country/us.json');\nconst data = await response.json();\nconsole.log(data.data); // Array of US states\n        ","get_single_city_batch_system":"\n// Get single city using batch system (recommended approach)\nasync function getCityById(cityId) {\n  // Step 1: Get batch index to find correct batch\n  const indexResponse = await fetch('https://cdn.jsdelivr.net/npm/geo-data-api@latest/dist/api/v1/cities/batches.json');\n  const batchIndex = await indexResponse.json();\n\n  // Step 2: Find which batch contains the city\n  const batch = batchIndex.data.find(b =>\n    cityId >= b.start_id && cityId <= b.end_id\n  );\n\n  if (!batch) {\n    throw new Error(`City with ID ${cityId} not found`);\n  }\n\n  // Step 3: Fetch the specific batch\n  const batchResponse = await fetch(`https://cdn.jsdelivr.net/npm/geo-data-api@latest/dist/api/v1/${batch.filename}`);\n  const batchData = await batchResponse.json();\n\n  // Step 4: Extract city data from batch\n  if (!batchData.data[cityId]) throw new Error('City not found: ' + cityId);\n  return batchData.data[cityId];\n}\n\n// Example: Get Bhopal (ID: 57995)\nconst bhopal = await getCityById(57995);\nconsole.log('Bhopal:', bhopal);\n        ","search_example":"\n// Client-side search for provinces\nconst searchData = await fetch('https://cdn.jsdelivr.net/npm/geo-data-api@latest/dist/api/v1/search/states.json');\nconst states = await searchData.json();\nconst provinces = states.data.filter(state =>\n  state.type === 'province' &&\n  state.name.toLowerCase().includes('badakh')\n);\n        "}},"best_practices":{"caching":"Implement client-side caching as data doesn't change frequently","search":"Use search endpoints for client-side filtering instead of downloading all data","coordinates":"Check for latitude/longitude availability before using location features","wikidata":"Use WikiData IDs to fetch additional information from Wikipedia/Wikidata APIs","cities_batch_system":"For single city access, use the batch system (/cities/batches.json + /cities/batch/) instead of individual city files for better performance and reliability"}}