AVERT Imagery API v2.0.0

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

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 visibility, day/night, degraded quality, and temporal frequency

Smart Downloads

Get download estimates before committing to large datasets

Endpoints

Endpoint	Description
`GET /api/imagery/q`	Query and download infrared/visible imagery
`GET /api/imagery/dates`	Get available dates per site (fast, cached)
`GET /api/imagery/dates/range`	Get global min/max date range per image type

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 conditions
?low_visibility=false&is_empty=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

freq=all with single site returns local timestamps (no Z suffix)
All other queries return UTC timestamps (with Z suffix)

7. Date Availability Endpoints (v2.0.0)

GET /api/imagery/dates - Returns available dates per site from static cache (no DB query)
GET /api/imagery/dates/range - Returns global min/max date range per image type
Both include Cache-Control: public, max-age=86400 response header

Breaking Changes from v1

Endpoint consolidation

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

Parameter changes

v1: search_from, search_tov2: datefrom, dateto (format: yyyymmddhhmmss)

# v1 format
?search_from=2022-10-01T00:00

# v2 format
?datefrom=20221001000000

Response structure

v1: Array of images

[
  {"image_id": "...", "image_url": "..."},
  ...
]

v2: Structured response with pagination

{
  "results": [...],
  "pagination": {...},
  "query": {...}
}

Download behavior

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"

import requests

response = requests.get(
    'https://avert.ldeo.columbia.edu/api/imagery/q',
    params={
        'imageType': 'infrared',
        'limit': 20
    }
)
data = response.json()

print(f"Found {len(data['results'])} images")
for img in data['results']:
    print(img['image_url'])

const response = await fetch(
  'https://avert.ldeo.columbia.edu/api/imagery/q?imageType=infrared&limit=20'
);
const data = await response.json();

console.log(`Found ${data.results.length} images`);
data.results.forEach(img => {
  console.log(img.image_url);
});

Filter by Site and Date

Get clear, non-degraded infrared images from Cleveland volcano in November 2025:

curl "https://avert.ldeo.columbia.edu/api/imagery/q?\
imageType=infrared&\
site=CLNE&\
datefrom=20251101000000&\
dateto=20251130235959&\
low_visibility=false&\
is_degraded=false&\
is_empty=false&\
limit=50"

response = requests.get(
    'https://avert.ldeo.columbia.edu/api/imagery/q',
    params={
        'imageType': 'infrared',
        'site': 'CLNE',
        'datefrom': '20251101000000',
        'dateto': '20251130235959',
        'low_visibility': False,
        'is_degraded': False,
        'is_empty': False,
        'limit': 50
    }
)

const params = new URLSearchParams({
  imageType: 'infrared',
  site: 'CLNE',
  datefrom: '20251101000000',
  dateto: '20251130235959',
  low_visibility: 'false',
  is_degraded: 'false',
  is_empty: 'false',
  limit: '50'
});

const response = await fetch(
  `https://avert.ldeo.columbia.edu/api/imagery/q?${params}`
);

Available Volcanoes and Sites

The API provides access to imagery from multiple volcanic monitoring sites. Available data varies by image type:

Image Type	Volcano ID	Site Code(s)	Volcano Name
Infrared	311240	CLNE	Cleveland
Infrared	345040	VPMI	Poás
Infrared	383010	CV01, CV02	Cumbre Vieja
Visible	311240	CLNE	Cleveland
Visible	311290	OKCF	Okmok
Visible	345040	VPMI	Poás
Visible	357120	RKPI	Villarrica

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: Visibility, day/night, degraded quality, empty files
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:

Get estimate (size, time, warnings)
Review and confirm
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:

Endpoint	Rate Limit	Window
`/api/imagery/q`	100 requests	per minute
`/api/imagery/dates`	60 requests	per minute
`/api/imagery/dates/range`	60 requests	per minute
`/health`	60 requests	per minute
`/` (root)	100 requests	per 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

Implement Retry Logic: Wait before retrying when you receive a 429 response
Cache Results: Store frequently accessed data locally
Use Pagination: Don’t request all data at once
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.

Getting Started

The Single-Board Computer

Node Software

The Data Server

API Reference v2

The AVERT Data Portal

AVERT Imagery API v2.0.0

Welcome to API v2.0.0

Why Upgrade to v2?

Unified Endpoint

Public Image URLs

Advanced Filtering

Smart Downloads

Endpoints

What’s New in v2.0.0

Major Improvements

Breaking Changes from v1

Quick Start

Basic Query

Filter by Site and Date

Available Volcanoes and Sites

Key Features

Flexible Filtering

Smart Downloads

Transparent Queries

Rate Limits

How Rate Limiting Works

Rate Limit Response

Best Practices

Authentication

Need Help Migrating?

​Welcome to API v2.0.0

​Why Upgrade to v2?

Unified Endpoint

Public Image URLs

Advanced Filtering

Smart Downloads

​Endpoints

​What’s New in v2.0.0

​Major Improvements

​Breaking Changes from v1

​Quick Start

​Basic Query

​Filter by Site and Date

​Available Volcanoes and Sites

​Key Features

​Flexible Filtering

​Comprehensive Pagination

​Smart Downloads

​Transparent Queries

​Rate Limits

​How Rate Limiting Works

​Rate Limit Response

​Best Practices

​Authentication

​Need Help Migrating?

Welcome to API v2.0.0

Why Upgrade to v2?

Endpoints

What’s New in v2.0.0

Major Improvements

Breaking Changes from v1

Quick Start

Basic Query

Filter by Site and Date

Available Volcanoes and Sites

Key Features

Flexible Filtering

Comprehensive Pagination

Smart Downloads

Transparent Queries

Rate Limits

How Rate Limiting Works

Rate Limit Response

Best Practices

Authentication

Need Help Migrating?