boc/iom/sdk/python/README.md

# Landvex Python SDK

> Official Python client for Landvex Urban Intelligence API.

## Installation

```bash
pip install landvex
```

Or from source:

```bash
git clone https://github.com/landvex/python-sdk.git
cd python-sdk
pip install -e .
```

## Quick Start

```python
from landvex import create_client

# Initialize client
client = create_client("your-api-key")

# Check API health
health = client.health_check()
print(f"Status: {health['status']}")

# List observations
observations = client.list_observations(
    lat=59.3293,
    lng=18.0686,
    radius=1000,
    limit=100
)

for obs in observations:
    print(f"{obs.id}: {obs.obj_type} (condition: {obs.condition}/5)")

# Get RGI score
rgi = client.get_rgi(59.3293, 18.0686)
print(f"RGI: {rgi['rgi']}")

# Get recommendations
recommendations = client.get_recommendations(
    stakeholder="municipality",
    lat=59.3293,
    lng=18.0686
)

for rec in recommendations['recommendations']:
    print(f"- {rec['recommendation']} (impact: {rec['expected_impact']})")
```

## API Reference

### Client Initialization

```python
from landvex import LandvexClient

client = LandvexClient(
    api_key="your-api-key",
    base_url="https://api.landvex.com/v1"  # Optional
)
```

### Observations

```python
# List observations
observations = client.list_observations(
    lat=59.3293,      # Optional: filter by location
    lng=18.0686,      # Optional: filter by location
    radius=1000,      # Optional: search radius in meters
    limit=100,        # Optional: max results
    status="approved" # Optional: filter by status
)

# Get single observation
obs = client.get_observation("OBS-001247")

# Create observation
new_obs = client.create_observation(
    lat=59.3293,
    lng=18.0686,
    image_url="https://...",
    evidence={...}
)
```

### Missions

```python
# List missions
missions = client.list_missions(status="active")

# Accept mission
client.accept_mission("M001")
```

### Indexes

```python
# Reality Gap Index
rgi = client.get_rgi(59.3293, 18.0686)

# Urban Morphology Index
umi = client.get_umi(59.3293, 18.0686)
```

### Visual Geolocation

```python
# Analyze image
result = client.analyze_image(
    image_path="/path/to/image.jpg",
    image_id="optional-id"
)

# Batch analyze
results = client.batch_analyze([
    {"path": "image1.jpg", "id": "1"},
    {"path": "image2.jpg", "id": "2"},
])
```

### Decisions

```python
recommendations = client.get_recommendations(
    stakeholder="municipality",  # or "property_owner", "citizen"
    lat=59.3293,
    lng=18.0686
)
```

## Data Models

### Observation

```python
@dataclass
class Observation:
    id: str
    lat: float
    lng: float
    condition: int  # 1-5
    obj_type: str
    zoomer: str
    status: str
    date: str
    rgi: Optional[float]
```

### Mission

```python
@dataclass
class Mission:
    id: str
    title: str
    description: str
    category: str
    difficulty: str
    reward_usd: float
    total_observations: int
    completed_observations: int
    deadline: str
```

## Error Handling

```python
from requests.exceptions import HTTPError

try:
    observations = client.list_observations()
except HTTPError as e:
    if e.response.status_code == 401:
        print("Invalid API key")
    elif e.response.status_code == 429:
        print("Rate limit exceeded")
    else:
        print(f"Error: {e}")
```

## Requirements

- Python 3.7+
- requests

## License

MIT