Aristocles Pty Ltd Volcanic Eruptions API

openapi: 3.2.0
info:
  title: Aristocles Data Volcanic Eruptions API
  description: 'Four Australian data APIs on one key — subscriptions, trade pricing, PBS drugs, and rental prices.


    ---


    ## Quick start


    **1. Get your API key** — register in one request:

    ```

    POST /v1/auth/register

    {"email": "you@example.com", "name": "Your Name"}

    ```

    Copy the `api_key` from the response.


    **2. Authenticate** — add your key to every request as a header:

    ```

    X-API-Key: ar_live_xxxxxxxxxxxx

    ```


    **3. Run the discovery endpoint** — returns all available slugs, example calls, and your account limits:

    ```

    GET /v1/discovery

    ```


    **4. Make your first call:**

    ```

    GET /v1/prices/netflix?country=AU

    GET /v1/trades/electrician/prices?state=NSW&country=AU

    GET /v1/pbs/metformin

    GET /v1/rental/VIC/Richmond

    ```


    ---


    ## Four data domains


    | Domain | Base path | What it covers |

    |---|---|---|

    | **Subscription Pricing** | `/v1/prices`, `/v1/services` | 50+ SaaS & streaming services: Netflix, Spotify, Adobe, etc. |

    | **Contractor Trades** | `/v1/trades` | Plumbers, electricians, painters across AU, US, UK, CA, NZ |

    | **PBS Drug Pricing** | `/v1/pbs` | 14,000+ medications on Australia''s Pharmaceutical Benefits Scheme |

    | **Rental Market** | `/v1/rental` | Median weekly rent by suburb and postcode across Australia |

    | **RBA Economic Data** | `/v1/rba` | Cash rate, AUD FX rates, CPI inflation, mortgage rates, credit aggregates |


    ---


    ## MCP Server


    All four data domains are also available as MCP tools at:

    ```

    https://api.aristocles.com.au/mcp/

    ```

    Connect any MCP-compatible AI agent (Claude, GPT, Gemini) to get structured data without writing API calls.'
  version: 2.1.0
tags:
- name: Volcanic Eruptions
  description: 'The long-running record of significant volcanic eruptions maintained by the United States national geophysical data centre, covering events from antiquity to the present. Each row gives the volcano name, date, coordinates, elevation, explosivity index and recorded human and economic impact. Insurers, travel-risk platforms and hazard modellers use it as a baseline for eruption frequency and severity. Source: Source: NOAA National Centers for Environmental Information, Significant Volcanic Eruption Database (public domain).. Licence: Public Domain (U.S. Government Work). Base path: /v1/data/global-volcanic-eruptions. Requires an API key (X-API-Key).'
paths:
  /v1/data/global-volcanic-eruptions:
    get:
      tags:
      - Volcanic Eruptions
      summary: List Global Volcanic Eruptions records
      description: 'List Global Volcanic Eruptions records with optional filters and pagination.


        **Source:** Source: NOAA National Centers for Environmental Information, Significant Volcanic Eruption Database (public domain). (Public Domain (U.S. Government Work)).


        **Fields returned:**

        - `event_id` (int) — Unique identifier for the eruption event

        - `volcano_name` (str) — Name of the volcano

        - `location` (str) — Descriptive location of the volcano

        - `country` (str) — Country in which the volcano sits

        - `year` (int) — Year of the eruption; negative values indicate BCE

        - `month` (int) — Month of the eruption where known

        - `day` (int) — Day of the eruption where known

        - `latitude` (float) — Latitude in decimal degrees

        - `longitude` (float) — Longitude in decimal degrees

        - `elevation_m` (int) — Volcano summit elevation in metres

        - `morphology` (str) — Volcano type, e.g. stratovolcano, caldera, shield

        - `explosivity_index` (int) — Volcanic Explosivity Index from 0 to 8

        - `deaths_total` (int) — Total recorded deaths attributed to the eruption

        - `damage_millions_usd` (float) — Recorded economic damage in millions of US dollars


        **Example:** `GET /v1/data/global-volcanic-eruptions?limit=10&country=example`'
      operationId: list_endpoint_v1_data_global_volcanic_eruptions_get
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          description: Max records to return (1-100).
          default: 25
          title: Limit
        description: Max records to return (1-100).
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          description: Records to skip, for pagination.
          default: 0
          title: Offset
        description: Records to skip, for pagination.
      - name: country
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Country in which the volcano sits
          examples:
          - example
          title: Country
        description: Country in which the volcano sits
      - name: year
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Year of the eruption; negative values indicate BCE
          examples:
          - '42'
          title: Year
        description: Year of the eruption; negative values indicate BCE
      - name: explosivity_index
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Volcanic Explosivity Index from 0 to 8
          examples:
          - '42'
          title: Explosivity Index
        description: Volcanic Explosivity Index from 0 to 8
      - name: morphology
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Volcano type, e.g. stratovolcano, caldera, shield
          examples:
          - example
          title: Morphology
        description: Volcano type, e.g. stratovolcano, caldera, shield
      - name: X-API-Key
        in: header
        required: true
        schema:
          type: string
          title: X-Api-Key
      responses:
        '200':
          description: A page of Global Volcanic Eruptions records with pagination metadata.
          content:
            application/json:
              schema: {}
              example:
                data:
                  items:
                  - event_id: 42
                    volcano_name: example
                    location: example
                    country: example
                    year: 42
                    month: 42
                    day: 42
                    latitude: 4.2
                    longitude: 4.2
                    elevation_m: 42
                    morphology: example
                    explosivity_index: 42
                    deaths_total: 42
                    damage_millions_usd: 4.2
                  total: 1
                  limit: 25
                  offset: 0
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/data/global-volcanic-eruptions/search:
    get:
      tags:
      - Volcanic Eruptions
      summary: Search Global Volcanic Eruptions by volcano_name
      description: 'Search Global Volcanic Eruptions records by `volcano_name` (partial, case-insensitive).


        **Example:** `GET /v1/data/global-volcanic-eruptions/search?q=exa`'
      operationId: search_endpoint_v1_data_global_volcanic_eruptions_search_get
      parameters:
      - name: q
        in: query
        required: true
        schema:
          type: string
          minLength: 2
          maxLength: 100
          description: Case-insensitive partial match on volcano_name.
          examples:
          - exa
          title: Q
        description: Case-insensitive partial match on volcano_name.
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          description: Max records to return (1-100).
          default: 25
          title: Limit
        description: Max records to return (1-100).
      - name: X-API-Key
        in: header
        required: true
        schema:
          type: string
          title: X-Api-Key
      responses:
        '200':
          description: Matching Global Volcanic Eruptions records.
          content:
            application/json:
              schema: {}
              example:
                data:
                  items:
                  - event_id: 42
                    volcano_name: example
                    location: example
                    country: example
                    year: 42
                    month: 42
                    day: 42
                    latitude: 4.2
                    longitude: 4.2
                    elevation_m: 42
                    morphology: example
                    explosivity_index: 42
                    deaths_total: 42
                    damage_millions_usd: 4.2
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/data/global-volcanic-eruptions/{key}:
    get:
      tags:
      - Volcanic Eruptions
      summary: Get one Global Volcanic Eruptions record by event_id
      description: 'Fetch a single Global Volcanic Eruptions record by its `event_id`.


        **Example:** `GET /v1/data/global-volcanic-eruptions/42`'
      operationId: get_endpoint_v1_data_global_volcanic_eruptions__key__get
      parameters:
      - name: key
        in: path
        required: true
        schema:
          type: string
          description: The event_id value to look up (case-insensitive).
          examples:
          - '42'
          title: Key
        description: The event_id value to look up (case-insensitive).
      - name: X-API-Key
        in: header
        required: true
        schema:
          type: string
          title: X-Api-Key
      responses:
        '200':
          description: A single Global Volcanic Eruptions record.
          content:
            application/json:
              schema: {}
              example:
                data:
                  event_id: 42
                  volcano_name: example
                  location: example
                  country: example
                  year: 42
                  month: 42
                  day: 42
                  latitude: 4.2
                  longitude: 4.2
                  elevation_m: 42
                  morphology: example
                  explosivity_index: 42
                  deaths_total: 42
                  damage_millions_usd: 4.2
        '404':
          content:
            application/json:
              example:
                error:
                  code: NOT_FOUND
                  message: No Global Volcanic Eruptions record for '...'.
          description: Not Found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError