> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coreflux.org/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenWeatherMap REST API

> Client-mode REST API connector for current weather, forecast, geocoding, air pollution, and One Call

Technical Preview

## Overview

[OpenWeatherMap](https://openweathermap.org/api) supplies current conditions, a 5-day forecast, geocoding, air pollution, and One Call 3.0. This connector is the expanded form of the weather client example on [REST API Connectors](/latest/lot-language/routes/rest-api-routes): `BASE_ADDRESS` is `https://api.openweathermap.org` and the key travels as the `appid` query parameter.

> [!NOTE]
>
> A call without a valid `appid` returns HTTP 401 (`Invalid API key`). This template has not been verified with a live key. Create a free key in the OpenWeatherMap dashboard and pass it only at runtime.

## Basic Syntax

```lot wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
# Coreflux REST_API template — OpenWeatherMap
# Generated from OpenAPI; credentials are placeholders only.
# Docs: https://docs.coreflux.org/latest/lot-language/routes/rest-api-routes

DEFINE ROUTE OpenweathermapRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://api.openweathermap.org"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '30'
        WITH DEFAULT_CONTENT_TYPE "application/json"
        # Auth: pass appid (API key) as query via {value.json.appid} — never hard-code keys.
        # Prefer publishing appid from MQTT JSON, or document GET SECRET for ops that load secrets upstream.
    ADD EVENT Getcurrentweatherbycity
        WITH SOURCE_TOPIC "integrations/openweathermap/request/Getcurrentweatherbycity"
        WITH DESTINATION_TOPIC "integrations/openweathermap/response/Getcurrentweatherbycity"
        WITH METHOD "GET"
        WITH ENDPOINT "/data/2.5/weather?q={value.json.q}&units={value.json.units}&appid={value.json.appid}"
        WITH HEADERS
            ADD "Accept" "application/json"
    ADD EVENT Getcurrentweatherbycoords
        WITH SOURCE_TOPIC "integrations/openweathermap/request/Getcurrentweatherbycoords"
        WITH DESTINATION_TOPIC "integrations/openweathermap/response/Getcurrentweatherbycoords"
        WITH METHOD "GET"
        WITH ENDPOINT "/data/2.5/weather?lat={value.json.lat}&lon={value.json.lon}&units={value.json.units}&appid={value.json.appid}"
        WITH HEADERS
            ADD "Accept" "application/json"
    ADD EVENT Getforecast5Daybycity
        WITH SOURCE_TOPIC "integrations/openweathermap/request/Getforecast5Daybycity"
        WITH DESTINATION_TOPIC "integrations/openweathermap/response/Getforecast5Daybycity"
        WITH METHOD "GET"
        WITH ENDPOINT "/data/2.5/forecast?q={value.json.q}&units={value.json.units}&appid={value.json.appid}"
        WITH HEADERS
            ADD "Accept" "application/json"
    ADD EVENT Getforecast5Daybycoords
        WITH SOURCE_TOPIC "integrations/openweathermap/request/Getforecast5Daybycoords"
        WITH DESTINATION_TOPIC "integrations/openweathermap/response/Getforecast5Daybycoords"
        WITH METHOD "GET"
        WITH ENDPOINT "/data/2.5/forecast?lat={value.json.lat}&lon={value.json.lon}&units={value.json.units}&appid={value.json.appid}"
        WITH HEADERS
            ADD "Accept" "application/json"
    ADD EVENT Geocodedirect
        WITH SOURCE_TOPIC "integrations/openweathermap/request/Geocodedirect"
        WITH DESTINATION_TOPIC "integrations/openweathermap/response/Geocodedirect"
        WITH METHOD "GET"
        WITH ENDPOINT "/geo/1.0/direct?q={value.json.q}&limit={value.json.limit}&appid={value.json.appid}"
        WITH HEADERS
            ADD "Accept" "application/json"
    ADD EVENT Geocodereverse
        WITH SOURCE_TOPIC "integrations/openweathermap/request/Geocodereverse"
        WITH DESTINATION_TOPIC "integrations/openweathermap/response/Geocodereverse"
        WITH METHOD "GET"
        WITH ENDPOINT "/geo/1.0/reverse?lat={value.json.lat}&lon={value.json.lon}&limit={value.json.limit}&appid={value.json.appid}"
        WITH HEADERS
            ADD "Accept" "application/json"
    ADD EVENT Getairpollution
        WITH SOURCE_TOPIC "integrations/openweathermap/request/Getairpollution"
        WITH DESTINATION_TOPIC "integrations/openweathermap/response/Getairpollution"
        WITH METHOD "GET"
        WITH ENDPOINT "/data/2.5/air_pollution?lat={value.json.lat}&lon={value.json.lon}&appid={value.json.appid}"
        WITH HEADERS
            ADD "Accept" "application/json"
    ADD EVENT Getonecall
        WITH SOURCE_TOPIC "integrations/openweathermap/request/Getonecall"
        WITH DESTINATION_TOPIC "integrations/openweathermap/response/Getonecall"
        WITH METHOD "GET"
        WITH ENDPOINT "/data/3.0/onecall?lat={value.json.lat}&lon={value.json.lon}&units={value.json.units}&appid={value.json.appid}"
        WITH HEADERS
            ADD "Accept" "application/json"
```

## Events

| Event | Method | Endpoint | Request topic | Response topic |
| - | - | - | - | - |
| Getcurrentweatherbycity | GET | `/data/2.5/weather?q={value.json.q}&units={value.json.units}&appid={value.json.appid}` | `integrations/openweathermap/request/Getcurrentweatherbycity` | `integrations/openweathermap/response/Getcurrentweatherbycity` |
| Getcurrentweatherbycoords | GET | `/data/2.5/weather?lat={value.json.lat}&lon={value.json.lon}&units={value.json.units}&appid={value.json.appid}` | `integrations/openweathermap/request/Getcurrentweatherbycoords` | `integrations/openweathermap/response/Getcurrentweatherbycoords` |
| Getforecast5Daybycity | GET | `/data/2.5/forecast?q={value.json.q}&units={value.json.units}&appid={value.json.appid}` | `integrations/openweathermap/request/Getforecast5Daybycity` | `integrations/openweathermap/response/Getforecast5Daybycity` |
| Getforecast5Daybycoords | GET | `/data/2.5/forecast?lat={value.json.lat}&lon={value.json.lon}&units={value.json.units}&appid={value.json.appid}` | `integrations/openweathermap/request/Getforecast5Daybycoords` | `integrations/openweathermap/response/Getforecast5Daybycoords` |
| Geocodedirect | GET | `/geo/1.0/direct?q={value.json.q}&limit={value.json.limit}&appid={value.json.appid}` | `integrations/openweathermap/request/Geocodedirect` | `integrations/openweathermap/response/Geocodedirect` |
| Geocodereverse | GET | `/geo/1.0/reverse?lat={value.json.lat}&lon={value.json.lon}&limit={value.json.limit}&appid={value.json.appid}` | `integrations/openweathermap/request/Geocodereverse` | `integrations/openweathermap/response/Geocodereverse` |
| Getairpollution | GET | `/data/2.5/air_pollution?lat={value.json.lat}&lon={value.json.lon}&appid={value.json.appid}` | `integrations/openweathermap/request/Getairpollution` | `integrations/openweathermap/response/Getairpollution` |
| Getonecall | GET | `/data/3.0/onecall?lat={value.json.lat}&lon={value.json.lon}&units={value.json.units}&appid={value.json.appid}` | `integrations/openweathermap/request/Getonecall` | `integrations/openweathermap/response/Getonecall` |

## Auth

OpenWeatherMap uses the **`appid` query parameter**, not a Bearer header.

**appid** `string` *required*

API key. Publish it on the MQTT JSON payload as `appid` (`{value.json.appid}`). Load it from a Hub secret. Never commit the key.

**q** `string`

City name for city endpoints, for example `London`.

**units** `string`

`metric`, `imperial`, or `standard`.

Example payload for current weather by city:

```json theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
{"q": "London", "units": "metric", "appid": "YOUR_OPENWEATHERMAP_KEY"}
```

## Try it

1. Add the connector on a lab broker.
2. Publish the JSON above to `integrations/openweathermap/request/Getcurrentweatherbycity`.
3. Subscribe to `integrations/openweathermap/response/Getcurrentweatherbycity`.
4. Coordinates: publish `lat`, `lon`, `units`, and `appid` to `integrations/openweathermap/request/Getcurrentweatherbycoords`.

> [!NOTE]
>
> A probe of `GET /data/2.5/weather?q=London` with an invalid `appid` returned HTTP 401. `lot_lint` reported no findings on `OpenweathermapRestApi`. That does not replace a call with a real key.

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps](/latest/lot-language/routes/rest-api-apps)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.