Skip to main content
API v2.0.0 is now available! We recommend all users migrate to v2 for a better experience. View migration guide.

​
Welcome to API v2.0.0

The AVERT Imagery API v2.0.0 provides streamlined access to volcano imagery data from infrared and visible cameras. This major update unifies the API into a single powerful endpoint with enhanced filtering capabilities. Base URL: https://avert.ldeo.columbia.edu/api/imagery/q

​
Why Upgrade to v2?

Unified Endpoint

Single endpoint for both infrared and visible images - no more separate URLs

Public Image URLs

Returns ready-to-display HTTPS URLs - just plug and play

Advanced Filtering

Filter by fog, clouds, day/night, and temporal frequency

Smart Downloads

Get download estimates before committing to large datasets

​
What’s New in v2.0.0

​
Major Improvements

1. Unified Endpoint
  • One endpoint handles both infrared and visible imagery
  • Switch image types with a simple imageType parameter
  • Consistent response format across all queries
2. Enhanced Filtering 
# Filter by atmospheric conditions
?has_fog=false&has_clouds=false&is_night=false

# Temporal sampling for time-lapse
?freq=hourly  # or daily, minutely

# Sort order control
?order=desc  # newest first (default) or asc (oldest first)
3. Smart Download System 
# Step 1: Get estimate
?download=estimate

# Step 2: Download with confidence
?download=true
4. Improved Pagination
  • Detailed pagination metadata
  • Up to 200 results per page
  • Clear navigation with has_next, has_prev indicators
5. Modern Response Format 
{
  "results": [...],
  "pagination": {
    "page": 1,
    "limit": 100,
    "total_count": 1500,
    "total_pages": 15,
    "has_next": true
  },
  "query": {...}
}
6. Smart Timestamps (v2.0.0)
  • freq=all with single site returns local timestamps (no Z suffix)
  • All other queries return UTC timestamps (with Z suffix)

​
Breaking Changes from v1

v1: Separate endpoints
/api/imagery/infrared/query
/api/imagery/visible/query
v2: Single unified endpoint
/api/imagery/q?imageType=infrared
/api/imagery/q?imageType=visible
v1: search_from, search_tov2: datefrom, dateto (format: yyyymmddhhmmss)
# v1 format
?search_from=2022-10-01T00:00

# v2 format
?datefrom=20221001000000
v1: Array of images
[
  {"image_id": "...", "image_url": "..."},
  ...
]
v2: Structured response with pagination
{
  "results": [...],
  "pagination": {...},
  "query": {...}
}
v1: Fixed 100-image limitv2: Smart downloads with estimates
  • Get size/time estimates first
  • Download all matching results (not just one page)
  • Configurable limits up to 200 per request

​
Quick Start

You can find available endpoints for querying infrared and visible volcano imagery with advanced filters.

​
Basic Query

Get the 20 most recent infrared images: 
curl "https://avert.ldeo.columbia.edu/api/imagery/q?imageType=infrared&limit=20"

​
Filter by Site and Date

Get clear daytime images from Cleveland volcano in November 2025: 
curl "https://avert.ldeo.columbia.edu/api/imagery/q?\
imageType=infrared&\
site=CLNE&\
datefrom=20251101000000&\
dateto=20251130235959&\
is_night=false&\
has_fog=false&\
limit=50"

​
Available Volcanoes and Sites

The API provides access to imagery from multiple volcanic monitoring sites. Available data varies by image type:
Image TypeVolcano IDSite Code(s)Volcano Name
Infrared311240CLNECleveland
Infrared345040VPMIPoás
Infrared383010CV01, CV02Cumbre Vieja
Visible311240CLNECleveland
Visible311290OKCFOkmok
Visible345040VPMIPoás
Use the vnum parameter to filter by volcano ID, or the site parameter to filter by specific camera site code. For example: ?imageType=infrared&vnum=311240 or ?imageType=visible&site=OKCF

​
Key Features

​
Flexible Filtering

Filter images by multiple criteria:
  • Location: Site code or volcano number
  • Time: Date ranges with minute precision
  • Conditions: Fog, clouds, day/night
  • Sampling: All, daily, hourly, or minutely

​
Comprehensive Pagination

Navigate through large datasets efficiently:
  • Configurable page sizes (1-200 results)
  • Clear navigation metadata
  • Total count and page indicators

​
Smart Downloads

Download images with confidence:
  1. Get estimate (size, time, warnings)
  2. Review and confirm
  3. Download as organized ZIP files

​
Transparent Queries

Every response includes your query parameters for easy debugging and logging.

​
Rate Limits

To ensure fair usage and system stability, the API implements rate limiting per IP address:
EndpointRate LimitWindow
/api/imagery/q100 requestsper minute
/health60 requestsper minute
/ (root)100 requestsper minute

​
How Rate Limiting Works

  • Per IP Address: Limits are applied per unique IP address
  • Sliding Window: Resets every minute
  • HTTP 429 Response: When limit exceeded, returns 429 Too Many Requests

​
Rate Limit Response

{
  "error": "Rate limit exceeded: 100 per 1 minute"
}

​
Best Practices

  1. Implement Retry Logic: Wait before retrying when you receive a 429 response
  2. Cache Results: Store frequently accessed data locally
  3. Use Pagination: Don’t request all data at once
  4. Batch Downloads: Use download=true instead of individual image downloads
Implement exponential backoff when retrying failed requests. See our code examples for implementation details.
If you need higher rate limits for legitimate use cases, please contact the AVERT System Team.

​
Authentication

The AVERT Imagery API v2 operates without authentication requirements for public data access. All endpoints are publicly accessible for research and educational purposes.

​
Need Help Migrating?

Check out our comprehensive migration guide for step-by-step instructions on upgrading from v1 to v2.