Aareon/GeoNamesMirror
1
0
Fork 0
Code Issues Pull requests Projects Releases 107 Packages Wiki Activity Actions
Automated mirror of GeoNames geographical database, updated weekly. https://geonames.org
12 commits 1 branch 110 tags 66 KiB
  • Python 100%
Find a file
Exact
Claude 3c51288324 Forgejo Actions: run the weekly update here, same behavior as GitHub 
.forgejo/workflows/update_allCountries.yml ports the GitHub workflow step
for step: Sunday 00:00 UTC, release <branch>-<n> with allCountries.zip and
the same notes. Forced differences: n = run_number + 114 to continue after
the main-114 copied from GitHub; forgejo-release instead of the GitHub-only
softprops action; outputs via FORGEJO_OUTPUT. update_allCountries.py now
reads the previous release from RELEASES_API_URL (default unchanged: the
GitHub API). Manual runs take dry_run to skip publishing.

Agent: Aki
2026-10-09 09:56:39 -05:00
.forgejo/workflows Forgejo Actions: run the weekly update here, same behavior as GitHub 2026-10-09 09:56:39 -05:00
.github/workflows Upgrade artifacts action to v4 2024-09-17 19:05:27 -05:00
.gitignore Improve release and update info 2024-09-17 18:14:40 -05:00
LICENSE Initial commit 2024-09-17 14:13:06 -05:00
poetry.lock Improve release and update info 2024-09-17 18:14:40 -05:00
pyproject.toml Improve release and update info 2024-09-17 18:14:40 -05:00
README.md Add Python shield 2024-09-17 14:16:55 -05:00
update_allCountries.py Forgejo Actions: run the weekly update here, same behavior as GitHub 2026-10-09 09:56:39 -05:00

README.md

🌍 GeoNamesMirror

Data Update Python Version Data License: CC BY 4.0

Automated mirror of GeoNames geographical database, updated weekly.

🎯 Purpose

This repository serves as an automated mirror for the GeoNames allCountries.zip dataset. It provides a reliable, versioned source for GeoNames postal code data, updated on a weekly basis.

🔄 Update Schedule

The GeoNames data is checked for updates every Sunday at 00:00 UTC. If new data is available, this repository will automatically create a new release with the updated allCountries.zip file.

📦 Accessing the Data

You can access the latest GeoNames data in two ways:

  1. Latest Release: Always points to the most recent data.

    • URL: https://github.com/Aareon/GeoNamesMirror/releases/latest/download/allCountries.zip

  2. Specific Version: Access a specific version of the data by its release tag.

    • URL: https://github.com/Aareon/GeoNamesMirror/releases/download/release-{number}/allCountries.zip
    • Replace {number} with the specific release number you want to access.

🛠️ Implementation Details

update_allCountries.py

This Python script is responsible for:

  • Checking if a new version of the GeoNames data is available
  • Downloading the new data if an update is found
  • Preparing the data for release

Key features:

  • Uses httpx for asynchronous HTTP requests
  • Implements robust error handling and logging
  • Verifies data integrity after download

update_allCountries.yml

This GitHub Actions workflow:

  • Runs on a weekly schedule (every Sunday at 00:00 UTC)
  • Can also be triggered manually
  • Executes the update_allCountries.py script
  • Creates a new release with the updated data if changes are detected

📊 Data Statistics

Each release includes basic statistics about the data:

  • Total number of entries
  • Number of countries covered
  • File size
  • MD5 checksum of the zip file

📜 License

This project is dual-licensed:

🙏 Acknowledgements

This project uses data from GeoNames, which is made available under the Creative Commons Attribution 4.0 License.

🚀 Using this Data

This mirrored data is ideal for:

  • Applications requiring offline access to GeoNames data
  • Projects that need a stable, versioned source of GeoNames data
  • Automated pipelines that depend on GeoNames postal code information

To use this data in your project, you can download the latest release or a specific version as needed. Always ensure you comply with the Creative Commons Attribution 4.0 License when using this data.

🤝 Contributing

While this repository is primarily automated, we welcome contributions to improve the update script or GitHub Actions workflow. Please feel free to submit issues or pull requests. Note that any contributions to the code will be under the MIT License.

📬 Contact

If you have any questions, encounter any issues, or would like to request enhancements, please create an issue in this repository. We appreciate your feedback and contributions!

Project Link: https://github.com/Aareon/GeoNamesMirror