{"id":31078213,"url":"https://github.com/asterodigital/geo-data-api","last_synced_at":"2025-10-24T16:02:56.966Z","repository":{"id":314420887,"uuid":"1055397634","full_name":"asterodigital/geo-data-api","owner":"asterodigital","description":"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.","archived":false,"fork":false,"pushed_at":"2025-09-12T11:28:35.000Z","size":4529,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-12T11:39:27.840Z","etag":null,"topics":["api","cities","countries","countries-states-cities","country","country-state-city","generator","geographical-data","hacktoberfest","json","region","regions","state","states","world-regions"],"latest_commit_sha":null,"homepage":"https://geo-data-api.asterodigital.com","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/asterodigital.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-12T07:55:54.000Z","updated_at":"2025-09-12T11:28:39.000Z","dependencies_parsed_at":"2025-09-12T11:39:32.033Z","dependency_job_id":"5551f372-5abe-42ba-8b9e-e2b3fb85265d","html_url":"https://github.com/asterodigital/geo-data-api","commit_stats":null,"previous_names":["asterodigital/geo-data"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/asterodigital/geo-data-api","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/asterodigital%2Fgeo-data-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/asterodigital%2Fgeo-data-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/asterodigital%2Fgeo-data-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/asterodigital%2Fgeo-data-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/asterodigital","download_url":"https://codeload.github.com/asterodigital/geo-data-api/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/asterodigital%2Fgeo-data-api/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":275388481,"owners_count":25455846,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-16T02:00:10.229Z","response_time":65,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","cities","countries","countries-states-cities","country","country-state-city","generator","geographical-data","hacktoberfest","json","region","regions","state","states","world-regions"],"created_at":"2025-09-16T08:35:49.681Z","updated_at":"2025-09-16T08:35:52.813Z","avatar_url":"https://github.com/asterodigital.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Geo-Data API Static Generator\n\n[![npm version](https://badge.fury.io/js/geo-data-api.svg)](https://www.npmjs.com/package/geo-data-api)\n[![jsDelivr hits (npm)](https://img.shields.io/jsdelivr/npm/hm/geo-data-api)](https://www.jsdelivr.com/package/npm/geo-data-api)\n\nGenerate a static JSON API for geographic data including countries, states and cities that can be hosted on any CDN.\n\nThis repository transforms the upstream dataset (countries, states, cities) into a small, cacheable, CDN-ready API under `dist/api/v1/`.\n\n## Quick start\n\nPrerequisites: Node.js and npm.\n\n1. Place source JSON files in the `db/` directory:\n   - `countries.json`\n   - `states.json`\n   - `cities.json`\n\nYou can download the dataset from the GitHub project: [dr5hn/countries-states-cities-database](https://github.com/dr5hn/countries-states-cities-database)\n\n1. Install dependencies and build the API:\n\n```powershell\nnpm install\nnpm run build\n```\n\n1. Upload the contents of `dist/api/v1/` to your CDN.\n\n1. Update `src/config.js` (for example, `CDN_BASE_URL`) if you need client-side configuration.\n\n## What this generates\n\nThe generator creates a small static API tree (example):\n\n```text\ndist/api/v1/\n├── countries.json                # list all countries\n├── countries/{iso2}.json         # country details (ISO2 code)\n├── states/country/{iso2}.json    # states by country (ISO2 code)\n├── states/{iso3166_2}.json       # state details (ISO 3166-2 code)\n├── cities/country/{iso2}.json    # cities by country (ISO2 code)\n├── cities/state/{iso3166_2}.json # cities by state (ISO 3166-2 code)\n├── cities/{id}.json              # (limited) city details\n└── search/\n    ├── countries.json            # searchable country index\n    ├── states.json               # searchable state index\n    └── cities.json               # searchable city index\n```\n\n## API endpoints (static files)\n\n### Countries\n\n- GET /countries.json\n- GET /countries/{iso2}.json\n- GET /countries/region/{region}.json\n- GET /countries/subregion/{subregion}.json\n\n### States\n\n- GET /states/country/{iso2}.json\n- GET /states/{iso3166_2}.json\n- GET /states/type/{type}.json\n- GET /states/timezone/{timezone}.json\n- GET /states/types.json\n- GET /states/timezones.json\n- GET /states/all.json\n\n### Cities\n\n- GET /cities/country/{iso2}.json\n- GET /cities/state/{iso3166_2}.json\n- GET /cities/timezone/{timezone}.json\n- GET /cities/{id}.json\n- GET /cities/batch/{batchId}.json\n- GET /cities/batches.json\n\n### Search\n\n- GET /search/countries.json\n- GET /search/states.json\n- GET /search/cities.json\n- GET /search/combined.json\n\n## Configuration\n\nEdit `src/config.js` to customize:\n\n- Output formatting (pretty vs compact)\n- Search fields included in index files\n- `CDN_BASE_URL` used by examples\n- Optional: country flag icons via [flag-icons (Lipis)](https://flagicons.lipis.dev/) (configurable in `src/config.js`)\n\n## Documentation\n\n📚 **Complete API Documentation**\n\n- **[API Documentation](docs/API_DOCUMENTATION.md)** - Comprehensive overview with examples and best practices\n- **[Quick Start Guide](docs/QUICK_START.md)** - Get up and running quickly with code examples\n- **[Endpoints Reference](docs/ENDPOINTS.md)** - Detailed reference for all available API endpoints\n- **[Data Structure Reference](docs/DATA_STRUCTURE.md)** - Complete field definitions and sample objects\n\n## Advanced Features\n\n### Performance Optimizations\n\n- **Sequential Processing**: Optimized for large datasets with controlled memory usage\n- **Batch Processing**: Cities are split into manageable batches for efficient API access\n- **Compact JSON**: Production-optimized minified output (use `--pretty` for development)\n- **Memory Management**: Automatic cache clearing and memory optimization during generation\n\n### Smart Search \u0026 Filtering\n\n- **Multi-entity Search**: Combined search index across countries, states, and cities\n- **Advanced Filtering**: Filter by region, subregion, administrative type, and timezone\n- **Client-side Search**: Pre-built search indexes for fast client-side filtering\n- **Batch City Access**: Efficient city lookup with 100 cities per batch file\n\n### Geographic Intelligence\n\n- **100% Coordinate Coverage**: All states and cities include latitude/longitude\n- **Timezone Support**: Complete timezone data for states and cities\n- **Administrative Types**: 93 different state/province types supported\n- **WikiData Integration**: 99.8% of cities linked to Wikipedia references\n\n## Roadmap\n\n### 🚀 Phase 1: Enhanced User Experience\n\n- [ ] **Astro-powered Landing Page**: Replace current HTML with Astro for better performance and maintainability\n- [ ] **Interactive Demo Redesign**: Rebuild demo pages using Astro with improved UX and modern design\n- [ ] **Single City Endpoints**: Add option to generate individual city API endpoints for better granularity\n\n### 🔧 Phase 2: Developer Experience\n\n- [ ] **OpenAPI Specification**: Generate comprehensive OpenAPI/Swagger docs for better API discovery\n- [ ] **SDK Generation**: Create SDKs for JavaScript, Python, and PHP\n- [ ] **TypeScript Support**: Add TypeScript definitions for better developer experience\n- [ ] **CLI Tool Enhancement**: Improve command-line interface with more options and better error handling\n\n### 📊 Phase 3: Advanced Features\n\n- [ ] **GraphQL API**: Add GraphQL support alongside REST API for flexible querying\n- [ ] **Real-time Updates**: Implement webhook system for data updates and notifications\n- [ ] **Advanced Search**: Add fuzzy search, autocomplete, and advanced filtering capabilities\n- [ ] **Data Export**: Support for CSV, XML, and other data formats\n\n## Deployment\n\n1. Run the build (see Quick start).\n1. Upload `dist/api/` to your CDN or static host.\n1. Configure CORS on the CDN to allow public reads. Example headers:\n\n```text\nAccess-Control-Allow-Origin: *\nAccess-Control-Allow-Methods: GET, OPTIONS\nAccess-Control-Allow-Headers: Content-Type\n```\n\nPerformance tips:\n\n- Enable gzip/brotli compression on your CDN.\n- Use long cache TTLs for static files and versioning on rebuilds.\n- Use the `/search` endpoints for client-side filtering instead of downloading full datasets.\n\n## Usage examples\n\nFetch all countries:\n\n```javascript\nconst resp = await fetch(\n  \"https://cdn.jsdelivr.net/npm/geo-data-api@latest/dist/api/v1/countries.json\"\n);\nconst data = await resp.json();\nconsole.log(data);\n```\n\nGet states for a country (example: Afghanistan):\n\n```javascript\nconst resp = await fetch(\n  \"https://cdn.jsdelivr.net/npm/geo-data-api@latest/dist/api/v1/states/country/af.json\"\n);\nconst states = await resp.json();\n```\n\nGet cities for a state (example: Badakhshan province):\n\n```javascript\nconst resp = await fetch(\n  \"https://cdn.jsdelivr.net/npm/geo-data-api@latest/dist/api/v1/cities/state/af-bds.json\"\n);\nconst cities = await resp.json();\n```\n\nSearch client-side (example):\n\n```javascript\nconst resp = await fetch(\n  \"https://cdn.jsdelivr.net/npm/geo-data-api@latest/dist/api/v1/search/countries.json\"\n);\nconst index = await resp.json();\nconst matches = index.data.filter((c) =\u003e c.name.toLowerCase().includes(\"ind\"));\n```\n\nReact hook example (tiny helper):\n\n```javascript\nimport { useState, useEffect } from \"react\";\n\nconst API_BASE_URL =\n  \"https://cdn.jsdelivr.net/npm/geo-data-api@latest/dist/api/v1\";\n\nexport function useCountriesAPI() {\n  const [countries, setCountries] = useState([]);\n  const [loading, setLoading] = useState(false);\n\n  async function getCountries() {\n    setLoading(true);\n    const r = await fetch(`${API_BASE_URL}/countries.json`);\n    const j = await r.json();\n    setCountries(j.data || []);\n    setLoading(false);\n  }\n\n  useEffect(() =\u003e {\n    getCountries();\n  }, []);\n\n  async function getStates(countryId) {\n    // Use ISO2 code (e.g., 'af' for Afghanistan) or numeric ID\n    const r = await fetch(`${API_BASE_URL}/states/country/${countryId}.json`);\n    return r.json();\n  }\n\n  async function getCities(stateId) {\n    // Use ISO 3166-2 code (e.g., 'af-bds' for Badakhshan) or numeric ID\n    const r = await fetch(`${API_BASE_URL}/cities/state/${stateId}.json`);\n    return r.json();\n  }\n\n  return { countries, loading, getStates, getCities };\n}\n```\n\n## File structure (project)\n\n- `src/` - generator source code\n  - `config.js` - configuration and field mappings\n  - `data-processor.js` - main processing logic and orchestration\n  - `server.js` - development server for testing\n  - `generators/` - per-entity generators\n    - `countries.js` - country endpoint generation\n    - `states.js` - state endpoint generation\n    - `cities.js` - city endpoint generation\n    - `search.js` - search index generation\n    - `base-generator.js` - shared generator utilities\n  - `analyzers/` - data analysis and validation\n  - `validators/` - data structure validation\n  - `utils/` - utility helpers and performance monitoring\n  - `docs/` - documentation generation templates\n- `db/` - source JSON data files (not committed)\n  - `countries.json` - country data\n  - `states.json` - state/province data\n  - `cities.json` - city data\n- `dist/` - generated API tree (gitignored)\n  - `api/v1/` - static JSON API files\n  - `demo/` - interactive demo files\n- `docs/` - generated documentation\n- `demo/` - demo HTML files\n\n## Notes\n\n- The repository is intended to produce a fully static API; no runtime server is required.\n- Keep `db/*.json` out of source control; the repo's `.gitignore` already excludes them.\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fasterodigital%2Fgeo-data-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fasterodigital%2Fgeo-data-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fasterodigital%2Fgeo-data-api/lists"}