# OpenWeather

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

> Global weather data — current conditions, 5-day forecasts, hourly forecasts, air quality index with pollutants, geocoding, and One Call 3.0 with full weather suite and government alerts.

**Category:** Data / Weather | **Website:** [openweathermap.org](https://openweathermap.org) | **Docs:** [openweathermap.org/api](https://openweathermap.org/api)

## Access Methods

| Method | Base URL | Auth |
|--------|----------|------|
| **MPP (Tempo)** | `https://openweather.mpp.paywithlocus.com/openweather/` | HTTP 402 auto-payment |
| **Wrapped API** | `https://beta-api.paywithlocus.com/api/wrapped/openweather/` | `Authorization: Bearer <LOCUS_API_KEY>` |

**OpenAPI discovery:** `GET https://openweather.mpp.paywithlocus.com/openapi.json`

## Endpoints

### Current Weather

Get current weather conditions for any location by latitude/longitude — temperature, feels_like, humidity, pressure, wind, clouds, visibility, and weather description.

**Estimated cost:** $0.003 + $0.003 fee

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `lat` | number | Yes | Latitude (-90 to 90) |
| `lon` | number | Yes | Longitude (-180 to 180) |
| `units` | string | No | Units: standard (Kelvin), metric (Celsius), imperial (Fahrenheit). Default: standard |
| `lang` | string | No | Language code for descriptions (e.g. en, es, fr, de, zh_cn) |

```bash
curl -X POST https://openweather.mpp.paywithlocus.com/openweather/current-weather \
  -H "Content-Type: application/json" \
  -d '{"lat":"<number>","lon":"<number>","units":"<string>","lang":"<string>"}'
```

### 5-Day Forecast

Get 5-day weather forecast with 3-hour step — up to 40 timestamps with temperature, precipitation probability, wind, clouds, and weather conditions.

**Estimated cost:** $0.005 + $0.003 fee

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `lat` | number | Yes | Latitude (-90 to 90) |
| `lon` | number | Yes | Longitude (-180 to 180) |
| `cnt` | number | No | Number of timestamps to return (1–40). Default: all 40 |
| `units` | string | No | Units: standard, metric, imperial. Default: standard |
| `lang` | string | No | Language code for descriptions |

```bash
curl -X POST https://openweather.mpp.paywithlocus.com/openweather/forecast-5day \
  -H "Content-Type: application/json" \
  -d '{"lat":"<number>","lon":"<number>","cnt":"<number>","units":"<string>","lang":"<string>"}'
```

### Air Quality

Get current Air Quality Index (AQI 1–5: Good→Very Poor) and concentrations of CO, NO, NO2, O3, SO2, PM2.5, PM10, and NH3 for any location.

**Estimated cost:** $0.003 + $0.003 fee

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `lat` | number | Yes | Latitude (-90 to 90) |
| `lon` | number | Yes | Longitude (-180 to 180) |

```bash
curl -X POST https://openweather.mpp.paywithlocus.com/openweather/air-quality \
  -H "Content-Type: application/json" \
  -d '{"lat":"<number>","lon":"<number>"}'
```

### Geocode

Convert a city name, state, or country into geographic coordinates (lat/lon). Returns up to 5 matching locations with country codes.

**Estimated cost:** $0.002 + $0.003 fee

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `q` | string | Yes | City name, optionally with state and country code (e.g. "London,GB", "Paris,FR", "Austin,TX,US") |
| `limit` | number | No | Max number of results (1–5). Default: 5 |

```bash
curl -X POST https://openweather.mpp.paywithlocus.com/openweather/geocode \
  -H "Content-Type: application/json" \
  -d '{"q":"<string>","limit":"<number>"}'
```

### Reverse Geocode

Convert geographic coordinates (lat/lon) into location names — city, state, and country.

**Estimated cost:** $0.002 + $0.003 fee

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `lat` | number | Yes | Latitude (-90 to 90) |
| `lon` | number | Yes | Longitude (-180 to 180) |
| `limit` | number | No | Max number of results (1–5). Default: 5 |

```bash
curl -X POST https://openweather.mpp.paywithlocus.com/openweather/reverse-geocode \
  -H "Content-Type: application/json" \
  -d '{"lat":"<number>","lon":"<number>","limit":"<number>"}'
```

### One Call — Full Forecast

Full weather suite in one call: current conditions, minute-by-minute forecast (1h), hourly forecast (48h), daily forecast (8 days), and government weather alerts. Requires One Call 3.0 subscription.

**Estimated cost:** $0.007 + $0.003 fee

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `lat` | number | Yes | Latitude (-90 to 90) |
| `lon` | number | Yes | Longitude (-180 to 180) |
| `exclude` | string | No | Comma-separated sections to exclude: current, minutely, hourly, daily, alerts |
| `units` | string | No | Units: standard, metric, imperial. Default: standard |
| `lang` | string | No | Language code for descriptions |

```bash
curl -X POST https://openweather.mpp.paywithlocus.com/openweather/onecall \
  -H "Content-Type: application/json" \
  -d '{"lat":"<number>","lon":"<number>","exclude":"<string>","units":"<string>","lang":"<string>"}'
```

### Weather Overview

AI-generated human-readable weather summary for today or tomorrow — describes current conditions, temperature, wind, humidity, UV, and precipitation in natural language. Requires One Call 3.0 subscription.

**Estimated cost:** $0.007 + $0.003 fee

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `lat` | number | Yes | Latitude (-90 to 90) |
| `lon` | number | Yes | Longitude (-180 to 180) |
| `date` | string | No | Date in YYYY-MM-DD format. Available for today and tomorrow. Defaults to today. |
| `units` | string | No | Units: standard, metric, imperial. Default: standard |

```bash
curl -X POST https://openweather.mpp.paywithlocus.com/openweather/weather-overview \
  -H "Content-Type: application/json" \
  -d '{"lat":"<number>","lon":"<number>","date":"<string>","units":"<string>"}'
```