A REST API providing access to the world's largest repository of webcams, with list and detail endpoints filterable by location, category, and country, each webcam carrying preview images, timelapse players, and location metadata. Authenticated with an x-windy-api-key header.
openapi: 3.0.1
info:
title: Windy API
description: >-
The Windy API exposes weather and imagery data from Windy.com across three
products: the Point Forecast API (multi-model numerical weather forecast data
for a coordinate), the Map Forecast API (an embeddable Leaflet-based weather
map library), and the Webcams API (the world's largest webcam repository).
This document models the HTTP/REST surfaces - the Point Forecast endpoint and
the Webcams v3 endpoints. The Map Forecast product is a client-side JavaScript
library and is referenced in the description rather than modeled as REST.
termsOfService: https://account.windy.com/agreements/windy-api-map-and-point-forecast-terms-of-use
contact:
name: Windy API Support
url: https://api.windy.com
version: '3.0'
servers:
- url: https://api.windy.com
description: Windy API production host
paths:
/api/point-forecast/v2:
post:
operationId: getPointForecast
tags:
- Point Forecast
summary: Get a multi-model point forecast for a coordinate.
description: >-
Returns numerical weather, sea, and air-quality forecast data for a
single latitude/longitude across the selected forecast model and
parameters. The API key is passed in the request body.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PointForecastRequest'
responses:
'200':
description: Forecast data for the requested point.
content:
application/json:
schema:
$ref: '#/components/schemas/PointForecastResponse'
'204':
description: No data available for the requested point/model combination.
'400':
description: Bad request - invalid parameters.
'401':
description: Unauthorized - missing or invalid API key.
'429':
description: Too Many Requests - daily session limit exceeded.
/webcams/api/v3/webcams:
get:
operationId: listWebcams
tags:
- Webcams
summary: List and filter webcams.
description: >-
Returns a paginated list of webcams. Results can be filtered by
category, country, continent, region, and bounding box, and enriched
with optional includes such as images, location, player, and urls.
parameters:
- name: lang
in: query
description: Language code for localized strings (e.g. en, de, es).
schema:
type: string
default: en
- name: limit
in: query
description: Maximum number of webcams to return (max 50).
schema:
type: integer
default: 10
maximum: 50
- name: offset
in: query
description: Offset for pagination. Max offset is 1000 (free) or 10000 (professional).
schema:
type: integer
default: 0
- name: categories
in: query
description: Comma-separated list of category slugs to filter by.
schema:
type: string
- name: continents
in: query
description: Comma-separated list of continent codes to filter by.
schema:
type: string
- name: countries
in: query
description: Comma-separated list of ISO country codes to filter by.
schema:
type: string
- name: regions
in: query
description: Comma-separated list of region codes to filter by.
schema:
type: string
- name: nearby
in: query
description: Filter to webcams near a point, as "lat,lon,radius" in km.
schema:
type: string
- name: include
in: query
description: >-
Comma-separated list of detail objects to include in each webcam:
categories, images, location, player, urls.
schema:
type: string
responses:
'200':
description: A list of webcams.
content:
application/json:
schema:
$ref: '#/components/schemas/WebcamList'
'401':
description: Unauthorized - missing or invalid x-windy-api-key.
security:
- WindyApiKey: []
/webcams/api/v3/webcams/{webcamId}:
get:
operationId: getWebcam
tags:
- Webcams
summary: Get a single webcam by ID.
description: Returns details for a single webcam, optionally enriched with include objects.
parameters:
- name: webcamId
in: path
required: true
description: The numeric identifier of the webcam.
schema:
type: integer
- name: lang
in: query
description: Language code for localized strings.
schema:
type: string
default: en
- name: include
in: query
description: >-
Comma-separated list of detail objects to include: categories,
images, location, player, urls.
schema:
type: string
responses:
'200':
description: A single webcam.
content:
application/json:
schema:
$ref: '#/components/schemas/Webcam'
'401':
description: Unauthorized - missing or invalid x-windy-api-key.
'404':
description: Webcam not found.
security:
- WindyApiKey: []
components:
securitySchemes:
WindyApiKey:
type: apiKey
in: header
name: x-windy-api-key
description: Windy Webcams API key, obtained at https://api.windy.com/keys.
schemas:
PointForecastRequest:
type: object
required:
- lat
- lon
- model
- parameters
- key
properties:
lat:
type: number
description: Latitude, rounded to 2 decimal places.
example: 49.809
lon:
type: number
description: Longitude, rounded to 2 decimal places.
example: 16.787
model:
type: string
description: >-
Forecast model. Weather models include arome, iconEu, gfs, namConus,
namHawaii, namAlaska; sea models include gfsWave, iconWave; air-quality
models include cams, camsEu.
example: gfs
parameters:
type: array
description: >-
Requested parameters, e.g. temp, dewpoint, precip, wind, windGust,
cape, ptype, lclouds, mclouds, hclouds, rh, gh, pressure.
items:
type: string
example:
- temp
- wind
- precip
levels:
type: array
description: Geopotential levels. Defaults to ["surface"].
items:
type: string
example:
- surface
key:
type: string
description: Point Forecast API key, obtained at https://api.windy.com/keys.
PointForecastResponse:
type: object
properties:
ts:
type: array
description: Array of UNIX timestamps in milliseconds, one per forecast step.
items:
type: integer
format: int64
units:
type: object
description: Maps each parameter-level key to its measurement unit.
additionalProperties:
type: string
example:
temp-surface: K
wind_u-surface: m*s-1
warning:
type: string
description: Optional warning message returned by the API.
additionalProperties:
type: array
description: >-
Data arrays keyed by "<parameter>-<level>" (e.g. temp-surface,
wind_u-surface, wind_v-surface). Indices align with the ts array;
null indicates missing model data.
items:
type: number
nullable: true
WebcamList:
type: object
properties:
total:
type: integer
description: Total number of webcams matching the query.
webcams:
type: array
items:
$ref: '#/components/schemas/Webcam'
Webcam:
type: object
properties:
webcamId:
type: integer
description: Unique numeric webcam identifier.
title:
type: string
description: Human-readable webcam title.
status:
type: string
description: Webcam status, e.g. active or inactive.
enum:
- active
- inactive
viewCount:
type: integer
description: Total number of views.
lastUpdatedOn:
type: string
format: date-time
description: Timestamp of the last image update.
categories:
type: array
description: Categories assigned to the webcam (when included).
items:
type: object
properties:
id:
type: string
name:
type: string
location:
type: object
description: Geographic location of the webcam (when included).
properties:
city:
type: string
region:
type: string
country:
type: string
continent:
type: string
latitude:
type: number
longitude:
type: number
images:
type: object
description: Preview image URLs (when included). Token-secured, time-limited.
properties:
current:
type: object
properties:
icon:
type: string
format: uri
thumbnail:
type: string
format: uri
preview:
type: string
format: uri
player:
type: object
description: Timelapse player embed URLs (when included).
properties:
day:
type: string
format: uri
month:
type: string
format: uri
year:
type: string
format: uri
urls:
type: object
description: Detail and provider URLs (when included).
properties:
detail:
type: string
format: uri
provider:
type: string
format: uri