Migration from Webcams API Version V2 to V3

Authorization

Both V2 and V3 require an API_KEY obtained from the API key manager However, note that in V3, the API key Header was renamed from X-WINDY-KEY to X-WINDY-API-KEY.

Authorization in V2

In V2, there were two methods to send keys:

• As a header: "X-WINDY-KEY": "{YOUR_API_KEY}"
• As a query parameter: ?key={YOUR_API_KEY}

Authorization in V3

In V3, the only method to send the key is as a header:

• "X-WINDY-API-KEY": "{YOUR_API_KEY}"

Webcam result schema

The structure of the webcam information has been modified from V2 to V3, impacting the naming conventions and presence of specific components. In the following section, we will outline these differences:

Webcam parts in V2

In V2, the webcam schema had these parts:

• category (renamed to categories in V3)
• image (renamed to images in V3)
• location
• map (removed in V3)
• player
• property (removed in V3)
• statistics (removed in V3)
• url (renamed to urls in V3)
• user (removed in V3)

Webcam parts in V3

In V3, the webcam schema is structured with these parts:

• categories (renamed from category)
• images (renamed from image)
• location
• player
• urls (renamed from url)

Webcam schema in V2

WebcamV2Schema = {
    "id": string,
    "status": "active"|"inactive",
    "title": string, // Translated title
    "category": [
        {
            "id": string, // Category id
            "name": string, // Translated category name
            "count": number // Number of webcams containing this category
        },
        ...
    ],
    "image": {
        "current": {
            "icon": string, // Image URL for the current image
            ... // All other URLs for available sizes
        },
        "daylight": {}, // Same as the current part, but for daylight images
        "sizes": {
            "icon": {
                "width": number, // Width of the returned image
                "height": number // Height of the returned image
            },
            ... // All other available sizes
        },
        "update": 1692254633
    },
    "location": {
        "city": string, // Translated city name
        "region": string, // Translated region name
        "region_code": string, // Region geo code 
        "country": string, // Translated country name
        "country_code": string, // Country geo code
        "continent": string, // Translated continent name
        "continent_code": string, // Continent geo code
        "latitude": number, // Latitude webcam coordinate
        "longitude": number, // longitude webcam coordinate
        "timezone": string, // Timezone of the webcam
        "wikipedia": string // Link to wikipedia description of the position
    },
    "map": {
        "clustersize": number // Number of webcams under the returned webcam using `map` endpoint
    },
    "player": {
        "live": {
            "available": boolean, // Specify if live stream is available
            "embed": string // Link of the embed with specified timespan used for iframe
        },
        "day": {
            "available": boolean, // Specify if timespan is available
            "link": string, // Windy webcam detail URL
            "embed": string // Link of the embed used for iframe
        },
        ... // same for month/year/lifetime
    },
    "property": [
        {
            "id": string, // Property id
            "name": string, // Translated property name
            "count": number // Number of webcams including specified property
        },
        ...
    ],
    "statistics": {
        "views": number // Number of views
    },
    "url": {
        "current": {
            "desktop": string, // Windy webcam detail URL
            "mobile": string // Windy webcam detail URL (same as for mobile)
        },
        "daylight": {...} // same as current
        "edit": string, // Windy webcam edit page ULR
    },
    "user": {
        "id": string, // Owner user id
        "name": string, // Owner username
        "url": string // Windy webcam detail URL
    }
}

Webcam schema in V3

WebcamV3Schema = {
    "webcamId": number,
    "status": "active"|"inactive",
    "title": string, // Translated title
    "viewCount": number, // Number of views
    "lastUpdatedOn": "2023-08-17T06:43:53.000Z",
    "clusterSize": number, // Number of webcams under the returned webcam using `/webcams/api/v3/map/clusters` endpoint
    "categories": [
        {
            "id": string, // Category id
            "name": string // Translated category
        },
        ...
    ],
    "images": {
        "current": {
            "icon": string, // image URL for current image
            ... // all other URLs for available sizes                
            // free: only small sizes
            // professional: all sizes
        },
        "daylight": {}, // same as current but for daylight images
        "sizes": {
            "icon": {
                "width": number, // width of returned image
                "height": number // height of returned image
            },
            ... // all other available sizes
            // free: only small sizes
            // professional: all sizes
        }
    },
    "location": {
        "city": string, // Translated city name
        "region": string, // Translated region name
        "region_code": string, // Region geo code 
        "country": string, // Translated country name
        "country_code": string, // Country geo code
        "continent": string, // Translated continent name
        "continent_code": string, // Continent geo code
        "latitude": number, // Latitude webcam coordinate
        "longitude": number // longitude webcam coordinate
    },
    "player": {
        "day": string, // Link of the embed used for iframe
        ... // Links for all other available timespans month/year/lifetime/live
    },
    "urls": {
        "detail": string, // Windy webcam detail URL
        "edit": string // Windy webcam edit URL
    }
}

List of categories

The list of categories has its own endpoint in V3 and can be affected by the optional lang query parameter for translation.

Get List of categories in V2

In V2, the list of categories was part of the old /api/webcams/v2/list endpoint, influenced by the show query parameter

{
    "status": "OK",
    "result": {
        "offset": number, // specified offset used for webcams (no need for categories)
        "limit": number, // specified limit of webacms (no need for categories)
        "total": number,// total number of webcams based on specified filters (no need for categories)
        "categories": [
            {
                "id": string, // Category id
                "name": string, // Translated category name
                "count": number // Number of webcams contain specified category
            },
        ]
    }
}

Get List of categories in V3

In V3, use the new endpoint /webcams/api/v3/categories

[
    {
        "id": string, // Category id
        "name": string // Translated category name
    },
    ...,
]

List of countries

The list of countries has its own endpoint in V3 and can be affected by the optional lang query parameter for translation.

Get List of countries in V2

In V2, the list of countries was part of the old /api/webcams/v2/list endpoint, influenced by theshow query parameter

{
    "status": "OK",
    "result": {
        "offset": number, // specified offset used for webcams (no need for countries)
        "limit": number, // specified limit of webacms (no need for countries)
        "total": number,// total number of webcams based on specified filters (no need for countries)
        "countries": [
            {
                "id": string, // Country geo code
                "name": string, // Translated country name
                "count": number // Number of webcams located in the country
            },
            ...
        ]
    }
}

Get List of countries in V3

In V3, use the new endpoint /webcams/api/v3/countries

[
    {
        "code": string, // Country geo code
        "name": string // Translated country name
    },
    ...
]

Get a Single Webcam by Webcam ID (V3 only)

Endpoint

V3 Endpoint:

/webcams/api/v3/webcams/{webamId}?{filter|modifier}&...&{filter|modifier}

Result modifiers

• Webcam result parts (Shared result parts query param)
• Webcam result translation (Shared language query param)

Example

V3 Example URL: https://api.windy.com/webcams/api/v3/webcams/1358084658?include=categories,images,location,player,urls&lang=en

Result

Get Webcams for Map based on Coordinates

In V3, the maximum range of the bounding box is determined by the selected zoom level. Specifically, at the highest zoom level (level 4), the difference in latitude is limited to 22.5 degrees, while the difference in longitude cannot exceed 45 degrees. Each subsequent lower zoom level reduces this limit by a factor of 2. This change aligns with the Google tile system.

Endpoints

V2 Endpoint:

/api/webcams/v2/map/{north_latitude},{east_longitude},{south_latitude},{west_longitude},{zoom}

V3 Endpoint:

/webcams/api/v3/map/clusters?northLat={north_latitude}&eastLon={east_longitude}&southLat={south_latitude}&westLon={west_longitude}&zoom={zoom}

Result modifiers

• Webcam result parts (Shared result parts query param)
• Webcam result translation (Shared language query param)

Examples

V2 Example URL:

https://api.windy.com/api/webcams/v2/map/55.776,22.500,40.979,0,4?show=webcams:category,image,location,map,player,property,statistics,url,user&lang=en

V3 Example URL:

https://api.windy.com/webcams/api/v3/map/clusters?northLat=55.776&eastLon=22.500&southLat=40.979&westLon=0&zoom=4&include=categories,images,location,player,urls&lang=en

Results

V2 Resulting JSON Schema:

{
    "status": string,
    "result": {
        "offset": number, // Specified offset
        "limit": number, // Specified limit
        "total": number, // Number of webcams matching specified  filters
        "webcams": WebcamV2Schema[]
    }
}

V3 Resulting JSON Schema: