Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/asterodigital/geo-data-api

Generate a static JSON API for geographic data including countries, states, and cities that can be hosted on any CDN. Transform geographic datasets into a small, cacheable, CDN-ready API with search capabilities.
https://github.com/asterodigital/geo-data-api

api cities countries countries-states-cities country country-state-city generator geographical-data hacktoberfest json region regions state states world-regions

Last synced: 25 days ago
JSON representation

Generate a static JSON API for geographic data including countries, states, and cities that can be hosted on any CDN. Transform geographic datasets into a small, cacheable, CDN-ready API with search capabilities.

Awesome Lists containing this project

README 

          
# Geo-Data API Static Generator



[![npm version](https://badge.fury.io/js/geo-data-api.svg)](https://www.npmjs.com/package/geo-data-api)

[![jsDelivr hits (npm)](https://img.shields.io/jsdelivr/npm/hm/geo-data-api)](https://www.jsdelivr.com/package/npm/geo-data-api)



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 under `dist/api/v1/`.



## Quick start



Prerequisites: Node.js and npm.



1. Place source JSON files in the `db/` directory:

   - `countries.json`

   - `states.json`

   - `cities.json`



You can download the dataset from the GitHub project: [dr5hn/countries-states-cities-database](https://github.com/dr5hn/countries-states-cities-database)



1. Install dependencies and build the API:



```powershell

npm install

npm run build

```



1. Upload the contents of `dist/api/v1/` to your CDN.



1. Update `src/config.js` (for example, `CDN_BASE_URL`) if you need client-side configuration.



## What this generates



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



```text

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

```



## API endpoints (static files)



### Countries



- GET /countries.json

- GET /countries/{iso2}.json

- GET /countries/region/{region}.json

- GET /countries/subregion/{subregion}.json



### States



- 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



### Cities



- 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



### Search



- GET /search/countries.json

- GET /search/states.json

- GET /search/cities.json

- GET /search/combined.json



## Configuration



Edit `src/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 via [flag-icons (Lipis)](https://flagicons.lipis.dev/) (configurable in `src/config.js`)



## Documentation



📚 **Complete API Documentation**



- **[API Documentation](docs/API_DOCUMENTATION.md)** - Comprehensive overview with examples and best practices

- **[Quick Start Guide](docs/QUICK_START.md)** - Get up and running quickly with code examples

- **[Endpoints Reference](docs/ENDPOINTS.md)** - Detailed reference for all available API endpoints

- **[Data Structure Reference](docs/DATA_STRUCTURE.md)** - Complete field definitions and sample objects



## Advanced Features



### Performance Optimizations



- **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



### Smart Search & Filtering



- **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



### Geographic Intelligence



- **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



## Roadmap



### 🚀 Phase 1: Enhanced User Experience



- [ ] **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



### 🔧 Phase 2: Developer Experience



- [ ] **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



### 📊 Phase 3: Advanced Features



- [ ] **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



## Deployment



1. Run the build (see Quick start).

1. Upload `dist/api/` to your CDN or static host.

1. Configure CORS on the CDN to allow public reads. Example headers:



```text

Access-Control-Allow-Origin: *

Access-Control-Allow-Methods: GET, OPTIONS

Access-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.



## Usage examples



Fetch all countries:



```javascript

const resp = await fetch(

  "https://cdn.jsdelivr.net/npm/geo-data-api@latest/dist/api/v1/countries.json"

);

const data = await resp.json();

console.log(data);

```



Get states for a country (example: Afghanistan):



```javascript

const resp = await fetch(

  "https://cdn.jsdelivr.net/npm/geo-data-api@latest/dist/api/v1/states/country/af.json"

);

const states = await resp.json();

```



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



```javascript

const resp = await fetch(

  "https://cdn.jsdelivr.net/npm/geo-data-api@latest/dist/api/v1/cities/state/af-bds.json"

);

const cities = await resp.json();

```



Search client-side (example):



```javascript

const resp = await fetch(

  "https://cdn.jsdelivr.net/npm/geo-data-api@latest/dist/api/v1/search/countries.json"

);

const index = await resp.json();

const matches = index.data.filter((c) => c.name.toLowerCase().includes("ind"));

```



React hook example (tiny helper):



```javascript

import { useState, useEffect } from "react";



const API_BASE_URL =

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



export function useCountriesAPI() {

  const [countries, setCountries] = useState([]);

  const [loading, setLoading] = useState(false);



  async function getCountries() {

    setLoading(true);

    const r = await fetch(`${API_BASE_URL}/countries.json`);

    const j = await r.json();

    setCountries(j.data || []);

    setLoading(false);

  }



  useEffect(() => {

    getCountries();

  }, []);



  async function getStates(countryId) {

    // Use ISO2 code (e.g., 'af' for Afghanistan) or numeric ID

    const r = await fetch(`${API_BASE_URL}/states/country/${countryId}.json`);

    return r.json();

  }



  async function getCities(stateId) {

    // Use ISO 3166-2 code (e.g., 'af-bds' for Badakhshan) or numeric ID

    const r = await fetch(`${API_BASE_URL}/cities/state/${stateId}.json`);

    return r.json();

  }



  return { countries, loading, getStates, getCities };

}

```



## File structure (project)



- `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



## Notes



- The repository is intended to produce a fully static API; no runtime server is required.

- Keep `db/*.json` out of source control; the repo's `.gitignore` already excludes them.



## License



This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.