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

# Query RSAM

> Endpoints for querying seismic RSAM (Real-time Seismic Amplitude Measurement) time-series data

## Overview

The RSAM endpoints provide access to seismic amplitude data from AVERT monitoring stations. Query time-series data by network, station, and channel with flexible date range filtering.

<Tip>
  Use `/api/seismic/sites` to discover available network/station/channel combinations before querying RSAM data.
</Tip>

## Available Stations and Channels

<Tabs>
  <Tab title="Cleveland">
    | Field       | Value     |
    | ----------- | --------- |
    | **Volcano** | Cleveland |
    | **Network** | `AV`      |

    | Station | Channels            |
    | ------- | ------------------- |
    | `CLCL`  | `BHE`, `BHN`, `BHZ` |
    | `CLCO`  | `BHE`, `BHN`, `BHZ` |
    | `CLES`  | `BHE`, `BHN`, `BHZ` |
    | `CLNE`  | `BHE`, `BHN`, `BHZ` |
    | `CLSF`  | `BHE`, `BHN`, `BHZ` |
  </Tab>

  <Tab title="Poás">
    | Field       | Value |
    | ----------- | ----- |
    | **Volcano** | Poás  |
    | **Network** | `OV`  |

    | Station | Channels                                                      |
    | ------- | ------------------------------------------------------------- |
    | `VPCC`  | `HHE`, `HHN`, `HHZ`, `VDT`, `VEC`, `VEI`, `VM1`, `VM2`, `VM3` |
    | `VPNC`  | `HHE`, `HHN`, `HHZ`, `VDT`, `VEC`, `VEI`, `VM1`, `VM2`, `VM3` |
    | `VPPC`  | `HHE`, `HHN`, `HHZ`, `VDT`, `VEC`, `VEI`, `VM1`, `VM2`, `VM3` |
    | `VPRS`  | `HHE`, `HHN`, `HHZ`, `VDT`, `VEC`, `VEI`, `VM1`, `VM2`, `VM3` |
  </Tab>

  <Tab title="Villarrica">
    | Field       | Value      |
    | ----------- | ---------- |
    | **Volcano** | Villarrica |
    | **Network** | `VC`       |

    | Station | Channels                   |
    | ------- | -------------------------- |
    | `RKPI`  | `HDF`, `HHE`, `HHN`, `HHZ` |
  </Tab>
</Tabs>

## Endpoints

| Method | Path                       | Description                                             |
| ------ | -------------------------- | ------------------------------------------------------- |
| `GET`  | `/api/seismic/sites`       | List all available network/station/channel combinations |
| `GET`  | `/api/seismic/dates`       | List dates with RSAM data for a specific channel        |
| `GET`  | `/api/seismic/rsam/latest` | Most recent RSAM entry per channel                      |
| `GET`  | `/api/seismic/rsam`        | RSAM time-series for a channel over a date range        |

***

## GET /api/seismic/rsam

Returns a RSAM time-series for the requested channel between `datefrom` and `dateto`. Both dates are inclusive and results are returned in chronological order.

### Parameters

<ParamField query="network" type="string" required>
  Seismic network code

  **Example:** `AV`

  ```bash theme={null}
  ?network=AV
  ```
</ParamField>

<ParamField query="station" type="string" required>
  Station code

  **Example:** `CLNE`

  ```bash theme={null}
  ?station=CLNE
  ```
</ParamField>

<ParamField query="channel" type="string" required>
  Channel code

  **Example:** `BHZ`

  ```bash theme={null}
  ?channel=BHZ
  ```
</ParamField>

<ParamField query="datefrom" type="string" required>
  Start date for query range (inclusive)

  **Format:** `YYYYMMDD`\
  **Example:** `20260410` = April 10, 2026

  ```bash theme={null}
  # Start from April 10, 2026
  ?datefrom=20260410
  ```
</ParamField>

<ParamField query="dateto" type="string" required>
  End date for query range (inclusive)

  **Format:** `YYYYMMDD`\
  **Example:** `20260412` = April 12, 2026

  ```bash theme={null}
  # End on April 12, 2026
  ?dateto=20260412
  ```
</ParamField>

### Response Format

<ResponseExample>
  ```json Success theme={null}
  {
    "series": [
      {
        "network": "AV",
        "station": "CLNE",
        "location": "",
        "channel": "BHZ",
        "window_sec": 60,
        "points": [
          {
            "time": "2026-04-10T00:00:00Z",
            "rsam_counts": 142.5
          },
          {
            "time": "2026-04-10T00:01:00Z",
            "rsam_counts": 138.2
          }
        ]
      }
    ],
    "datefrom": "20260410",
    "dateto": "20260412",
    "query": {
      "network": "AV",
      "station": "CLNE",
      "channel": "BHZ",
      "datefrom": "20260410",
      "dateto": "20260412"
    }
  }
  ```
</ResponseExample>

### Response Fields

<ResponseField name="series" type="array" required>
  Array containing one RSAM series object for the requested channel

  <Expandable title="Series object properties">
    <ResponseField name="network" type="string" required>
      Seismic network code
    </ResponseField>

    <ResponseField name="station" type="string" required>
      Station code
    </ResponseField>

    <ResponseField name="location" type="string" required>
      Location code (empty string if not set)
    </ResponseField>

    <ResponseField name="channel" type="string" required>
      Channel code
    </ResponseField>

    <ResponseField name="window_sec" type="integer" required>
      Duration in seconds of each RSAM averaging window (typically 60)
    </ResponseField>

    <ResponseField name="points" type="array" required>
      Chronological list of RSAM samples

      <Expandable title="Point object properties">
        <ResponseField name="time" type="string" required>
          ISO 8601 UTC timestamp of the sample (e.g. `"2026-04-10T00:00:00Z"`)
        </ResponseField>

        <ResponseField name="rsam_counts" type="number" required>
          RSAM amplitude value in counts
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="datefrom" type="string" required>
  Start date echoed from your query (`YYYYMMDD`)
</ResponseField>

<ResponseField name="dateto" type="string" required>
  End date echoed from your query (`YYYYMMDD`)
</ResponseField>

<ResponseField name="query" type="object" required>
  Echo of all query parameters for debugging
</ResponseField>

***

## GET /api/seismic/sites

Returns all distinct network/station/location/channel combinations that have RSAM data. Use this to discover what data is available before querying.

**Rate limit:** 60 requests per minute

### Response Format

<ResponseExample>
  ```json Success theme={null}
  {
    "channels": [
      {
        "network": "AV",
        "station": "CLNE",
        "location": "",
        "channel": "BHZ"
      },
      {
        "network": "AV",
        "station": "CLES",
        "location": "",
        "channel": "BHZ"
      }
    ],
    "total": 2
  }
  ```
</ResponseExample>

### Response Fields

<ResponseField name="channels" type="array" required>
  List of available channel combinations

  <Expandable title="Channel object properties">
    <ResponseField name="network" type="string" required>
      Seismic network code
    </ResponseField>

    <ResponseField name="station" type="string" required>
      Station code
    </ResponseField>

    <ResponseField name="location" type="string" required>
      Location code (empty string if not set)
    </ResponseField>

    <ResponseField name="channel" type="string" required>
      Channel code
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="total" type="integer" required>
  Total number of distinct channels returned
</ResponseField>

***

## GET /api/seismic/dates

Returns a list of dates (UTC) that have RSAM data for the requested network/station/channel. Use this to populate date pickers or validate date availability before querying.

**Rate limit:** 60 requests per minute

### Parameters

<ParamField query="network" type="string" required>
  Seismic network code (e.g. `AV`)
</ParamField>

<ParamField query="station" type="string" required>
  Station code (e.g. `CLNE`)
</ParamField>

<ParamField query="channel" type="string" required>
  Channel code (e.g. `BHZ`)
</ParamField>

### Response Format

<ResponseExample>
  ```json Success theme={null}
  {
    "dates": [
      "2026-04-12",
      "2026-04-11",
      "2026-04-10"
    ],
    "network": "AV",
    "station": "CLNE",
    "channel": "BHZ"
  }
  ```
</ResponseExample>

### Response Fields

<ResponseField name="dates" type="array" required>
  List of available dates in `YYYY-MM-DD` format, ordered newest first
</ResponseField>

<ResponseField name="network" type="string" required>
  Network code echoed from your query
</ResponseField>

<ResponseField name="station" type="string" required>
  Station code echoed from your query
</ResponseField>

<ResponseField name="channel" type="string" required>
  Channel code echoed from your query
</ResponseField>

***

## GET /api/seismic/rsam/latest

Returns the most recent available RSAM date for every network/station/location/channel combination. Useful for dashboards and monitoring views.

**Rate limit:** 60 requests per minute

### Response Format

<ResponseExample>
  ```json Success theme={null}
  {
    "channels": [
      {
        "network": "AV",
        "station": "CLNE",
        "location": "",
        "channel": "BHZ",
        "latest_date": "2026-04-12"
      }
    ],
    "total": 1
  }
  ```
</ResponseExample>

### Response Fields

<ResponseField name="channels" type="array" required>
  List of channels with their most recent data date

  <Expandable title="Channel entry properties">
    <ResponseField name="network" type="string" required>
      Seismic network code
    </ResponseField>

    <ResponseField name="station" type="string" required>
      Station code
    </ResponseField>

    <ResponseField name="location" type="string" required>
      Location code (empty string if not set)
    </ResponseField>

    <ResponseField name="channel" type="string" required>
      Channel code
    </ResponseField>

    <ResponseField name="latest_date" type="string" required>
      Most recent UTC date with RSAM data, in `YYYY-MM-DD` format
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="total" type="integer" required>
  Total number of channels returned
</ResponseField>

***

## Example Requests

### Discover Available Data

<CodeGroup>
  ```bash List All Channels theme={null}
  # See all available network/station/channel combinations
  curl "https://avert.ldeo.columbia.edu/api/seismic/sites"
  ```

  ```bash Check Latest Data theme={null}
  # See the most recent date available per channel
  curl "https://avert.ldeo.columbia.edu/api/seismic/rsam/latest"
  ```

  ```bash Available Dates for a Channel theme={null}
  # Check which dates have data for AV.CLNE.BHZ
  curl "https://avert.ldeo.columbia.edu/api/seismic/dates?\
  network=AV&\
  station=CLNE&\
  channel=BHZ"
  ```
</CodeGroup>

### Query RSAM Time-series

<CodeGroup>
  ```bash Single Day theme={null}
  # RSAM for AV.CLNE.BHZ on April 10, 2026
  curl "https://avert.ldeo.columbia.edu/api/seismic/rsam?\
  network=AV&\
  station=CLNE&\
  channel=BHZ&\
  datefrom=20260410&\
  dateto=20260410"
  ```

  ```bash Date Range theme={null}
  # RSAM for three days
  curl "https://avert.ldeo.columbia.edu/api/seismic/rsam?\
  network=AV&\
  station=CLNE&\
  channel=BHZ&\
  datefrom=20260410&\
  dateto=20260412"
  ```

  ```bash Full Month theme={null}
  # RSAM for all of April 2026
  curl "https://avert.ldeo.columbia.edu/api/seismic/rsam?\
  network=AV&\
  station=CLES&\
  channel=BHZ&\
  datefrom=20260401&\
  dateto=20260430"
  ```
</CodeGroup>

***

## Code Examples

### JavaScript/TypeScript

<CodeGroup>
  ```javascript Discover and Query theme={null}
  // Step 1: find available channels
  const sitesRes = await fetch(
    'https://avert.ldeo.columbia.edu/api/seismic/sites'
  );
  const { channels } = await sitesRes.json();
  console.log('Available channels:', channels.length);

  // Step 2: query RSAM for the first channel
  const { network, station, channel } = channels[0];
  const params = new URLSearchParams({
    network, station, channel,
    datefrom: '20260410',
    dateto: '20260412',
  });

  const rsamRes = await fetch(
    `https://avert.ldeo.columbia.edu/api/seismic/rsam?${params}`
  );
  const data = await rsamRes.json();

  const series = data.series[0];
  console.log(`${series.points.length} points for ${network}.${station}.${channel}`);
  ```

  ```javascript Plot Time-series theme={null}
  // Fetch and plot RSAM data
  async function getRsamSeries(network, station, channel, datefrom, dateto) {
    const params = new URLSearchParams({ network, station, channel, datefrom, dateto });
    const res = await fetch(
      `https://avert.ldeo.columbia.edu/api/seismic/rsam?${params}`
    );
    const data = await res.json();
    return data.series[0].points;
  }

  const points = await getRsamSeries('AV', 'CLNE', 'BHZ', '20260410', '20260412');

  // points is an array of { time, rsam_counts }
  const timestamps = points.map(p => new Date(p.time));
  const values     = points.map(p => p.rsam_counts);

  // Pass timestamps/values to your charting library
  ```

  ```javascript Latest Status Dashboard theme={null}
  // Build a status dashboard showing latest RSAM date per channel
  const res = await fetch(
    'https://avert.ldeo.columbia.edu/api/seismic/rsam/latest'
  );
  const { channels } = await res.json();

  channels.forEach(({ network, station, channel, latest_date }) => {
    console.log(`${network}.${station}.${channel} — latest: ${latest_date}`);
  });
  ```
</CodeGroup>

### Python

<CodeGroup>
  ```python Basic Query theme={null}
  import requests

  response = requests.get(
      'https://avert.ldeo.columbia.edu/api/seismic/rsam',
      params={
          'network': 'AV',
          'station': 'CLNE',
          'channel': 'BHZ',
          'datefrom': '20260410',
          'dateto': '20260412',
      }
  )
  data = response.json()

  series = data['series'][0]
  print(f"{len(series['points'])} RSAM points")
  print(f"Window: {series['window_sec']} seconds")

  for point in series['points'][:5]:
      print(f"  {point['time']}: {point['rsam_counts']:.1f} counts")
  ```

  ```python Discover Available Channels theme={null}
  import requests

  # List all channels
  sites = requests.get(
      'https://avert.ldeo.columbia.edu/api/seismic/sites'
  ).json()

  for ch in sites['channels']:
      print(f"{ch['network']}.{ch['station']}.{ch['channel']}")
  ```

  ```python Check Date Availability theme={null}
  import requests

  # Check which dates have data before querying
  dates_res = requests.get(
      'https://avert.ldeo.columbia.edu/api/seismic/dates',
      params={'network': 'AV', 'station': 'CLNE', 'channel': 'BHZ'}
  )
  dates = dates_res.json()['dates']

  print(f"Available dates: {len(dates)}")
  print(f"Latest: {dates[0]}")
  print(f"Oldest: {dates[-1]}")
  ```

  ```python Export to CSV theme={null}
  import requests
  import csv

  response = requests.get(
      'https://avert.ldeo.columbia.edu/api/seismic/rsam',
      params={
          'network': 'AV',
          'station': 'CLNE',
          'channel': 'BHZ',
          'datefrom': '20260410',
          'dateto': '20260410',
      }
  )
  series = response.json()['series'][0]

  with open('rsam.csv', 'w', newline='') as f:
      writer = csv.DictWriter(f, fieldnames=['time', 'rsam_counts'])
      writer.writeheader()
      writer.writerows(series['points'])

  print(f"Exported {len(series['points'])} rows to rsam.csv")
  ```
</CodeGroup>

***

## Handling Rate Limits

The `/api/seismic/rsam` endpoint limits requests to 100 per minute per IP address. Helper endpoints (`/sites`, `/dates`, `/rsam/latest`) are limited to 60 per minute.

<CodeGroup>
  ```python Python theme={null}
  import requests
  import time

  def query_rsam_with_retry(params, max_retries=3):
      for attempt in range(max_retries):
          response = requests.get(
              'https://avert.ldeo.columbia.edu/api/seismic/rsam',
              params=params
          )
          if response.status_code == 200:
              return response.json()
          elif response.status_code == 429:
              wait_time = 2 ** attempt
              print(f"Rate limited. Waiting {wait_time} seconds...")
              time.sleep(wait_time)
          else:
              response.raise_for_status()
      raise Exception("Max retries exceeded")
  ```

  ```javascript JavaScript theme={null}
  async function queryRsamWithRetry(params, maxRetries = 3) {
    const url = 'https://avert.ldeo.columbia.edu/api/seismic/rsam?' +
      new URLSearchParams(params);

    for (let attempt = 0; attempt < maxRetries; attempt++) {
      const response = await fetch(url);

      if (response.ok) return await response.json();

      if (response.status === 429) {
        const waitTime = Math.pow(2, attempt) * 1000;
        console.log(`Rate limited. Waiting ${waitTime / 1000} seconds...`);
        await new Promise(resolve => setTimeout(resolve, waitTime));
      } else {
        throw new Error(`HTTP ${response.status}: ${response.statusText}`);
      }
    }
    throw new Error('Max retries exceeded');
  }
  ```
</CodeGroup>

***

## Error Responses

<ResponseExample>
  ```json 400 - Invalid Date Format theme={null}
  {
    "error": true,
    "status_code": 400,
    "detail": "Invalid datefrom format '2026-04-10'. Use YYYYMMDD (e.g. 20260410)."
  }
  ```

  ```json 400 - Date Range Reversed theme={null}
  {
    "error": true,
    "status_code": 400,
    "detail": "datefrom must be <= dateto"
  }
  ```

  ```json 422 - Missing Required Parameter theme={null}
  {
    "error": true,
    "status_code": 422,
    "detail": "Validation error in request parameters",
    "errors": [
      {
        "type": "missing",
        "loc": ["query", "network"],
        "msg": "Field required"
      }
    ],
    "path": "/api/seismic/rsam"
  }
  ```

  ```json 429 - Rate Limit Exceeded theme={null}
  {
    "error": "Rate limit exceeded: 100 per 1 minute"
  }
  ```
</ResponseExample>

***

## Rate Limits

| Endpoint                   | Rate Limit   | Window     |
| -------------------------- | ------------ | ---------- |
| `/api/seismic/rsam`        | 100 requests | per minute |
| `/api/seismic/sites`       | 60 requests  | per minute |
| `/api/seismic/dates`       | 60 requests  | per minute |
| `/api/seismic/rsam/latest` | 60 requests  | per minute |

***

## Need Help?

<CardGroup cols={2}>
  <Card title="Query Imagery" icon="camera" href="/api-reference/v2/query-imagery">
    Query infrared and visible volcano imagery
  </Card>

  <Card title="Contact Support" icon="envelope" href="mailto:avert-system@proton.me">
    Questions or issues? Reach out to our team
  </Card>
</CardGroup>