Getting started
To get API working, just do these 2 simple steps:
- Obtain your Webcams API key here
-
Send GET request to the URL:
https://api.windy.com/api/webcams/v2/[path]
The API authorization key from the first step can be in the:- request header
"x-windy-key": "your_API_key"
, - or get parameter
?key=your_API_key
- request header
Please make sure to query the Webcams API at least daily in order to benfit from the latest additions and updates, because we add new webcams and we take care that the information about the webcams stay up-to-date.
Reference
- /list
- /list/bbox
- /list/category
- /list/continent
- /list/country
- /list/nearby
- /list/property
- /list/region
- /list/webcam
- /list/exclude
- /list/orderby
- /list/limit
- /map
Response
The response of the API is always in JSON.
First, an example of a summarized response of the API. After this follows a breakdown of the different elements of the response.
{
"status": "OK",
"result": {
"offset": 0,
"limit": 10,
"total": 1,
"webcams": [ ... ],
"categories": [ ... ],
"properties": [ ... ],
"continents": [ ... ],
"countries": [ ... ],
"regions": [ ... ]
}
}
Breakdown of the different elements in a response:
response object
{
"status": "OK",
"result": <result object>
}
Property | Description | ||||||
---|---|---|---|---|---|---|---|
status |
The return status of the API call. Possible values are:
|
||||||
result | The result object. |
result object
{
"offset": 0,
"limit": 10,
"total": 1,
"webcams": [ <webcam object>... ],
"categories": [ <category object>... ],
"properties": [ <property object>... ],
"continents": [ <continent object>... ],
"countries": [ <country object>... ],
"regions": [ <region object>... ]
}
Property | Description |
---|---|
offset | The offset in the list of webcam of the API call. |
limit | The limit of the list |
total | The total number of webcams in the list of this API call. |
webcams | The webcam object. This is only available if webcam is in the value of the show query parameter of the API call. |
categories | An array of category objects. This is only available if categories is in the value of the show query parameter of the API call. |
properties | An array of property objects. This is only available if properties is in the value of the show query parameter of the API call. |
continents | An array of continent objects. This is only available if continents is in the value of the show query parameter of the API call. |
countries | An array of country objects. This is only available if countries is in the value of the show query parameter of the API call. |
regions | An array of region objects. This is only available if regions is in the value of the show query parameter of the API call. |
webcam object
Use the show=webcams query parameter in order to be it part of the response.
{
"id": "1171032474",
"status": "active",
"title": "Zurich › North: Best Carwash − Hardbrücke − Jumbo compact Zürich − Hard One − Abaton − KV Zürich Business School − Escher Wyss",
"category": <webcam.category object>,
"image": <webcam.image object>,
"location": <webcam.location object>,
"map": <webcam.map object>,
"player": <webcam.player object>,
"property": <webcam.property object>,
"statistics": <webcam.statistics object>,
"url": <webcam.url object>,
"user": <webcam.user object>
}
Property | Description |
---|---|
id | The ID of this webcam. You can use this for the webcam and exclude modifier. |
status | The current status of this webcam. Either active or inactive. |
title | The display title of this webcam. |
category | The webcam.category object. This is only available if category is part of the show=webcams: query parameter of the API call. |
image | The webcam.image object. This is only available if image is part of the show=webcams: query parameter of the API call. |
location | The webcam.location object. This is only available if location is part of the show=webcams: query parameter of the API call. |
map | The webcam.map object. This is only available if map is part of the show=webcams: query parameter of the API call. |
player | The webcam.player object. This is only available if player is part of the show=webcams: query parameter of the API call. |
property | The webcam.property object. This is only available if property is part of the show=webcams: query parameter of the API call. |
statistics | The webcam.statistics object. This is only available if statistics is part of the show=webcams: query parameter of the API call. |
url | The webcam.url object. This is only available if url is part of the show=webcams: query parameter of the API call. |
user | The webcam.user object. This is only available if user is part of the show=webcams: query parameter of the API call. |
webcam.category object
This is an array of category objects. Use the show=webcams:category query parameter in order to be it part of the response.
[
<category object>,
...
]
webcam.image object
Use the show=webcams:image query parameter in order to be it part of the response.
{
"current": {
"icon": "https://images.webcams.travel/icon/1171032474.jpg",
"thumbnail": "https://images.webcams.travel/thumbnail/1171032474.jpg",
"preview": "https://images.webcams.travel/preview/1171032474.jpg"
},
"daylight": {
"icon": "https://images.webcams.travel/daylight/icon/1171032474.jpg",
"thumbnail": "https://images.webcams.travel/daylight/thumbnail/1171032474.jpg",
"preview": "https://images.webcams.travel/daylight/preview/1171032474.jpg"
},
"sizes": {
"icon": {
"width": 48,
"height": 48
},
"thumbnail": {
"width": 200,
"height": 112
},
"preview": {
"width": 400,
"height": 224
}
},
"update": 1460123709
}
Property | Description |
---|---|
current | URLs of the most recent icon, thumbnail, and preview image sizes of the webcam. |
daylight | URLs of the last daylight icon, thumbnail, and preview image sizes of the webcam. |
sizes | The sizes of the icon, thumbnail, and preview images in pixel. |
update | UNIX timestamp of the last update of the webcam. |
webcam.location object
Use the show=webcams:location query parameter in order to be it part of the response.
{
"city": "Zurich",
"region": "Zurich",
"region_code": "CH.ZH",
"country": "Switzerland",
"country_code": "CH",
"continent": "Europe",
"continent_code": "EU",
"latitude": 47.36667,
"longitude": 8.55,
"timezone": "Europe/Zurich",
"wikipedia": "https://en.wikipedia.org/wiki/Z%C3%BCrich"
}
Property | Description |
---|---|
city | The localized name of the location. |
region | The localized name of the region. |
region_code | The code for this region. Can be used for the region modifier. |
country | The localized name of the country. |
country_code | The code for this country. Can be used for the country modifier. |
continent | The localized name of the continent. |
continent_code | The code for this continent. Can be used for the continent modifier. |
latitude | The WGS84 latitude of the webcam. |
longitude | The WGS84 longitude of the webcam. |
timezone | The Olson name of the time zone. |
wikipedia | Link to the Wikipedia article about this location. |
webcam.map object
Use the show=webcams:map query parameter in order to be it part of the response.
{
"clustersize": 127
}
Property | Description |
---|---|
clustersize | If used in conjuction with /map, it denotes the number of webcams in the cluster that this webcam represents, otherwise it is always 1. |
webcam.player object
Use the show=webcams:player query parameter in order to be it part of the response. **
{
"live": {
"available": true,
"embed": "https://api.lookr.com/embed/player/1485691420/live"
},
"day": {
"available": true,
"link": "https://www.lookr.com/lookout/1485691420#action-play-day",
"embed": "https://api.lookr.com/embed/player/1485691420/day"
},
"month": {
"available": true,
"link": "https://www.lookr.com/lookout/1485691420#action-play-month",
"embed": "https://api.lookr.com/embed/player/1485691420/month"
},
"year": {
"available": true,
"link": "https://www.lookr.com/lookout/1485691420#action-play-year",
"embed": "https://api.lookr.com/embed/player/1485691420/year"
},
"lifetime": {
"available": true,
"link": "https://www.lookr.com/lookout/1485691420#action-play-lifetime",
"embed": "https://api.lookr.com/embed/player/1485691420/lifetime"
}
}
Property | Description | ||||||
---|---|---|---|---|---|---|---|
live |
Availability and links for the live stream of this webcam.
|
||||||
day |
Availability and links for the day timelapse for this webcam.
|
||||||
month |
Availability and links for the month timelapse for this webcam.
|
||||||
year |
Availability and links for the year timelapse for this webcam.
|
||||||
lifetime |
Availability and links for the lifetime timelapse for this webcam.
|
* Add allowfullscreen="true" to your <iframe> tag to allow the player to go fullscreen
** In order for the player to work properly, please add google.com, pub-4276969157128104, RESELLER, f08c47fec0942fa0 to your ads.txt
webcam.property object
This is an array of property objects. Use the show=webcams:property query parameter in order to be it part of the response.
[
<property object>,
...
]
webcam.statistics object
Use the show=webcams:statistics query parameter in order to be it part of the response.
{
"views": 588150
}
Property | Description |
---|---|
views | How often this webcam has been viewed since it has been added to windy.com. |
webcam.url object
Use the show=webcams:url query parameter in order to be it part of the response.
{
"current": {
"desktop": "http://www.webcams.travel/webcam/1171032474-Weather-Hardbr%C3%BCcke-Zurich",
"mobile": "http://m.webcams.travel/webcam/1171032474-Weather-Hardbr%C3%BCcke-Zurich"
},
"daylight": {
"desktop": "http://www.webcams.travel/webcam/1171032474-Weather-Hardbr%C3%BCcke-Zurich/daylight",
"mobile": "http://m.webcams.travel/webcam/1171032474-Weather-Hardbr%C3%BCcke-Zurich/daylight"
},
"edit": "https://lookr.com/edit/1171032474"
}
Property | Description |
---|---|
current |
Links to the desktop and mobile version of the current view of the webcam. |
daylight |
Links to the desktop and mobile version of the daylight view of the webcam. |
edit | Link for giving feedback to the webcam. |
webcam.user object
Use the show=webcams:user query parameter in order to be it part of the response.
{
"id": "3626",
"name": "ingo",
"url": "http://www.webcams.travel/user/3626"
}
Property | Description |
---|---|
id | The ID of the user. |
name | The display name of the user. |
url | The URL to the user's account. |
category object
Use the show=categories query parameter in order to be it part of the response.
{
"id": "building",
"name": "Building",
"count": 1
}
Property | Description |
---|---|
id | The ID of this category that can be used in the category modifier. |
name | The localized name of this category. |
count | Number of webcam in this category with the given modifiers. |
property object
Use the show=properties query parameter in order to be it part of the response.
{
"id": "hd",
"name": "HD",
"count": 25
}
Property | Description |
---|---|
id | The ID of this property that can be used in the property modifier. |
name | The localized name of this property. |
count | Number of webcam with this property with the given modifiers. |
continent object
Use the show=continents query parameter in order to be it part of the response.
{
"id": "EU",
"name": "Europe",
"count": 23549
}
Property | Description |
---|---|
id | The ID of this continent that can be used in the continent modifier. |
name | The localized name of this continent. |
count | Number of webcam in this continent with the given modifiers. |
country object
Use the show=countries query parameter in order to be it part of the response.
{
"id": "CH",
"name": "Switzerland",
"count": 2077
}
Property | Description |
---|---|
id | The ID of this country that can be used in the country modifier. |
name | The localized name of this country. |
count | Number of webcam in this country with the given modifiers. |
region object
Use the show=regions query parameter in order to be it part of the response.
{
"id": "CH.BE",
"name": "Bern",
"count": 306
}
Property | Description |
---|---|
id | The ID of this region that can be used in the region modifier. |
name | The localized name of this region. |
count | Number of webcam in this region with the given modifiers. |
Query Parameter
These query parameter can be added to any of the API calls and are all optional.
Parameter | Description |
---|---|
show |
The objects to be listed in the response. Possible values are:
Multiple objects must be separated by semicolon (;), e.g. show=webcams:categories;countries. The default is webcams. The webcam object consists of different parts. Possible values are:
Multiple parts must be separated by comma (,), e.g. show=webcams:image,location,player The default is basic and it is always part of the webcam object and can be omitted. Check the Response Object section for a more detailed description. |
lang | Localize the results to this language, if available. The default is English (en), e.g. lang=de |
callback | The name of the callback function in which the JSON response will be encapsulated. This enables JSONP. |
Example
-
/api/webcams/v2/list?show=webcams:image,location;categories&lang=de
The response will contain the webcam and the category objects. The webcam objects will contain the basic, image, and location parts (show=webcams:image,location;categories). Where available, the results will be in German (lang=de).
/list
Returns a list of webcams according to the applied modifiers.
Syntax
/api/webcams/v2/list/{modifier}[/{modifier}...]
Description
Initially, the list contains all webcams. The resulting list of webcams from applying a modifier will be used as input for the following modifier. With every applied modifier, the list of webcams will be narrowed down.
Parameters
Please refer to the description of the various modifiers to learn more about their usage and defaults. The modifiers are:
Explicit modifiers
Modifier | Description |
---|---|
bbox | List of webcams in an area. |
category | List of webcams in a category. |
continent | List of webcams in a continent. |
country | List of webcams in a country. |
nearby | List of webcams around a position. |
property | List of webcams with a certain property. |
region | List of webcams in a region. |
webcam | Explicit list of webcams. |
Implicit modifiers
Modifier | Description |
---|---|
exclude | Exclude specific webcams from a list of webcams. |
orderby | Order the list of webcams. |
limit | Slice the list of webcams. |
Usage
The explicit modifiers are applied in the order as given in the API call. You may apply up to 10 explicit modifiers.
The implicit modifiers are always applied only once in this order and after any given explicit modifier (even if none are given).
If no explicit modifier is given then all available webcams are in the list before applying the implicit modifiers.
Examples
-
/api/webcams/v2/list/nearby=40.11,12.05,5/orderby=distance/limit=20
List the first 20 webcams (limit=20) that are closest to the coordinates (40.11, 12.05) within a radius of 5km (nearby=40.11,12.05,5).
Use case: In your app, list the webcams that are around the current position of a user.
-
/api/webcams/v2/list/category=beach/country=IT/orderby=popularity,desc/limit=20
List the first 20 webcams (limit=20) that are in the category "beach" (category=beach) and in Italy (country=IT), ordered by their popularity (orderby=popularity).
Use case: A directory of the most popular beaches in Italy.
-
/api/webcams/v2/list/nearby=40.11,12.05,5/category=beach/orderby=distance/limit=1
List the closest webcam (orderby=distance and limit=1) to the coordinates (40.11, 12.05) within a radius of 5km (nearby=40.11,12.05,5) and that is in the category "beach" (category=beach).
Use case: Show the webcam of the beach that is closest to the current position of a user of your app.
/list/bbox
Returns the webcams in a bounding box.
Syntax
/api/webcams/v2/list/bbox={ne_lat},{ne_lng},{sw_lat},{sw_lng}
Description
This is a modifier and returns a list of the webcams in the bounding box given by the coordinates of the north-east and south-west corners, i.e. to display webcams in the visible area of a map.
Parameters
Parameter | Requirement | Description |
---|---|---|
ne_lat | required | The WGS84 latitude of the north-east corner of the bounding box. |
ne_lng | required | The WGS84 longitude of the north-east corner of the bounding box. |
sw_lat | required | The WGS84 latitude of the south-west corner of the bounding box. |
sw_lng | required | The WGS84 longitude of the south-west corner of the bounding box. |
Examples
-
/api/webcams/v2/list/bbox=45.900,6.117,40.500,3.624
List the webcams that are in the bounding box with the north-east corner at the coordinates (45.900,6.117) and the south-west corner at the coordinates (40.500,3.624).
Use case: You have a map on your website an want to list all webcams that are in the visible area of the map (together with some more specific criteria given by one or more of the other modifiers).
/list/category
Returns the webcams in a category.
Syntax
/api/webcams/v2/list/category={category}[,{category}...]
Description
This is a modifier and returns a list of webcams according to the listed categories. Multiple categories must be separated by comma.
Parameters
Parameter | Requirement | Description |
---|---|---|
category | required |
A category. To retrieve a list with all available categories with:
The currently defined categories are:
|
Examples
-
/api/webcams/v2/list/category=beach
List the webcams that are in the category "beach".
Use case: It is summer and hot and you want to display webcams that show beaches in your weather app.
/list/continent
Returns the webcams on a continent.
Syntax
/api/webcams/v2/list/continent={continent}[,{continent}...]
Description
This is a modifier and returns a list of webcams according to the listed continents. Multiple continents must be separated by comma.
Parameters
Parameter | Requirement | Description |
---|---|---|
continent | required |
A continent identifier. Retrieve a list with all available
continents with:
|
Examples
-
/api/webcams/v2/list/continent=EU
List the webcams that are in Europe.
Use case: For your trip planning app you want to show all european traffic webcams (together with the modifier category=beach).
/list/country
Returns the webcams in a country.
Syntax
/api/webcams/v2/list/country={country}[,{country}...]
Description
This is a modifier and returns a list of webcams according to the listed country. Multiple countries must be separated by comma.
Parameters
Parameter | Requirement | Description |
---|---|---|
country | required |
An ISO 3166-1-alpha-2 country identifier.
Retrieve a list with all available countries with:
|
Examples
-
/api/webcams/v2/list/country=DE
List the webcams that are in Germany.
Use case: Your website focuses on touristic destinations in Germany and thus you want to display matching webcams from only Germany.
/list/nearby
Returns the webcams near a position within a radius.
Syntax
/api/webcams/v2/list/nearby={lat},{lng},{radius}
Description
This is a modifier and returns a list of webcams near a center point up to a radius, i.e. to display the webcams around a user. The webcams can be ordered by their distance from the center point.
Parameters
Parameter | Requirement | Description |
---|---|---|
lat | required | The WGS84 latitude of the center point. |
lng | required | The WGS84 longitude of the center point. |
radius | required | The radius around the center point in kilometers. The maximum value is 250 |
Examples
-
/api/webcams/v2/list/nearby=40.11,12.05,5
List the webcams that are around the coordinates (40.11,12.05) within the radius of 5km.
Use case: The coordinates are the current position of someone using your app and you want to display all beaches (together with the modifier category=beach) that are nearby.
/list/property
Returns the webcams with a certain property.
Syntax
/api/webcams/v2/list/property={property}[,{property}...]
Description
This is a modifier and returns a list of webcams according to the listed property. Multiple properties must be separated by comma.
Parameters
Parameter | Requirement | Description | ||||||
---|---|---|---|---|---|---|---|---|
property | required |
A property. Possible values for a property are:
|
Examples
-
/api/webcams/v2/list/property=hd
List the webcams that have the property "hd".
Use case: Listing only the webcams that have a high resolution image as special content.
/list/region
Returns the webcams in a region of a country.
Syntax
/api/webcams/v2/list/region={region}[,{region}...]
Description
This is a modifier and returns a list of webcams according to the listed region. Multiple regions must be separated by comma.
Parameters
Parameter | Requirement | Description |
---|---|---|
region | required |
A region identifier. Retrieve a list with all available regions
with:
|
Examples
-
/api/webcams/v2/list/region=CH.ZH
List the webcams that are in the canton of Zürich in Switzerland.
Use case: You run a regional website and want to display the webcams from only this region.
/list/webcam
Returns details of one or more webcams.
Syntax
/api/webcams/v2/list/webcam={webcamid}[,{webcamid}...]
Description
This is a modifier and returns the given webcams. Multiple webcamid must be separated by comma.
Parameters
Parameter | Requirement | Description |
---|---|---|
webcamid | required | The ID of a webcam. The maximum number of allowed IDs is 25. |
Examples
-
/api/webcams/v2/list/webcam=1361879037,1171032474
Show the details of the webcams with the IDs 1361879037 and 1171032474.
Use case: A user of your app bookmarked these webcams and you want to retrieve them for a listing.
/list/exclude
Exclude webcams from the list.
Syntax
/api/webcams/v2/list/exclude={webcamid}[,{webcamid}...]
Description
This is a modifier and excludes the given webcams from the list. Multiple webcamid must be separated by comma. Required at least one webcamid. The maximum number of allowed webcamid is 25.
Parameters
Parameter | Requirement | Description |
---|---|---|
webcamid | required | The ID of a webcam. |
Examples
-
/api/webcams/v2/list/exclude=1171032474
Exclude the webcam with the ID 1171032474 from the results.
Use case: You are currently displaying the webcam with the ID 1171032474 and want to exclude it from an additional listing of the webcams nearby.
/list/orderby
Sort the webcams.
Syntax
/api/webcams/v2/list/orderby={sort}[,{order}]
Description
This is a modifier and sorts the list of webcams according to a criteria.
Parameters
Parameter | Requirement | Description | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
sort | required |
Sort the webcams according to one of these criterias:
|
||||||||||||
order | optional |
The sorting direction. Possible values are:
|
Defaults
If this modifier is not applied, no explicit ordering will be applied.
Examples
-
/api/webcams/v2/list/orderby=popularity,desc
Sort the webcams by their popularity with the most popular webcam first.
Use case: For providing a list of the most popular webcams.
/list/limit
Slice the webcams.
Syntax
/api/webcams/v2/list/limit={limit}[,{offset}]
Description
This is a modifier and returns the list of webcams sliced by limit and offset.
Parameters
Parameter | Requirement | Description |
---|---|---|
limit | required | The number of webcams in the resulting list. The maximum allowed value is 50. |
offset | optional | The offset from where to start listing the webcam for the resulting list. The default value is 0 |
Defaults
If this modifier is not applied, a limit of 10 webcams will be applied.
Examples
-
/api/webcams/v2/list/limit=20,60
List 20 webcams, starting from 60th webcam in the list.
Use case: Pagination
/map
Returns a list of webcams optimized for displaying on a map for a given bounding box and zoom level.
Syntax
/api/webcams/v2/map/{ne_lat},{ne_lng},{sw_lat},{sw_lng},{zoom}
Description
For each zoom level, the returned webcams are arranged in such a way that they are nicely distributed and not too close to each other on the map. The zoom level corresponds to the zoom levels from the Google Maps API.
The number of webcams in the result is limited to 150. The selection of the webcams is based on their popularity. Each webcam in the results represents a cluster of webcams. The number of webcams in each cluster is available in the webcams.map object.
Parameters
Parameter | Requirement | Description |
---|---|---|
ne_lat | required | Latitude (WGS84) of the north-east corner of the bounding box |
ne_lng | required | Longitude (WGS84) of the north-east corner of the bounding box |
sw_lat | required | Latitude (WGS84) of the south-west corner of the bounding box |
sw_lng | required | Longitude (WGS84) of the south-west corner of the bounding box |
zoom | required | Current zoom level of the map, compatible with the Google Maps zoom level. |
Examples
-
/api/webcams/v2/map/45.900,6.117,40.500,3.624,4
For the zoom level of 4, show the webcams that are within the bounding box whose north-east corner has the coordinates (45.900,6.117) and whose south-west corner has the coordinates (40.500,3.624).
Use case: You want to enrich the map that you already have on your website.
Examples
If you just want to jump in, we give you a little walk-through for the API.
Let's list all available webcams:
/api/webcams/v2/list
Woah! That's too much. I'm planning to go to Italy soon, so let's check their webcams by adding the country modifier. A list of all countries can be obtained by calling /api/webcams/v2/list?show=countries.
/api/webcams/v2/list/country=IT
That's still a lot. Can I narrow it down a bit more? What about categories? The show query parameter will help:
/api/webcams/v2/list/country=IT?show=categories
Ahh, very interesting. There are beaches in Italy. Let's check them out by adding the category modifier:
/api/webcams/v2/list/country=IT/category=beach
Cool. However, I want to know which one is the most popular and add the orderby modifier:
/api/webcams/v2/list/country=IT/category=beach/orderby=popularity
We're getting somewhere. I want to see more beaches at once by adding the limit modifier:
/api/webcams/v2/list/country=IT/category=beach/orderby=popularity/limit=20
Good. But I also want to know where these beaches are and how they look like, so I need more information about them. Let's use the show query parameter again:
/api/webcams/v2/list/country=IT/category=beach/orderby=popularity/limit=20?show=webcams:location,image
Very nice! Enough beaches for now. Currently I'm in the swiss mountains and my phone gives me the coordinates 46.54 latitude and 7.98 longitude. What nice places are around me where I could hike to, but not more than 5 kilometer away? Let's check the nearby modifier and some more details with the show query parameter:
/api/webcams/v2/list/nearby=46.54,7.98,5?show=webcams:location,image
Awesome! But hey, everything is in English. If I want ask a local for directions I need to show the details in German. Luckily there's the lang query parameter to change to a different language:
/api/webcams/v2/list/nearby=46.54,7.98,5?show=webcams:location,image&lang=de
Technical support
Drop a line in our Windy API section of our Windy Community forum.
Windy community forum