Metadata-Version: 2.4
Name: georavity
Version: 1.0.0
Summary: Official Python SDK for the Georavity Geospatial API — routing, geocoding, and map tiles.
Author-email: Georavity <hello@georavity.com>
License: MIT
Project-URL: Homepage, https://georavity.com
Project-URL: Documentation, https://georavity.com/docs
Project-URL: Repository, https://github.com/georavity/georavity-python
Project-URL: Issues, https://github.com/georavity/georavity-python/issues
Keywords: georavity,routing,geocoding,maps,geospatial,osm,openstreetmap
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: GIS
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.28.0

# georavity

Official Python SDK for the **Georavity Geospatial API** — routing, geocoding, isochrones, and more.

## Installation

```bash
pip install georavity
```

## Quick Start

```python
from georavity import Georavity

geo = Georavity("gr_your_api_key")

# Route between two points
route = geo.route(
    locations=[
        {"lon": 13.388860, "lat": 52.517037},  # Berlin Hauptbahnhof
        {"lon": 13.397634, "lat": 52.529407},  # Mauerpark
    ],
    costing="auto",
)
print(f"Distance: {route['trip']['summary']['length']} km")
print(f"Duration: {route['trip']['summary']['time']} seconds")
```

## API Reference

### Routing

```python
# Standard route
route = geo.route(
    locations=[{"lat": 52.52, "lon": 13.40}, {"lat": 48.85, "lon": 2.35}],
    costing="auto",  # "auto" | "bicycle" | "pedestrian" | "truck"
)

# Optimized route (TSP)
optimized = geo.optimized_route(
    locations=[
        {"lat": 52.52, "lon": 13.40},
        {"lat": 48.85, "lon": 2.35},
        {"lat": 51.50, "lon": -0.12},
    ],
    costing="auto",
)

# Distance/time matrix
matrix = geo.matrix(
    sources=[{"lat": 52.52, "lon": 13.40}],
    targets=[{"lat": 48.85, "lon": 2.35}, {"lat": 51.50, "lon": -0.12}],
    costing="auto",
)

# Isochrone
iso = geo.isochrone(
    locations=[{"lat": 52.52, "lon": 13.40}],
    costing="auto",
    contours=[{"time": 15}, {"time": 30}],
    polygons=True,
)
```

### Geocoding

```python
# Forward geocode
results = geo.geocode("Brandenburg Gate, Berlin")

# With focus point (biases results near the given location)
results = geo.geocode("coffee", focus_lat=52.52, focus_lon=13.40)

# Reverse geocode
place = geo.reverse(lat=52.5163, lon=13.3777)

# Autocomplete
suggestions = geo.autocomplete("Bran", focus_lat=52.52, focus_lon=13.40)
```

### Error Handling

```python
from georavity import Georavity, GeoravityError

try:
    route = geo.route(...)
except GeoravityError as e:
    print(f"API Error [{e.code}]: {e}")
    print(f"HTTP Status: {e.status}")
```

## License

MIT — [georavity.com](https://georavity.com)
