Airpult API

Webcams

Search, filter, and display live webcam imagery from locations worldwide.

Overview

The Webcams API provides access to a global catalog of live webcams. You can search and filter webcams by location, retrieve snapshot history, display map clusters, and embed an interactive snapshot player on your site.

All endpoints require API key authentication except the embed player, which uses a short-lived token.

Authentication

Most webcam endpoints are protected by API key authentication, passed as a query parameter or header (the same method used across all Airpult API endpoints).

The clusters endpoint accepts either an API key or an auth token. The embed player requires a webcam-specific token, which is included in the detail response for each webcam.

List webcams

Search and filter webcams with optional geographic constraints.

GET /webcams

Parameters

Parameter Required Default Description
bbox No — Bounding box filter: min_lat,min_lng,max_lat,max_lng
nearby No — Proximity filter: lat,lng,radius_km
country No — ISO 3166-1 alpha-2 country code (e.g. AT, CH, US)
location No — Filter by location public ID
limit No 50 Maximum results per page (max 200)
offset No 0 Number of results to skip for pagination
sort No views Sort order: views (most viewed first), views_asc (least viewed first)

Example Request

GET /webcams?country=CH&limit=2

Example Response

{
  "results": [
    {
      "public_id": "abc123",
      "name": "Zürich Bellevue",
      "latitude": 47.3667,
      "longitude": 8.5451,
      "location_public_id": "3704415940",
      "location_name": "Zürich",
      "country_code": "CH",
      "views": 4821,
      "image": {
        "current": "https://cdn.airpult.com/webcams/snapshots/abc123/latest.jpg?sig=..."
      }
    }
  ],
  "count": 1,
  "total": 47
}

Webcam detail

Retrieve a single webcam by its public ID. The response includes a signed embed player URL.

GET /webcams/{public_id}

Example Request

GET /webcams/abc123

Example Response

{
  "public_id": "abc123",
  "name": "Zürich Bellevue",
  "latitude": 47.3667,
  "longitude": 8.5451,
  "location_public_id": "3704415940",
  "location_name": "Zürich",
  "country_code": "CH",
  "last_updated": "2026-04-09T12:30:00Z",
  "views": 4821,
  "image": {
    "current": "https://cdn.airpult.com/webcams/snapshots/abc123/latest.jpg?sig=..."
  },
  "player": {
    "embed": "https://data.airpult.com/webcams/embed/abc123?token=...",
    "expires_in": 3600
  }
}

The player.embed URL can be used in an <iframe> to display the interactive snapshot player. The token expires after 1 hour (expires_in is in seconds).

Response Fields

Field Type Description
public_id string Unique webcam identifier
name string Webcam name
latitude float Latitude
longitude float Longitude
location_public_id string Public ID of the associated location
location_name string Name of the associated location
country_code string ISO 3166-1 alpha-2 country code
last_updated string ISO 8601 timestamp of the most recent snapshot (detail endpoint only)
views integer Total view count
image.current string Signed URL to the latest snapshot image
player.embed string Signed URL to the embeddable HTML player (detail endpoint only)
player.expires_in integer Token validity in seconds (detail endpoint only)

Map clusters

Retrieve webcam clusters for a map view. Webcams are grouped into grid cells based on the zoom level, which reduces the number of markers at low zoom levels.

This endpoint accepts either an API key or an auth token. To avoid exposing your API key in client-side code, generate a token first and pass it to the clusters endpoint.

Generate a token

POST /webcams/token

This endpoint requires API key authentication. It returns a token valid for 1 hour.

Example Response

{
  "token": "dG9rZW4tc2lnbmF0dXJl.1712678400",
  "expires_in": 3600
}

Fetch clusters

GET /webcams/clusters?bbox={bbox}&zoom={zoom}&token={token}

Parameters

Parameter Required Default Description
bbox Yes — Bounding box: min_lat,min_lng,max_lat,max_lng
zoom Yes — Map zoom level (1–18)
token No — Auth token from POST /webcams/token. Either token or api_key is required.
api_key No — API key (alternative to token)

Example Request

GET /webcams/clusters?bbox=46.0,6.0,48.0,10.0&zoom=8&token=dG9rZW4tc2lnbmF0dXJl.1712678400

Example Response

{
  "clusters": [
    {
      "latitude": 47.367,
      "longitude": 8.545,
      "count": 1,
      "webcam": {
        "public_id": "abc123",
        "name": "Zürich Bellevue",
        "latitude": 47.3667,
        "longitude": 8.5451,
        "location_public_id": "3704415940",
        "location_name": "Zürich",
        "country_code": "CH",
        "views": 4821,
        "image": {
          "current": "https://cdn.airpult.com/webcams/snapshots/abc123/latest.jpg?sig=..."
        }
      }
    },
    {
      "latitude": 46.948,
      "longitude": 7.438,
      "count": 5
    }
  ],
  "count": 2
}

When a cluster contains a single webcam, the full webcam object is included. When a cluster contains multiple webcams, only the centroid coordinates and count are returned.

Token flow

A typical integration for map-based webcam display:

  1. Your server calls POST /webcams/token with the API key to obtain a token.
  2. Pass the token to your client-side code.
  3. The client calls GET /webcams/clusters with the token as the user pans and zooms.
  4. When the token nears expiry (check expires_in), request a new one from your server.

This keeps the API key on your server and out of client-side requests.

Snapshot history

Retrieve historical snapshots for a webcam.

GET /webcams/{public_id}/snapshots

Parameters

Parameter Required Default Description
range No 24h Time range: 24h (all snapshots from the last 24 hours) or 30d (one snapshot per day, closest to local noon, for the last 30 days)

Example Request

GET /webcams/abc123/snapshots?range=24h

Example Response

{
  "snapshots": [
    {
      "captured_at": "2026-04-09T12:30:00Z",
      "image_url": "https://cdn.airpult.com/webcams/snapshots/abc123/1712666200.jpg?sig=..."
    },
    {
      "captured_at": "2026-04-09T12:00:00Z",
      "image_url": "https://cdn.airpult.com/webcams/snapshots/abc123/1712664400.jpg?sig=..."
    }
  ],
  "count": 2
}

Snapshot Fields

Field Type Description
captured_at string ISO 8601 timestamp of when the snapshot was taken
image_url string Signed URL to the snapshot image

Embed player

A self-contained HTML page that displays an interactive snapshot player for a webcam. Designed to be loaded in an <iframe>.

GET /webcams/embed/{public_id}?token={token}

The embed URL (including a valid token) is provided in the player.embed field of the webcam detail response. You do not need to construct this URL manually.

Parameters

Parameter Required Default Description
token Yes — Webcam-specific token (provided in the detail response)
range No 24h Snapshot range: 24h or 30d

Features

  • Timeline slider to browse snapshots
  • Play/pause button for automatic playback
  • Relative time labels (e.g. “2h ago”)
  • Dark theme, responsive layout

Example Usage

<iframe
  src="https://data.airpult.com/webcams/embed/abc123?token=..."
  width="640"
  height="480"
  frameborder="0"
  allowfullscreen>
</iframe>

Errors

Status Description
400 Invalid parameters (e.g. malformed bounding box)
403 Invalid API key, or invalid/expired token (embed and clusters endpoints)
404 Webcam not found
429 Rate limit exceeded
503 Webcam data not loaded

Confirm