Query Imagery
Endpoints
Query Imagery
Unified endpoint for querying infrared and visible volcano imagery
GET
Query Imagery
Documentation Index
Fetch the complete documentation index at: https://docs.avert.ldeo.columbia.edu/llms.txt
Use this file to discover all available pages before exploring further.
Overview
The unified imagery query endpoint provides access to both infrared and visible images from AVERT volcano monitoring cameras. Query and download images with flexible filtering options including site, date range, atmospheric conditions, and temporal sampling.Parameters
Image Type
Type of imagery to queryOptions:
infrared- Thermal/infrared imagery (default)visible- Standard visible light imagery
Pagination
Number of results per pageRange: 1-200
Default: 100
Default: 100
Page number for paginationMinimum: 1
Default: 1
Default: 1
Location Filters
You can find available site names and vnum codes here.
Camera site codeCommon sites:
CLNE- Cleveland volcanoVPMI- Poás volcano
Volcano ID numberCommon volcano IDs:
311240- Cleveland345040- Poás383010- Cumbre Vieja311290- Okmok
Date Range Filters
Start date/time for query rangeFormat:
Timezone: Coordinated Universal Time (UTC) Example:
yyyymmddhhmmssTimezone: Coordinated Universal Time (UTC) Example:
20250321110000 = March 21, 2025 at 11:00:00 AM UTCEnd date/time for query rangeFormat:
Timezone: Coordinated Universal Time (UTC)Time Handling:
yyyymmddhhmmssTimezone: Coordinated Universal Time (UTC)Time Handling:
freq=allwith single site: Time portion ignored, dates interpreted as local datesfreq=daily: Time portion ignored, dates interpreted as local datesfreq=hourly/minutely: Time portion creates daily recurring UTC time windowfreq=allwithout site: Time portion used, dates interpreted as exact UTC range
Condition Filters
Filter by empty/corrupted filesApplies to: Infrared and Visible
Filter by time of dayApplies to: Visible only (returns 400 error for infrared)Options:
true- Nighttime imagesfalse- Daytime images
Filter by degraded quality (dynamic range artifacts)Applies to: Infrared only (returns 400 error for visible)
Filter by fog/clouds obstructionApplies to: Infrared and Visible
Temporal Sampling
Frequency/sampling filter for time-lapse and data reductionOptions:
Time Handling:
all- Return all captured images (default, ~1-2 min intervals)- Single site: Returns all images for full local days, timestamps in local time (no Z)
- No site/multi-site: Returns images in exact UTC time range, timestamps in UTC (with Z)
minutely- Middle image from each minute within daily UTC time window (requiressite)hourly- Middle image from each hour within daily UTC time window (requiressite)daily- Image closest to 10:00 AM local time for each day (requiressite)
freq parameter groups images by time period and returns a representative image from each period.| freq value | Data Reduction | Timestamp Format | Requires Site? |
|---|---|---|---|
all (single site) | None (100% of images) | Local time (no Z) | No |
all (no site) | None | UTC (with Z) | No |
minutely | ~0-5% | UTC (with Z) | Yes |
hourly | ~98% (60x smaller) | UTC (with Z) | Yes |
daily | ~99.9% (1440x smaller) | UTC (with Z) | Yes |
freq=allwith single site: Time portion ignored, returns full local daysfreq=daily: Time portion ignored, returns one image per local day at 10 AMfreq=hourly/minutely: Time portion creates daily recurring UTC time window
Sort order of results by timestampOptions:
desc- Newest images first (default)asc- Oldest images first
freq=allwith single site: Sorts by local site time- All other queries: Sorts by UTC time
For
freq=hourly and freq=minutely, the same images are returned regardless of order - only the display order changes.Download Options
Download mode for retrieving imagesOptions:
estimate- Get download estimate (size, time, warnings) WITHOUT downloadingtrue- Download all matching images as ZIP fileselected- Download specific images by ID (requiresimage_ids)
API testing:
Comma-separated image IDs for selective downloadRequired when:
Format: Comma-separated list of image IDs
download=selectedFormat: Comma-separated list of image IDs
Response Format
JSON Response (default)
Response Fields
Array of image objects matching your query
Pagination metadata for navigating results
Echo of your query parameters for debugging
Download Estimate Response
When usingdownload=estimate:
ZIP Download Response
When usingdownload=true or download=selected, returns a ZIP file containing JPG images.
ZIP Structure:
Example Requests
Basic Queries
Filter by Location
Filter by Date
Filter by Conditions
Temporal Sampling
Downloads
Code Examples
JavaScript/TypeScript
Python
Handling Rate Limits
The/api/imagery/q endpoint limits requests to 100 per minute per IP address. Implement retry logic to handle rate limit errors:
Error Responses
Best Practices
Use estimates before downloading
Use estimates before downloading
Always call
download=estimate before triggering large downloads to inform users about size and time requirements.Use freq parameter for large datasets
Use freq parameter for large datasets
When querying long time periods, use
freq=hourly or freq=daily to reduce dataset size while maintaining temporal coverage.Implement pagination for large result sets
Implement pagination for large result sets
Don’t try to fetch all results at once. Use pagination to load results incrementally.
Cache results when appropriate
Cache results when appropriate
Store frequently accessed data locally to reduce API calls and improve performance.
Handle errors gracefully
Handle errors gracefully
Implement proper error handling and retry logic for rate limits and network errors.
Need Help?
Migration Guide
Upgrading from API v1? Check our migration guide
Contact Support
Questions or issues? Reach out to our team

