> ## 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.

# AVERT Imagery API v2.0.0

> Unified API for accessing infrared and visible volcano imagery with advanced filtering

<Warning>
  **API v2.0.0 is now available!** We recommend all users migrate to v2 for a better experience. [View migration guide](/api-reference/v2/migration-guide).
</Warning>

## 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?

<CardGroup cols={2}>
  <Card title="Unified Endpoint" icon="merge">
    Single endpoint for both infrared and visible images - no more separate URLs
  </Card>

  <Card title="Public Image URLs" icon="link">
    Returns ready-to-display HTTPS URLs - just plug and play
  </Card>

  <Card title="Advanced Filtering" icon="filter">
    Filter by visibility, day/night, degraded quality, and temporal frequency
  </Card>

  <Card title="Smart Downloads" icon="download">
    Get download estimates before committing to large datasets
  </Card>
</CardGroup>

## 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**

```bash theme={null}
# 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**

```bash theme={null}
# 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**

```json theme={null}
{
  "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

<AccordionGroup>
  <Accordion title="Endpoint consolidation">
    **v1**: Separate endpoints

    ```bash theme={null}
    /api/imagery/infrared/query
    /api/imagery/visible/query
    ```

    **v2**: Single unified endpoint

    ```bash theme={null}
    /api/imagery/q?imageType=infrared
    /api/imagery/q?imageType=visible
    ```
  </Accordion>

  <Accordion title="Parameter changes">
    **v1**: `search_from`, `search_to`

    **v2**: `datefrom`, `dateto` (format: `yyyymmddhhmmss`)

    ```bash theme={null}
    # v1 format
    ?search_from=2022-10-01T00:00

    # v2 format
    ?datefrom=20221001000000
    ```
  </Accordion>

  <Accordion title="Response structure">
    **v1**: Array of images

    ```json theme={null}
    [
      {"image_id": "...", "image_url": "..."},
      ...
    ]
    ```

    **v2**: Structured response with pagination

    ```json theme={null}
    {
      "results": [...],
      "pagination": {...},
      "query": {...}
    }
    ```
  </Accordion>

  <Accordion title="Download behavior">
    **v1**: Fixed 100-image limit

    **v2**: Smart downloads with estimates

    * Get size/time estimates first
    * Download all matching results (not just one page)
    * Configurable limits up to 200 per request
  </Accordion>
</AccordionGroup>

## Quick Start

You can find [available endpoints](/api-reference/v2/query-imagery) for querying infrared and visible volcano imagery with advanced filters.

### Basic Query

Get the 20 most recent infrared images:

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://avert.ldeo.columbia.edu/api/imagery/q?imageType=infrared&limit=20"
  ```

  ```python Python theme={null}
  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'])
  ```

  ```javascript JavaScript theme={null}
  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);
  });
  ```
</CodeGroup>

### Filter by Site and Date

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

<CodeGroup>
  ```bash cURL theme={null}
  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"
  ```

  ```python Python theme={null}
  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
      }
  )
  ```

  ```javascript JavaScript theme={null}
  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}`
  );
  ```
</CodeGroup>

## 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   |

<Tip>
  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`
</Tip>

## 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:

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:

| 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

```json theme={null}
{
  "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

<Tip>
  Implement exponential backoff when retrying failed requests. See our [code examples](/api-reference/v2/query-imagery#handling-rate-limits) for implementation details.
</Tip>

<Note>
  If you need higher rate limits for legitimate use cases, please contact the AVERT System Team.
</Note>

## 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](/api-reference/v2/migration-guide) for step-by-step instructions on upgrading from v1 to v2.