# Historical weather (SBX-WHIST)

Daily weather since 1981 and hourly since 2001, monthly climate normals, and heating and cooling degree days.

Version: v1.0

## Authentication

Send your API key on every request, either as a Bearer token or as the `apikey` query parameter:

```
Authorization: Bearer <YOUR_API_KEY>
https://api.servicebox.io/v1/weather-history/...?apikey=<YOUR_API_KEY>
```

Get a key: sign up at https://servicebox.io/en/signup and create one on the dashboard. An agent can sign up itself with `POST https://api.servicebox.io/v1/accounts` and `{"email": "...", "apis": ["weather-history"]}`: the owner of the mailbox approves by email and the agent collects a short-lived key by polling the returned `poll_url`.

## Base URL

`https://api.servicebox.io`

## Endpoints

### GET /v1/weather-history/days

**Daily history**

Daily mean, high and low temperature, precipitation, humidity and wind for `start`–`end` (inclusive, at most 366 days), from 1981-01-01 to a few days ago. Recent days NASA POWER has not filled yet are null.

**Credits:** 1 per call

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `cityId` | query | string | no | A city id from the Cities API, e.g. 745044 (İstanbul). |
| `lat` | query | number | no | Latitude (WGS84), with `lon`. |
| `lon` | query | number | no | Longitude (WGS84), with `lat`. |
| `timezone` | query | string | no | IANA timezone for local times. Default: the city's, or the nearest city's for a point. |
| `start` | query | string | yes | First day, YYYY-MM-DD. |
| `end` | query | string | yes | Last day, YYYY-MM-DD. |

**Example**

```bash
curl "https://api.servicebox.io/v1/weather-history/days?start=<start>&end=<end>" \
  -H "Authorization: Bearer $SBX_API_KEY"
```

### GET /v1/weather-history/degree-days

**Heating and cooling degree days**

Heating degree days (below `heatingBase`, default 18 °C) and cooling degree days (above `coolingBase`, default 22 °C) from the daily mean temperature over `start`–`end` (at most 366 days), in total (`meta`) and per month.

**Credits:** 1 per call

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `cityId` | query | string | no | A city id from the Cities API, e.g. 745044 (İstanbul). |
| `lat` | query | number | no | Latitude (WGS84), with `lon`. |
| `lon` | query | number | no | Longitude (WGS84), with `lat`. |
| `timezone` | query | string | no | IANA timezone for local times. Default: the city's, or the nearest city's for a point. |
| `start` | query | string | yes | First day, YYYY-MM-DD. |
| `end` | query | string | yes | Last day, YYYY-MM-DD. |
| `heatingBase` | query | number | no | °C, -10 to 40. |
| `coolingBase` | query | number | no | °C, -10 to 40. |

**Example**

```bash
curl "https://api.servicebox.io/v1/weather-history/degree-days?start=<start>&end=<end>" \
  -H "Authorization: Bearer $SBX_API_KEY"
```

### GET /v1/weather-history/hours

**Hourly history**

Hourly temperature, precipitation, humidity and wind for `start`–`end` (at most 7 days), from 2001-01-01, in local time.

**Credits:** 1 per call

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `cityId` | query | string | no | A city id from the Cities API, e.g. 745044 (İstanbul). |
| `lat` | query | number | no | Latitude (WGS84), with `lon`. |
| `lon` | query | number | no | Longitude (WGS84), with `lat`. |
| `timezone` | query | string | no | IANA timezone for local times. Default: the city's, or the nearest city's for a point. |
| `start` | query | string | yes | First day, YYYY-MM-DD. |
| `end` | query | string | yes | Last day, YYYY-MM-DD. |

**Example**

```bash
curl "https://api.servicebox.io/v1/weather-history/hours?start=<start>&end=<end>" \
  -H "Authorization: Bearer $SBX_API_KEY"
```

### GET /v1/weather-history/normals

**Monthly normals**

The climate normals for each month over NASA POWER's 20-year climatology (2001–2020): mean temperature, the highest and lowest hourly temperature seen in that month, monthly precipitation, humidity and wind.

**Credits:** 1 per call

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `cityId` | query | string | no | A city id from the Cities API, e.g. 745044 (İstanbul). |
| `lat` | query | number | no | Latitude (WGS84), with `lon`. |
| `lon` | query | number | no | Longitude (WGS84), with `lat`. |
| `timezone` | query | string | no | IANA timezone for local times. Default: the city's, or the nearest city's for a point. |

**Example**

```bash
curl "https://api.servicebox.io/v1/weather-history/normals" \
  -H "Authorization: Bearer $SBX_API_KEY"
```

### GET /v1/weather-history/parameters

**List parameters**

The variables the history answers carry, their units, and the dates the data covers. Free.

**Credits:** free (0 credits per call)

No parameters.

**Example**

```bash
curl "https://api.servicebox.io/v1/weather-history/parameters" \
  -H "Authorization: Bearer $SBX_API_KEY"
```

## Errors

Errors are RFC 9457 `application/problem+json` bodies with a machine-readable `type`.

- `401` — the key is missing, unknown, expired or revoked.
- `402` — not enough credits: the body carries `credits_required` and `upgrade_url` (https://servicebox.io/en/pricing).
- `403` — the key is not allowed to call this API.
- `429` — rate limited: wait `retry_after` seconds (also sent as the `Retry-After` header); `upgrade_url` points to a larger plan.

## Links

- OpenAPI document: https://api.servicebox.io/v1/weather-history/openapi.json
- Pricing: https://servicebox.io/en/pricing?api=SBX-WHIST
- API page: https://servicebox.io/en/apis/weather-history