Migration from Webcams API 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}"

Tokens

In V3, the Webcams API returns image URLs secured with tokens. These tokens have an expiration time: 10 minutes for the free API tier and 24 hours for the professional API tier. Once a token expires, the image URL will yield an HTTP 401 error. To maintain consistent access, it's advised to invoke /webcams/api/v3/webcams or /webcams/api/v3/webcams/{webcamId} every time a page loads.

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

{
  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

{
  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
  };
};

Shared query params

Result parts

This parameter specifies which parts are included in the result. It has a similar role in both V2 and V3, but with different names and parts:

Result translation

This parameter specifies the desired language for result translation:

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 continents

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

Get List of continents in V2

In V2, the list of continents 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 continents)
    limit: number; // specified limit of webacams (no need for continents)
    total: number; // total number of webcams based on specified filters (no need for continents)
    continents: [
      {
        id: string; // Continent geo code
        name: string; // Translated continent name
        count: number; // Number of webcams located in the continent
      }
    ];
  };
};

Get List of continents in V3

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

[
  {
    code: string; // Continent geo code
    name: string; // Translated continent 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
  }
  ...
]

List of regions

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

Get list of regions in V2

In V2, the list of regions 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 regions)
    limit: number; // specified limit of webacms (no need for regions)
    total: number; // total number of webcams based on specified filters (no need for regions)
    regions: [
      {
        id: string; // Region geo code
        name: string; // Translated region name
        count: number; // Number of webcams located in the region
      }
      ...
    ];
  };
};

Get list of regions in V3

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

[
  {
    code: string; // Region geo code
    name: string; // Translated region 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 list of the webcams

Endpoints

V2 endpoints:

https://api.windy.com/api/webcams/v2/list/{filter}/.../{filter}?{modifier}&...&{modifier}

V3 endpoints:

https://api.windy.com/webcams/api/v3/webcams?{filter|modifier}&...&{filter|modifier}

Filters

Filter by Category

Specify one or more categories. Multiple categories are used with an AND logic.

Category Filter Operation (V3 only)

Can only be used with the category filter in V3.
Specify category operation (and or or) when using the category filter.

Filter by Continent

Specify one or more continents. Multiple continents are used with an OR logic.

Filter by Country

Specify one or more countries. Multiple countries are used with an OR logic.

Filter by Region

Specify one or more regions. Multiple regions are used with an OR logic.

Filter by Property (V2 only)

In V3, this filter was removed.

• HD: To check for HD webcams in V3, you can inspect the images.sizes.full ratio of the webcam image on the client side.

• Live: To determine if a webcam is live in V3, you can check if the player.live attribute exists on the webcam object on the client side.

Filter by Nearby location

Filter by Bounding Box

Exclude by Webcam IDs (V2 only)

Filter webcams without specific webcam IDs.
Note that this filter is removed in V3 and can be managed on the client side.

Get Webcams by Webcam IDs

Result modifiers

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

Sorting

Sorting Keys (Sorting)

V2 Sorting keys:

• popularity
• hotness (removed in V3)
• new (renamed to createdOn in V3)
• recent (removed in V3)
• random (removed in V3)
• distance (removed in V3, only used for nearby filter)

V3 Sorting keys:

• popularity (desc means the most popular)
• createdOn (desc means newest)

Sorting by Key

In V3, the sortDirection was moved to its own query parameter

Sorting direction (V3 only)

A new query parameter introduced in V3.
Can be used only if the sortKey filter is applied.

Pagination

Limit

In V3, the offset was moved to its own query parameter.

Offset (V3 only)

A new query parameter introduced in V3. Offset can be used without specifying the limit parameter, in which case the default limit will be applied.

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:

{
  total: number; // Number of webcams matching specified  filters
  webcams: WebcamV3Schema[];
}

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: