Metadata-Version: 2.4
Name: offlineRevGeocoder
Version: 0.1.0
Summary: Fast offline reverse geocoding using a prepared Natural Earth cache
Home-page: https://github.com/aminjavadi02/reverseGeocoder-py
Author: AminJavadi
License: MIT
Project-URL: Source, https://github.com/aminjavadi02/reverseGeocoder-py
Project-URL: Natural Earth, https://www.naturalearthdata.com/
Keywords: geocoder,geocoding,gis,natural-earth,reverse-geocoding
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: GIS
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: author
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: project-url
Dynamic: requires-python
Dynamic: summary

# 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](https://www.naturalearthdata.com/),
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](https://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

```bash
pip install offlineRevGeocoder
```

## Usage

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

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

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