{"id":38080332,"url":"https://github.com/odch/aerodromes","last_synced_at":"2026-01-16T20:48:01.906Z","repository":{"id":316375675,"uuid":"1063103077","full_name":"odch/aerodromes","owner":"odch","description":"Aerodromes registry","archived":false,"fork":false,"pushed_at":"2026-01-12T07:25:51.000Z","size":3939,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-12T16:32:34.773Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/odch.png","metadata":{"files":{"readme":"README.md","changelog":"changes_summary.txt","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-24T07:05:26.000Z","updated_at":"2026-01-12T07:25:55.000Z","dependencies_parsed_at":"2025-09-24T09:15:02.037Z","dependency_job_id":"cbaa241c-dc7e-472f-a2c1-12c0ee2ad821","html_url":"https://github.com/odch/aerodromes","commit_stats":null,"previous_names":["odch/aerodromes"],"tags_count":34,"template":false,"template_full_name":null,"purl":"pkg:github/odch/aerodromes","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/odch%2Faerodromes","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/odch%2Faerodromes/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/odch%2Faerodromes/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/odch%2Faerodromes/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/odch","download_url":"https://codeload.github.com/odch/aerodromes/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/odch%2Faerodromes/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28482314,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-16T11:59:17.896Z","status":"ssl_error","status_checked_at":"2026-01-16T11:55:55.838Z","response_time":107,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":[],"created_at":"2026-01-16T20:48:01.038Z","updated_at":"2026-01-16T20:48:01.886Z","avatar_url":"https://github.com/odch.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Aerodrome Registry\n\nA comprehensive registry of all aerodromes worldwide that have ICAO codes. This serves as a single source of truth for multiple projects requiring aerodrome data.\n\n## Overview\n\nThis registry contains essential information for each aerodrome:\n- **ICAO Code**: 4-letter international identifier\n- **Name**: Official aerodrome name\n- **Country**: Country location\n- **Timezone**: IANA timezone identifier\n\n## Data Format\n\nThe registry uses JSON format for maximum compatibility and ease of integration:\n\n```json\n{\n  \"version\": \"1.0.0\",\n  \"last_updated\": \"2025-09-22T22:40:31+02:00\",\n  \"total_count\": 4,\n  \"aerodromes\": [\n    {\n      \"icao\": \"KJFK\",\n      \"name\": \"John F. Kennedy International Airport\",\n      \"country\": \"United States\",\n      \"timezone\": \"America/New_York\"\n    }\n  ]\n}\n```\n\n## Files\n\n- `aerodromes.json` - Main registry file containing all aerodrome data\n- `schema.json` - JSON Schema for data validation\n- `README.md` - This documentation file\n\n## Usage\n\n### For Nightly Database Imports\n\nMost projects can import this data directly into their databases:\n\n**Python Example:**\n```python\nimport json\nimport requests\nfrom datetime import datetime\n\ndef import_aerodromes():\n    with open('aerodromes.json', 'r') as f:\n        data = json.load(f)\n    \n    for aerodrome in data['aerodromes']:\n        # Insert into your database\n        insert_aerodrome(\n            icao=aerodrome['icao'],\n            name=aerodrome['name'],\n            country=aerodrome['country'],\n            timezone=aerodrome['timezone']\n        )\n    \n    print(f\"Imported {data['total_count']} aerodromes\")\n```\n\n**Node.js Example:**\n```javascript\nconst fs = require('fs').promises;\n\nasync function importAerodromes() {\n    const data = JSON.parse(await fs.readFile('aerodromes.json', 'utf8'));\n    \n    for (const aerodrome of data.aerodromes) {\n        await insertAerodrome({\n            icao: aerodrome.icao,\n            name: aerodrome.name,\n            country: aerodrome.country,\n            timezone: aerodrome.timezone\n        });\n    }\n    \n    console.log(`Imported ${data.total_count} aerodromes`);\n}\n```\n\n### Data Validation\n\nUse the provided JSON Schema to validate data integrity:\n\n```bash\n# Using ajv-cli\nnpm install -g ajv-cli\najv validate -s schema.json -d aerodromes.json\n```\n\n```python\n# Using jsonschema library\nimport json\nimport jsonschema\n\nwith open('schema.json', 'r') as f:\n    schema = json.load(f)\n\nwith open('aerodromes.json', 'r') as f:\n    data = json.load(f)\n\njsonschema.validate(data, schema)\nprint(\"Data is valid!\")\n```\n\n## Data Sources\n\nThis registry is built using the following open data sources:\n\n### Primary Data Sources\n\n1. **OurAirports** (https://ourairports.com)\n   - **License**: Public Domain (Unlicense)\n   - **Usage**: Airport names, locations, and ICAO codes\n   - **Attribution**: David Megginson and contributors\n\n2. **OpenFlights** (https://openflights.org)\n   - **License**: Open Database License (ODbL)\n   - **Usage**: Timezone data for airports\n   - **Attribution**: OpenFlights.org contributors\n\n### Data Processing\n\n- Airport data is sourced primarily from OurAirports (public domain)\n- Timezone information is enhanced using OpenFlights data where available\n- Fallback timezone mapping is applied based on country location\n- The registry includes both 'icao_code' and 'ident' fields from OurAirports to ensure comprehensive coverage\n\n## Maintenance\n\n### Automated Workflow\n\nThis registry uses a **GitOps workflow** with automated data synchronization and manual review/release process.\n\n#### 🤖 Automated Sync Process\n\n**Every Monday at 6:00 AM UTC** (or manually triggered), GitHub Actions automatically:\n\n1. **Downloads** fresh data from OurAirports and OpenFlights\n2. **Processes** data using `sync_aerodromes.py`\n3. **Creates** `aerodromes-staging.json` with latest information\n4. **Compares** staging vs production data\n5. **If changes detected**:\n   - Commits staging file to repository\n   - Generates detailed change summary\n   - **Creates GitHub Issue** for manual review\n\n#### 👤 Review \u0026 Release Process\n\nWhen automation detects changes, **you receive a GitHub Issue** with:\n- Detailed change summary and statistics\n- Instructions for next steps\n- Automatic labels for easy tracking\n\n### 🤖 **Automated Release (Recommended)**\n\nSimply **comment on the GitHub Issue** with one of these commands:\n\n**To approve and release:**\n- `!release patch` - For data updates, new airports, corrections\n- `!release minor` - For new fields, backward-compatible changes  \n- `!release major` - For breaking changes, schema updates\n- `!release patch Fixed timezone data` - Add optional description\n\n**To reject:**\n- `!reject` or `!reject Reason for rejection`\n\n**What happens automatically:**\n1. ✅ Validates staging data\n2. ✅ Creates production backup \n3. ✅ Bumps version (patch/minor/major)\n4. ✅ Releases to production\n5. ✅ Commits \u0026 creates Git tag\n6. ✅ Closes issue with summary\n\n### 🖥️ **Manual Release (Legacy)**\n\nFor local development or when automation fails:\n- **Review**: Run `python3 review_changes.py` to see detailed changes\n- **Approve**: Run `python3 release.py` to promote staging → production\n- **Reject**: Do nothing, changes remain in staging only\n\n#### 🔒 Safety Features\n\n- **Production never touched by automation** - Always requires manual approval\n- **Automatic backups** created before each release\n- **Rollback capability** if issues arise\n- **Data validation** before promotion\n- **Clear audit trail** through Git commits and Issues\n\n#### 📁 Key Files\n\n- **`aerodromes.json`** - 🟢 PRODUCTION (what applications consume)\n- **`aerodromes-staging.json`** - 🟡 STAGING (automated updates)\n- **`sync_aerodromes.py`** - Downloads and processes source data\n- **`review_changes.py`** - Shows differences between staging and production  \n- **`release.py`** - Promotes staging to production with backups\n\n### Manual Maintenance\n\n#### Adding Individual Aerodromes (Not Recommended)\n\nFor emergency additions only. **Prefer the automated sync process** for data quality.\n\n1. Ensure the aerodrome has a valid 4-letter ICAO code\n2. Add entry to the `aerodromes` array in `aerodromes.json`\n3. Update `total_count` field\n4. Update `last_updated` timestamp\n5. Validate against schema\n6. Commit changes\n\n### Semantic Versioning\n\nThis registry follows [Semantic Versioning](https://semver.org/) (MAJOR.MINOR.PATCH):\n\n#### Version Types\n\n- **🔴 MAJOR** (x.0.0): Breaking changes to JSON structure or schema\n  - Removing required fields\n  - Changing field names or types  \n  - Altering data format significantly\n  - Example: `1.0.0` → `2.0.0`\n\n- **🟡 MINOR** (0.x.0): Backward-compatible additions\n  - Adding new optional fields\n  - Expanding existing data without breaking apps\n  - Schema enhancements that don't break existing consumers\n  - Example: `1.0.0` → `1.1.0`\n\n- **🟢 PATCH** (0.0.x): Data updates and corrections\n  - New airports added\n  - Airport information corrected\n  - Timezone assignments updated\n  - Bug fixes in data processing\n  - Example: `1.0.0` → `1.0.1`\n\n#### Version Management\n\n**The `release.py` script handles version updates:**\n- Prompts you to choose version bump type (patch/minor/major)\n- Updates the `VERSION` file automatically\n- Integrates with the release process\n- Commits version changes with descriptive messages\n\n**Manual version updates:**\n```bash\n# View current version\ncat VERSION\n\n# Manual update (if needed)\necho \"1.0.1\" \u003e VERSION\ngit add VERSION\ngit commit -m \"🏷️ Bump version to 1.0.1\"\n```\n\n**Version in API Response:**\n```json\n{\n  \"version\": \"1.0.0\",\n  \"last_updated\": \"2025-09-24T09:00:00Z\", \n  \"total_count\": 19356,\n  \"aerodromes\": [...]\n}\n```\n\n#### Application Compatibility\n\nConsumer applications should check version compatibility:\n\n```python\nimport requests\n\ndef fetch_aerodromes_safe():\n    response = requests.get(\"https://raw.githubusercontent.com/username/repo/main/aerodromes.json\")\n    data = response.json()\n    \n    version = data['version']\n    major_version = int(version.split('.')[0])\n    \n    if major_version \u003e 1:\n        print(f\"⚠️ Warning: Data version {version} may contain breaking changes\")\n        # Handle version compatibility\n    \n    return data\n```\n\n## Contributing\n\n1. Fork the repository\n2. Make your changes\n3. Validate data against schema\n4. Submit a pull request with description of changes\n\n## License\n\n### Registry Software \u0026 Code\nThis project (code, scripts, and documentation) is licensed under the **MIT License**. See the [LICENSE](LICENSE) file for details.\n\n### Data Licensing \u0026 Attribution\n\nThis registry uses data from the following sources with their respective licenses:\n\n1. **OurAirports Data**: Public Domain (Unlicense)\n   - No attribution required, but we credit David Megginson and contributors\n   - Source: https://github.com/davidmegginson/ourairports-data\n\n2. **OpenFlights Data**: Open Database License (ODbL) v1.0\n   - Requires attribution and share-alike for derivative works\n   - Source: https://openflights.org\n   - License: https://opendatacommons.org/licenses/odbl/1-0/\n\n### Usage Compliance\n\n**If you use this registry:**\n- ✅ You can use it freely for any purpose (commercial or non-commercial)\n- ✅ Attribution is appreciated but not legally required for the registry itself\n- ✅ The underlying airport data is largely public domain\n\n**If you create derivative works:**\n- 📝 Please maintain attribution to data sources (good practice)\n- 📝 For works using OpenFlights-derived data, follow ODbL requirements\n- 📝 Consider contributing improvements back to the community\n\n### Disclaimer\n\nThis data is not suitable for navigation. The maintainers assume no responsibility for accuracy and no liability for results obtained or damages incurred from using this data.\n\n## Support\n\nFor questions or issues, please create an issue in the repository or contact the maintainers.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fodch%2Faerodromes","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fodch%2Faerodromes","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fodch%2Faerodromes/lists"}