Skip to content
OpenWebcamDB

API / Documentation

API documentation

How to authenticate, what the API returns, its rate limits and its terms of use. Every endpoint and parameter is listed in the full API reference.

Getting started

1. Create an API key

Create a free account or log in, then create a key on your API keys page. The key is shown once, so store it somewhere safe.

2. Send it with every request

Put the key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

3. Use the base URL

https://openwebcamdb.com/api/v1

4. Make a request

Ten webcams in Belgium, ordered by title:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://openwebcamdb.com/api/v1/webcams?country=belgium&per_page=10"

Endpoints

All endpoints use GET and answer with JSON.

/webcams
Webcams, with the filters below. Paginated.
/webcams/{slug}
One webcam, including its stream URL.
/webcams/random
A random webcam, including its stream URL.
/webcams/popular
Webcams by popularity. Paginated.
/webcams/trending
Webcams with the most views recently. Takes limit (1–100, default 12).
/webcams/recently-viewed
Webcams viewed most recently. Takes limit (1–100, default 12).
/webcams/map
Up to 500 webcams inside a bounding box. Requires lat_min, lat_max, lng_min and lng_max.
/countries
Countries that have webcams, with a count for each.
/countries/{iso_code}
One country and its webcams, by two-letter ISO code (BE). Paginated.
/categories
Kinds of view, with a count for each.
/categories/{slug}
One kind of view and its webcams. Paginated.

Filtering and sorting webcams

/webcams accepts these query parameters:

country
A country’s slug: the last part of its page address on this site, such as belgium.
category
A kind of view’s slug, such as beaches.
search
Text to look for in the title, description or city.
featured
Set to 1 for featured webcams only.
lat_min, lat_max, lng_min, lng_max
A bounding box. Send all four.
sort
title (default), city, views, popularity_score or created_at.
order
asc (default) or desc.
per_page
Results per page, 1 to 100. The default is 20. Use page to move through the pages.

The full API reference lists every endpoint with its parameters and response schema, and lets you try requests in the browser. It’s generated from the code, and also available as an OpenAPI document.

Responses

Paginated lists put the webcams in data, with links and meta for paging. Lists leave out stream_url; request a single webcam to get it.

slug
The webcam’s identifier. Use it to request the webcam.
title, description, city
As shown on the webcam’s page.
stream_type
How the stream is delivered, such as youtube, hls, iframe, mjpeg or image.
stream_url
The stream itself. Only on single-webcam responses.
latitude, longitude
Decimal degrees, as strings with seven decimals.
thumbnail_url
A recent still image, if there is one.
permalink
The webcam’s page on OpenWebcamDB.
country
The country’s name and two-letter ISO code.
categories
The kinds of view, each with a name and slug.

Rate limits

Each account has a limit per minute and a limit per day, set by its plan. Some plans also have a limit per hour. The limits count the requests from all of an account’s API keys together. Compare the plans.

  • Per minute and per hour: counted in fixed windows that start with your first request.
  • Per day: a rolling 24-hour window, not a calendar day. Each request counts for 24 hours after you make it, so your allowance comes back gradually rather than at a set time.
  • Requests that are turned away with a 429 don’t count towards the daily limit.

Headers

Every response that gets past the limits tells you where you stand:

X-RateLimit-Limit
Your daily limit.
X-RateLimit-Remaining
Requests you have left in the rolling 24 hours, after this one.
X-RateLimit-Window
Always 24h-sliding.
X-RateLimit-Limit-Minute
Your limit per minute.
X-RateLimit-Remaining-Minute
Requests left in the current minute.
X-RateLimit-Limit-Hour
Your limit per hour. Only on plans with an hourly limit.
X-RateLimit-Remaining-Hour
Requests left in the current hour. Only on plans with an hourly limit.

When you reach a limit

The API answers with status 429 Too Many Requests. For the minute and hour limits, retry_after says how many seconds to wait: 

{
  "message": "Too many requests. Please try again in 42 seconds.",
  "limit": 60,
  "retry_after": 42
}

For the daily limit, the response shows how many requests you made in the last 24 hours:

{
  "message": "Daily API rate limit exceeded. Please upgrade your plan or wait for your limit to reset.",
  "limit": 100,
  "used": 100,
  "remaining": 0,
  "note": "Limit is based on a rolling 24-hour window"
}

There’s no Retry-After header, so read the response body.

Errors

Errors come back as JSON with a message.

401
The API key is missing or not valid.
403
The API key has been disabled.
404
There’s no webcam, country or category with that identifier.
422
A parameter isn’t valid, such as per_page above 100. The errors field says which one.
429
You’ve reached a rate limit. See above.

Terms of use

The OpenWebcamDB API is free for non-commercial use only. By using it, you agree to these terms.

You may use it for

  • Personal projects and hobby applications
  • Educational and research purposes
  • Non-profit organisations
  • Open-source projects, with attribution

You may not use it for

  • Creating competing webcam directories or aggregators
  • Commercial applications or services that generate revenue
  • Reselling or redistributing API data
  • Illegal activities or anything that breaks applicable laws
  • Harassment, abuse or malicious activities
  • Excessive scraping or data harvesting

For commercial licensing, or if you’re not sure whether your use is allowed, email [email protected].