# 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)
