# Wunderground — Wrapped API

> **You are on:** `https://api.paywithlocus.com/api` | [llms.txt](https://paywithlocus.com/llms.txt) | [docs](https://docs.paywithlocus.com)
>
> Locus runs on multiple environments -- make sure every URL you call matches your expected environment.
> | Environment | Landing | API | Docs |
> |---|---|---|---|
> | Production | paywithlocus.com | api.paywithlocus.com | docs.paywithlocus.com |
> | Beta | beta.paywithlocus.com | api.beta.paywithlocus.com | docs.paywithlocus.com |
> | Stage | stage.paywithlocus.com | api.stage.paywithlocus.com | docs.paywithlocus.com |
>
> If the API URL above doesn't match your expected environment, re-fetch this file from the correct domain.

> Access real-time weather conditions, multi-day forecasts, and detailed historical weather data from thousands of personal and airport weather stations worldwide. Search and retrieve current observations, hourly history, and monthly records to power your weather applications and analysis.

**Category:** Weather | **Website:** [wunderground.com/](https://wunderground.com/) | **Docs:** [parse.bot/marketplace/31a45835-21fc-4935-987e-a27e25a5a873/wunderground-com-api](https://parse.bot/marketplace/31a45835-21fc-4935-987e-a27e25a5a873/wunderground-com-api)

Pay-per-use API proxy. Each call is automatically billed to your wallet in USDC.

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/parse-wunderground-com-api-31a45835/`
**Auth:** `Authorization: Bearer <LOCUS_API_KEY>`

## Endpoints

### get_airport_temperature_updates_batch

Retrieve newly available TWC airport temperature observations for multiple global airport stations in one incremental batch request. Returns only rows where observed_at_utc is strictly after since_utc and at or before through_utc, supporting causal progressive daily-maximum forecasting. The since_utc to through_utc window must not exceed 30 hours (recovery/bootstrap lookback). Each station is fetched independently — one failed station does not fail the entire batch. Observations are deduplicated by station and observed_at_utc. Returns a next_cursor_utc equal to retrieved_at for the caller to use as since_utc on the next poll. Metric output only. Supports at least 150 stations per request.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `since_utc` | string | Yes | ISO-8601 UTC timestamp. Only observations with observed_at_utc strictly after this value are returned. Supports up to 30-hour lookback from through_utc. |
| `stations` | string | Yes | JSON array of station objects, each with station_id (ICAO code), country_code (two-letter ISO), and timezone_name (IANA). Example: [{"station_id":"KJFK","country_code":"US","timezone_name":"America/New_York"}]. |
| `through_utc` | string | Yes | ISO-8601 UTC timestamp. Upper bound (inclusive) for observations returned. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-wunderground-com-api-31a45835/get_airport_temperature_updates_batch \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"since_utc":"<string>","stations":"<string>","through_utc":"<string>"}'
```

### get_current_weather

Get current weather conditions for a PWS station. Returns the most recent observation including temperature, humidity, wind speed/direction, solar radiation, pressure, precipitation, and UV index. The station_id should be a PWS ID (e.g. ILONDO440) obtainable from the search endpoint's pwsId field.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `station_id` | string | Yes | PWS Station ID (e.g. ILONDO440). Obtain from search endpoint's pwsId field. |
| `units` | string | No | Unit system: 'm' for metric, 'e' for english/imperial. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-wunderground-com-api-31a45835/get_current_weather \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"station_id":"<string>","units":"<string>"}'
```

### get_forecast

Retrieve 7-day daily and 2-day hourly weather forecasts for a latitude/longitude. Daily forecast includes temperature ranges, precipitation, moon/sun times, and narrative summaries with daypart breakdowns. Hourly forecast includes temperature, precipitation chance, wind, UV, and weather phrases. Coordinates can be obtained from the search endpoint.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `lat` | number | Yes | Latitude of the location. |
| `lon` | number | Yes | Longitude of the location. |
| `units` | string | No | Unit system: 'm' for metric, 'e' for english/imperial. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-wunderground-com-api-31a45835/get_forecast \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"lat":"<number>","lon":"<number>","units":"<string>"}'
```

### get_historical_airport

Access historical weather observations for an airport station over a date range. Returns hourly observations enriched with timestamp fields, temperature unit, row type classification, and QC/provenance placeholders. Includes response-level metadata (row count, missing hours, warnings), station metadata, and a daily_summary block with derived and source-published daily temperature maxima. Date range should not exceed 31 days.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `country_code` | string | No | Two-letter ISO country code for the station (e.g. US, GB). |
| `end_date` | string | Yes | End date in YYYYMMDD format. |
| `start_date` | string | Yes | Start date in YYYYMMDD format. |
| `station_id` | string | Yes | Airport station ICAO code (e.g. KJFK, EGLL). Obtain from search endpoint's icaoCode field. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-wunderground-com-api-31a45835/get_historical_airport \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"country_code":"<string>","end_date":"<string>","start_date":"<string>","station_id":"<string>"}'
```

### get_historical_airport_daily_maxima

Retrieve daily temperature maxima for an airport station, grouped by local calendar date in the specified IANA timezone. Uses the same metric observation source as get_historical_airport but returns only compact per-day summaries with max temperature, observation counts, gap analysis, and duplicate detection. DST transitions are handled automatically. Date range should not exceed 31 days.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `country_code` | string | No | Two-letter ISO country code for the station (e.g. FI, US). |
| `end_date` | string | Yes | End date in YYYYMMDD format. |
| `start_date` | string | Yes | Start date in YYYYMMDD format. |
| `station_id` | string | Yes | Airport station ICAO code (e.g. EFHK, KJFK). Obtain from search endpoint's icaoCode field. |
| `timezone_name` | string | Yes | IANA timezone name for local date grouping (e.g. Europe/Helsinki, America/New_York). DST transitions are handled automatically. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-wunderground-com-api-31a45835/get_historical_airport_daily_maxima \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"country_code":"<string>","end_date":"<string>","start_date":"<string>","station_id":"<string>","timezone_name":"<string>"}'
```

### get_historical_airport_temperature_series

Retrieve a complete year-scale airport observation temperature series for settlement calibration. Returns every observation within the requested local-date range (up to 366 days), preserving the full intraday path. Observations are deduplicated by valid_time_gmt, grouped by local calendar date using the specified IANA timezone, and sorted chronologically. Includes compact daily maxima derived from the returned rows. Internally batches requests to the upstream 31-day-limited API.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `country_code` | string | Yes | Two-letter ISO country code for the station (e.g. FI, US). |
| `end_date` | string | Yes | End date in YYYYMMDD format, inclusive local calendar date. |
| `start_date` | string | Yes | Start date in YYYYMMDD format, interpreted as a local calendar date. |
| `station_id` | string | Yes | Airport station ICAO code (e.g. EFHK, KJFK). Obtain from search endpoint's icaoCode field. |
| `timezone_name` | string | Yes | IANA timezone name for local date grouping (e.g. Europe/Helsinki, America/New_York). DST transitions are handled automatically. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-wunderground-com-api-31a45835/get_historical_airport_temperature_series \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"country_code":"<string>","end_date":"<string>","start_date":"<string>","station_id":"<string>","timezone_name":"<string>"}'
```

### get_monthly_observations

Get all hourly observations for a specific month at an airport station. Internally queries the full date range of the specified month. Returns the same enriched observation format as get_historical_airport with station_metadata, response_metadata, daily_summary, and data_source_note. Useful for bulk historical analysis of a complete calendar month.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `country_code` | string | No | Two-letter ISO country code for the station (e.g. US, GB). |
| `month` | integer | Yes | Month number, 1 through 12. |
| `station_id` | string | Yes | Airport station ICAO code (e.g. KJFK, EGLL). |
| `year` | integer | Yes | Year (e.g. 2024). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-wunderground-com-api-31a45835/get_monthly_observations \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"country_code":"<string>","month":"<integer>","station_id":"<string>","year":"<integer>"}'
```

### get_pws_hourly_history

Retrieve the last 7 days of hourly observations for a PWS station. Includes temperature highs/lows, humidity, wind speed/gusts, solar radiation, UV, dewpoint, and precipitation totals in a metric sub-object. The station_id should be a PWS ID obtainable from the search endpoint's pwsId field.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `station_id` | string | Yes | PWS Station ID (e.g. ILONDO440). Obtain from search endpoint's pwsId field. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-wunderground-com-api-31a45835/get_pws_hourly_history \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"station_id":"<string>"}'
```

### search

Search for locations and weather stations by keyword. Returns matching cities and airports with coordinates, country codes, ICAO codes, PWS IDs, and place identifiers as parallel arrays (one index per location). Use returned station IDs and coordinates as inputs to other endpoints.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `query` | string | Yes | Location search keyword (e.g. London, New York, Tokyo). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-wunderground-com-api-31a45835/search \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"<string>"}'
```

### search_nearby_stations

Search for nearby weather stations within a configurable radius of one or more input locations. Accepts lat/lon coordinates or station IDs (ICAO or PWS). Returns all matching stations sorted by distance, deduplicated across multiple inputs, with each station listing all input locations it is near. The upstream API returns up to 10 nearest stations per product type per input location. When station_type is 'official', only professionally operated stations (METAR, SYNOP, airport with ICAO code) are returned.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `locations` | string | Yes | JSON array of input location objects. Each object has either lat/lon (e.g. {"lat":51.5,"lon":-0.12}) or station_id (e.g. {"station_id":"KJFK"}). ICAO codes and PWS IDs are supported. |
| `radius_km` | number | No | Search radius in kilometres. Stations beyond this distance are excluded. |
| `station_type` | string | No | Filter by station type. Set to 'official' to return only professionally operated stations (airport, METAR, SYNOP). When omitted, all station types are returned including personal weather stations. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-wunderground-com-api-31a45835/search_nearby_stations \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"locations":"<string>","radius_km":"<number>","station_type":"<string>"}'
```