# OpenGeo Cambodia API

> High-performance Cambodian Geographic & Administrative Division API providing sub-millisecond cascading lookups across all 25 Provinces, 210 Districts, 1,661 Communes, and 14,576 Villages with smart OpenStreetMap geocoding.

## Overview & Core Architecture

OpenGeo Cambodia provides standard 4-tier administrative boundary resolution for digital products operating in the Kingdom of Cambodia (logistics, e-commerce, fintech KYC, government forms):
`City / Province (រាជធានី / ខេត្ត) -> District / Khan / Krong (ស្រុក / ខណ្ឌ / ក្រុង) -> Commune / Sangkat (ឃុំ / សង្កាត់) -> Village (ភូមិ)`

- **Base URL**: `https://opengeo-cambodia.pphat.me` (or `http://localhost:3000` locally)
- **Interactive Playground**: `https://opengeo-cambodia.pphat.me/demo`
- **Full LLM Reference**: [llms-full.txt](https://opengeo-cambodia.pphat.me/llms-full.txt)
- **API Spec & Metadata**: `GET /api/info`
- **Health Check**: `GET /health`
- **Rate Limits**: 120 requests/min for `/api/admin/*`, 30 requests/min for `/api/geocode/*` (IP-based, standard `X-RateLimit-*` headers)
- **Data Latency**: Sub-1ms for in-memory administrative lookups; ~100-300ms for Nominatim OSM reverse geocoding

## Administrative Hierarchy (4 Tiers)

| Tier | Cambodian Name (KM) | Latin Romanization | Total Count | Standard Code Length |
| :--- | :--- | :--- | :--- | :--- |
| **Tier 1: Province** | រាជធានី / ខេត្ត | Reachdhanie / Khaet | **25** (1 Capital + 24 Provinces) | 2 digits (e.g. `12`) |
| **Tier 2: District** | ស្រុក / ខណ្ឌ / ក្រុង | Srok / Khan / Krong | **210** (14 Khans + 32 Krongs + 164 Sroks) | 4 digits (e.g. `1202`) |
| **Tier 3: Commune** | ឃុំ / សង្កាត់ | Khum / Sangkat | **1,661** | 6 digits (e.g. `120201`) |
| **Tier 4: Village** | ភូមិ | Phum (Village) | **14,576** | 8 digits (e.g. `12020101`) |

## Quick API Reference

### Administrative Lookups (In-Memory, < 1ms)
- `GET /api/admin/provinces`: List all 25 provinces/capital with Khmer & English names, coordinates, and codes.
- `GET /api/admin/provinces/:id/districts`: List all districts / khans / krongs within a province (e.g. `:id` = `12` for Phnom Penh).
- `GET /api/admin/districts/:id/communes`: List all communes / sangkats within a district (e.g. `:id` = `1202` for Doun Penh).
- `GET /api/admin/communes/:id/villages`: List all villages within a commune (e.g. `:id` = `120201` for Phsar Thmei 1).
- `GET /api/admin/item/:id`: Fetch a single administrative record by numeric ID.
- `GET /api/admin/hierarchy/:id`: Resolves the complete ascending 4-tier tree (Province -> District -> Commune -> Village) for any division ID.
- `GET /api/admin/search?q=:query&level=:level&limit=:limit`: Sub-millisecond full-text search across Khmer script and Latin romanizations.
- `GET /api/admin/stats`: Summary counts of loaded administrative units (25 provinces, 210 districts, 1,661 communes, 14,576 villages).

### Smart Geocoding (OSM & Nominatim)
- `GET /api/geocode/reverse?lat=:lat&lon=:lon`: Reverse geocode a GPS coordinate into the standardized 4-tier Cambodian address model.
- `GET /api/geocode/search?q=:query&limit=:limit`: Free-text geocoding search bounded to Cambodia territory.

## Common Code Patterns

### 1. Fetch Provinces & Districts (TypeScript / Fetch)
```ts
const API_BASE = 'https://opengeo-cambodia.pphat.me';

// 1. Get all provinces
const provinces = await fetch(`${API_BASE}/api/admin/provinces`).then(r => r.json());

// 2. Get districts for Phnom Penh (ID: 12)
const districts = await fetch(`${API_BASE}/api/admin/provinces/12/districts`).then(r => r.json());
```

### 2. Reverse Geocode GPS to Cambodian Address (Python)
```python
import requests

res = requests.get('https://opengeo-cambodia.pphat.me/api/geocode/reverse', params={
    'lat': 11.5564,
    'lon': 104.9282
}).json()

print(res['data']['displayName'])
# Output: Doun Penh, Phnom Penh, 120201, Cambodia
```

## Detailed Documentation
- [Full LLM Specification & Schemas](https://opengeo-cambodia.pphat.me/llms-full.txt): Comprehensive schemas, status codes, gotchas, and complete TypeScript/Python SDK integration patterns.
- [Interactive Web Playground](https://opengeo-cambodia.pphat.me/demo): Live testing interface with tree cascading selector, interactive Leaflet map, and address search.
- [GitHub Repository](https://github.com/pphatdev/opengeo-cambodia): Open-source source code, Overpass QL sync scripts, and CSV update utilities.