# Climate API
> Classify any location's climate with the Köppen-Geiger system — the standard used across geography, ecology, agriculture and architecture. Provide a location's twelve monthly mean temperatures and precipitation totals and get back its climate code (for example Cfb or BWh), the climate group and full name, a description, and a block of derived statistics (annual mean temperature, annual precipitation, warmest and coldest month, driest month, months above 10 °C, summer-precipitation share and the aridity threshold). The hemisphere is auto-detected from the temperature curve, or you can set it explicitly. A reference endpoint returns all thirty Köppen-Geiger codes with names, groups, descriptions and example cities. Every endpoint accepts input via the query string or the request body and returns lean JSON. Pure server-side computation (no third-party upstream), so responses are instant and always available. Ideal for EdTech and geography tools, AgTech and crop-suitability apps, architecture and GIS pipelines.

## Authentication
All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys.

```bash
curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/climate-api/..."
```

## Pricing
- **Free** (Free) — 14,000 calls/Mo, 4 req/s
- **Basic** ($5/Mo) — 175,000 calls/Mo, 12 req/s
- **Pro** ($15/Mo) — 1,300,000 calls/Mo, 40 req/s
- **Mega** ($39/Mo) — 6,500,000 calls/Mo, 130 req/s

## Endpoints

### Climate

#### `GET /v1/classify` — Köppen-Geiger code from monthly data

**Parameters:**
- `monthly_temp` (query, required, string) — 12 monthly mean temps °C (Jan..Dec) Example: `5,5,7,9,13,16,18,18,15,11,7,5`
- `monthly_precip` (query, required, string) — 12 monthly precip mm (Jan..Dec) Example: `55,41,42,44,49,45,45,50,49,69,59,55`
- `hemisphere` (query, optional, string) — north|south (auto-detected) Example: `north`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/climate-api/v1/classify?monthly_temp=5%2C5%2C7%2C9%2C13%2C16%2C18%2C18%2C15%2C11%2C7%2C5&monthly_precip=55%2C41%2C42%2C44%2C49%2C45%2C45%2C50%2C49%2C69%2C59%2C55&hemisphere=north"
```

**Response:**
```json
{
    "data": {
        "code": "Cfb",
        "group": "Temperate",
        "hemisphere": "north",
        "statistics": {
            "coldest_month_c": 5,
            "driest_month_mm": 41,
            "warmest_month_c": 18,
            "annual_precip_mm": 603,
            "months_above_10c": 6,
            "annual_mean_temp_c": 10.8,
            "summer_precip_share": 0.47,
            "aridity_threshold_mm": 36
        },
        "description": "No dry season, warm summer.",
        "climate_name": "Oceanic"
    },
    "meta": {
        "timestamp": "2026-05-30T22:48:31.401Z",
        "request_id": "a4d65d9e-71d0-46b7-9864-eec1ba7a1f8e"
    },
    "status": "ok",
    "message": "Climate classified",
    "success": true
}
```

#### `GET /v1/code` — Single code detail

**Parameters:**
- `code` (query, required, string) — Köppen code Example: `Cfb`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/climate-api/v1/code?code=Cfb"
```

**Response:**
```json
{
    "data": {
        "code": "Cfb",
        "name": "Oceanic",
        "group": "Temperate",
        "examples": [
            "London",
            "Paris",
            "Melbourne"
        ],
        "description": "No dry season, warm summer."
    },
    "meta": {
        "timestamp": "2026-05-30T22:48:31.472Z",
        "request_id": "7dce870c-0ef1-4f91-8c8e-e1aee1ee0d06"
    },
    "status": "ok",
    "message": "Code retrieved",
    "success": true
}
```

#### `GET /v1/codes` — All Köppen-Geiger codes

**Parameters:**
- `group` (query, optional, string) — Tropical|Arid|Temperate|Continental|Polar Example: `Polar`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/climate-api/v1/codes?group=Polar"
```

**Response:**
```json
{
    "data": {
        "codes": [
            {
                "code": "ET",
                "name": "Tundra",
                "group": "Polar",
                "examples": [
                    "Nuuk",
                    "Barrow",
                    "Mount Washington"
                ],
                "description": "Warmest month 0–10 °C."
            },
            {
                "code": "EF",
                "name": "Ice cap",
                "group": "Polar",
                "examples": [
                    "Vostok Station",
                    "Greenland interior"
                ],
                "description": "All months below 0 °C."
            }
        ],
        "count": 2
    },
    "meta": {
        "timestamp": "2026-05-30T22:48:31.542Z",
        "request_id": "0354bd8e-1ac0-409b-9ec9-0a76ebe7c0fe"
    },
    "status": "ok",
    "message": "Codes retrieved",
    "success": true
}
```


---
Marketplace page: https://www.oanor.com/api/climate-api
OpenAPI spec: https://www.oanor.com/api/climate-api/openapi.json