offlineRevGeocoder 0.1.0

Fast offline reverse geocoding using a prepared Natural Earth cache

Reverse Geocoder

Tiny offline reverse geocoding for Python.

offlineRevGeocoder takes a latitude and longitude and returns a small GeoResult object with the matching country, continent, ocean, and nearest city when one is close enough. It is intentionally simple: the geographic source data is prepared ahead of time, cached as a pickle file, and loaded locally at runtime. No API keys, no network requests, no external service latency.

The bundled lookup data is derived from Natural Earth, a public domain map dataset. The prepared cache is included so callers can use the package immediately.

Project Info

• PyPI package: offlineRevGeocoder
• Import package: offlineRevGeocoder
• Source code: github.com/aminjavadi02/reverseGeocoder-py
• License: MIT
• Author: AminJavadi

This is an open-source package. Bug reports, fixes, data improvements, and documentation updates are welcome; please open an issue or send a pull request on GitHub.

Install

pip install offlineRevGeocoder

Usage

from offlineRevGeocoder import get

result = get(35.6892, 51.3890)

print(result.country)          # Iran
print(result.country_iso2)     # IR
print(result.city)             # Tehran
print(result.precision)        # city

Common Use Case

This package is most useful when you only need a small reverse geocoding answer, for example checking whether a user's latitude and longitude are in or near a specific city. In that kind of flow, you often do not need to pay for a full reverse geocoding API subscription.

from offlineRevGeocoder import get

place = get(35.7000, 51.4000, city_radius_km=25)

print(place.city)              # Tehran
print(place.precision)         # city
print(place.city == "Tehran")  # True

For a nearby-city check, use city_radius_km to control how strict the match should be for your product.

Return Type

get(lat, lon, city_radius_km=50) returns:

GeoResult(
    continent: str | None,
    country: str | None,
    country_iso2: str | None,
    country_iso3: str | None,
    ocean: str | None,
    city: str | None,
    city_distance_km: float | None,
    precision: str,
)

precision is one of:

• city: a nearby city was found.
• country: the point matched a country, but no nearby city was found.
• ocean: the point matched an ocean or marine area.
• none: no matching land or ocean feature was found.

Data

The package uses Natural Earth datasets that were transformed into a compact pickle cache at offlineRevGeocoder/data/reverse_geocoder_cache.pkl. Natural Earth data is public domain, so it can be redistributed with this MIT-licensed package.

The code is MIT licensed. Natural Earth requests attribution where possible; this README keeps that attribution with the package.