boc/LANDVEX_API.md

# LANDVEX — Public API Architecture
**Beslutad:** 2026-06-21, Erik Svensson
**Princip:** API:et är produkten. Enkel integration. Enterprise-grade output.

---

## Design Philosophy

- **En rad kod** för att få ett Intelligence Assessment på en koordinat
- **Välkänd standard** — REST + JSON, ingen proprietär SDK krävs
- **Transparent** — varje svar inkluderar confidence, data age, methodology version
- **Freemium** — gratis historisk data, betald live intelligence

---

## Endpoint-struktur

### 1. Point Intelligence
```
GET /v1/intelligence/point?lat=59.334&lng=18.063&profile=business
```
Returnerar Intelligence Assessment för en koordinat.

### 2. Area Intelligence
```
GET /v1/intelligence/area?bbox=59.28,17.90,59.40,18.20&profile=safety
```
Returnerar alla zoner inom en bounding box.

### 3. Contradiction Score
```
GET /v1/contradiction?lat=59.334&lng=18.063
```
Returnerar enbart Contradiction Index för en punkt — lätt att konsumera.

### 4. City Brief
```
GET /v1/cities/stockholm?profile=investment
```
Komplett Intelligence Brief för en stad.

### 5. District Ranking
```
GET /v1/cities/stockholm/districts?profile=nightlife&sort=score
```
Sorterad distriktsranking per profil.

### 6. Batch
```
POST /v1/intelligence/batch
{ "points": [{"lat":...,"lng":...}, ...], "profile": "business" }
```
Upp till 100 koordinater per anrop.

### 7. Tile Overlay (XYZ)
```
GET /v1/tiles/{z}/{x}/{y}.png?profile=safety&apikey=...
```
Direkt inbäddning i Mapbox/Leaflet/ArcGIS/QGIS utan preprocessing.

---

## Response Format

```json
{
  "point": { "lat": 59.334, "lng": 18.063 },
  "district": "Södermalm",
  "city": "Stockholm",
  "country": "SE",
  "profile": "business",
  "assessment": {
    "score": 6.8,
    "grade": "B",
    "label": "Moderate business activity",
    "color": "#eab308"
  },
  "indices": {
    "infrastructure": 7.1,
    "safety": 7.2,
    "commercial_activity": 7.8,
    "night_risk": 6.1
  },
  "contradiction": {
    "score": "medium",
    "description": "Official infrastructure ratings overstate actual road conditions in SoFo area.",
    "deviation_pct": 14,
    "official_source": "Stockholm stad, 2025",
    "observed_source": "quiXzoom observations, 847 data points"
  },
  "confidence": {
    "score": 88,
    "data_age_days": 45,
    "observation_count": 847,
    "methodology_version": "1.2"
  },
  "live_available": true,
  "data_tier": "historical",
  "generated_at": "2026-06-21T10:14:00Z"
}
```

---

## Tiers

| Tier | Pris | Vad ingår |
|------|------|-----------|
| **Free** | $0 | 1 000 req/mån, historisk data (30+ dagar), point + area |
| **Starter** | $99/mån | 50 000 req/mån, historisk + 7-dagars lag |
| **Professional** | $499/mån | 500 000 req/mån, 24h lag, batch, tile overlay |
| **Enterprise** | Custom | Live intelligence, SLA, dedikerad pipeline, webhook push |

---

## Integrationsmål (1 rad kod)

**Mapbox:**
```js
map.addSource('landvex', { type: 'raster', tiles: ['https://api.landvex.com/v1/tiles/{z}/{x}/{y}.png?profile=safety&apikey=KEY'] });
```

**Python:**
```python
import requests
r = requests.get('https://api.landvex.com/v1/intelligence/point', params={'lat':59.334,'lng':18.063,'profile':'business'}, headers={'X-API-Key':'KEY'})
```

**curl:**
```bash
curl "https://api.landvex.com/v1/contradiction?lat=59.334&lng=18.063" -H "X-API-Key: KEY"
```

---

## Nästa steg
1. Definiera OpenAPI 3.0-spec
2. Bygg mock-endpoint på api.landvex.com
3. Dokumentationssida (/api-docs)
4. API-nyckelhantering