Repository files navigation

Generate a static JSON API for geographic data including countries, states and cities that can be hosted on any CDN.

This repository transforms the upstream dataset (countries, states, cities) into a small, cacheable, CDN-ready API underdist/api/v1/.

Prerequisites: Node.js and npm.

1. Place source JSON files in thedb/ directory:
   • countries.json
   • states.json
   • cities.json

You can download the dataset from the GitHub project:dr5hn/countries-states-cities-database

1. Install dependencies and build the API:

npm installnpm run build

1. Upload the contents ofdist/api/v1/ to your CDN.

2. Updatesrc/config.js (for example,CDN_BASE_URL) if you need client-side configuration.

The generator creates a small static API tree (example):

dist/api/v1/├── countries.json                # list all countries├── countries/{iso2}.json         # country details (ISO2 code)├── states/country/{iso2}.json    # states by country (ISO2 code)├── states/{iso3166_2}.json       # state details (ISO 3166-2 code)├── cities/country/{iso2}.json    # cities by country (ISO2 code)├── cities/state/{iso3166_2}.json # cities by state (ISO 3166-2 code)├── cities/{id}.json              # (limited) city details└── search/    ├── countries.json            # searchable country index    ├── states.json               # searchable state index    └── cities.json               # searchable city index

• GET /countries.json
• GET /countries/{iso2}.json
• GET /countries/region/{region}.json
• GET /countries/subregion/{subregion}.json

• GET /states/country/{iso2}.json
• GET /states/{iso3166_2}.json
• GET /states/type/{type}.json
• GET /states/timezone/{timezone}.json
• GET /states/types.json
• GET /states/timezones.json
• GET /states/all.json

• GET /cities/country/{iso2}.json
• GET /cities/state/{iso3166_2}.json
• GET /cities/timezone/{timezone}.json
• GET /cities/{id}.json
• GET /cities/batch/{batchId}.json
• GET /cities/batches.json

• GET /search/countries.json
• GET /search/states.json
• GET /search/cities.json
• GET /search/combined.json

Editsrc/config.js to customize:

• Output formatting (pretty vs compact)
• Search fields included in index files
• CDN_BASE_URL used by examples
• Optional: country flag icons viaflag-icons (Lipis) (configurable insrc/config.js)

📚Complete API Documentation

• API Documentation - Comprehensive overview with examples and best practices
• Quick Start Guide - Get up and running quickly with code examples
• Endpoints Reference - Detailed reference for all available API endpoints
• Data Structure Reference - Complete field definitions and sample objects

• Sequential Processing: Optimized for large datasets with controlled memory usage
• Batch Processing: Cities are split into manageable batches for efficient API access
• Compact JSON: Production-optimized minified output (use--pretty for development)
• Memory Management: Automatic cache clearing and memory optimization during generation

• Multi-entity Search: Combined search index across countries, states, and cities
• Advanced Filtering: Filter by region, subregion, administrative type, and timezone
• Client-side Search: Pre-built search indexes for fast client-side filtering
• Batch City Access: Efficient city lookup with 100 cities per batch file

• 100% Coordinate Coverage: All states and cities include latitude/longitude
• Timezone Support: Complete timezone data for states and cities
• Administrative Types: 93 different state/province types supported
• WikiData Integration: 99.8% of cities linked to Wikipedia references

• Astro-powered Landing Page: Replace current HTML with Astro for better performance and maintainability
• Interactive Demo Redesign: Rebuild demo pages using Astro with improved UX and modern design
• Single City Endpoints: Add option to generate individual city API endpoints for better granularity

• OpenAPI Specification: Generate comprehensive OpenAPI/Swagger docs for better API discovery
• SDK Generation: Create SDKs for JavaScript, Python, and PHP
• TypeScript Support: Add TypeScript definitions for better developer experience
• CLI Tool Enhancement: Improve command-line interface with more options and better error handling

• GraphQL API: Add GraphQL support alongside REST API for flexible querying
• Real-time Updates: Implement webhook system for data updates and notifications
• Advanced Search: Add fuzzy search, autocomplete, and advanced filtering capabilities
• Data Export: Support for CSV, XML, and other data formats

1. Run the build (see Quick start).
2. Uploaddist/api/ to your CDN or static host.
3. Configure CORS on the CDN to allow public reads. Example headers:

Access-Control-Allow-Origin: *Access-Control-Allow-Methods: GET, OPTIONSAccess-Control-Allow-Headers: Content-Type

Performance tips:

• Enable gzip/brotli compression on your CDN.
• Use long cache TTLs for static files and versioning on rebuilds.
• Use the/search endpoints for client-side filtering instead of downloading full datasets.

Fetch all countries:

constresp=awaitfetch("https://cdn.jsdelivr.net/npm/geo-data-api@latest/dist/api/v1/countries.json");constdata=awaitresp.json();console.log(data);

Get states for a country (example: Afghanistan):

constresp=awaitfetch("https://cdn.jsdelivr.net/npm/geo-data-api@latest/dist/api/v1/states/country/af.json");conststates=awaitresp.json();

Get cities for a state (example: Badakhshan province):

constresp=awaitfetch("https://cdn.jsdelivr.net/npm/geo-data-api@latest/dist/api/v1/cities/state/af-bds.json");constcities=awaitresp.json();

Search client-side (example):

constresp=awaitfetch("https://cdn.jsdelivr.net/npm/geo-data-api@latest/dist/api/v1/search/countries.json");constindex=awaitresp.json();constmatches=index.data.filter((c)=>c.name.toLowerCase().includes("ind"));

React hook example (tiny helper):

import{useState,useEffect}from"react";constAPI_BASE_URL="https://cdn.jsdelivr.net/npm/geo-data-api@latest/dist/api/v1";exportfunctionuseCountriesAPI(){const[countries,setCountries]=useState([]);const[loading,setLoading]=useState(false);asyncfunctiongetCountries(){setLoading(true);constr=awaitfetch(`${API_BASE_URL}/countries.json`);constj=awaitr.json();setCountries(j.data||[]);setLoading(false);}useEffect(()=>{getCountries();},[]);asyncfunctiongetStates(countryId){// Use ISO2 code (e.g., 'af' for Afghanistan) or numeric IDconstr=awaitfetch(`${API_BASE_URL}/states/country/${countryId}.json`);returnr.json();}asyncfunctiongetCities(stateId){// Use ISO 3166-2 code (e.g., 'af-bds' for Badakhshan) or numeric IDconstr=awaitfetch(`${API_BASE_URL}/cities/state/${stateId}.json`);returnr.json();}return{ countries, loading, getStates, getCities};}

• src/ - generator source code
  • config.js - configuration and field mappings
  • data-processor.js - main processing logic and orchestration
  • server.js - development server for testing
  • generators/ - per-entity generators
    • countries.js - country endpoint generation
    • states.js - state endpoint generation
    • cities.js - city endpoint generation
    • search.js - search index generation
    • base-generator.js - shared generator utilities
  • analyzers/ - data analysis and validation
  • validators/ - data structure validation
  • utils/ - utility helpers and performance monitoring
  • docs/ - documentation generation templates
• db/ - source JSON data files (not committed)
  • countries.json - country data
  • states.json - state/province data
  • cities.json - city data
• dist/ - generated API tree (gitignored)
  • api/v1/ - static JSON API files
  • demo/ - interactive demo files
• docs/ - generated documentation
• demo/ - demo HTML files

• The repository is intended to produce a fully static API; no runtime server is required.
• Keepdb/*.json out of source control; the repo's.gitignore already excludes them.

This project is licensed under the MIT License - see theLICENSE file for details.