DataQuoll Gauges API

openapi: 3.2.0
info:
  title: DataQuoll Gauges API
  description: 'DataQuoll turns fragmented Australian public data into answers about locations, events and assets.


    Today''s datasets: real-time emergency incidents and warnings (bushfires, floods, storms, earthquakes, rescues, and more) in one GeoJSON schema with CAP-aligned severity, urgency, and certainty fields that carry only what each agency states; disaster declarations reported by LGA as declared-area status; live river gauges with BoM flood classes; and a historical archive. DataQuoll was formerly EmergencyAPI. Standards-validated CAP output is available as an Atom feed via ?format=cap-atom and as per-incident documents via /api/v1/incidents/{id}?format=cap-au, both validated against the OASIS CAP 1.2 schema and the CAP-AU Profile v3.0. Includes real-time incidents, proximity search, and historical audit trail snapshots.


    **Disclaimer:** DataQuoll provides aggregated emergency incident data for informational

    purposes only. This data is sourced from

    official government feeds, community-decoded SA pager feeds and an agency feed whose licence is not published (NT PFES).

    It may be delayed, incomplete, or inaccurate. Do not use this API as a substitute for

    official emergency warnings.'
  version: 1.113.0
  contact:
    name: DataQuoll Support
    url: https://dataquoll.io
  license:
    name: Proprietary
servers:
- url: https://dataquoll.io
  description: Primary host
- url: https://emergencyapi.com
  description: Legacy host, identical responses until the announced sunset
security:
- BearerAuth: []
tags:
- name: Gauges
  description: River gauge observations against the Bureau of Meteorology flood classifications. Status reporting, not flood prediction, and not a substitute for official warnings.
paths:
  /api/v1/gauges:
    get:
      operationId: listGauges
      summary: River gauge stations with live flood status
      description: Returns river gauge stations with their latest water level, the Bureau of Meteorology flood classification thresholds for each gauge, and a derived floodClass (below_minor, minor, moderate, major, or unclassified) computed from the latest reading against the published thresholds. Water-level readings are in metres relative to each gauge's local datum (each gauge carries its own unit, since some report in AHD). readingStatus flags stale data (bom-kiwis sourced stations are a 1-2 day archive, stale horizon 72 hours; bcc-telemetry are event-driven council ALERT loggers, stale horizon 48 hours; telemetry sources 24 hours). Defaults to water-level gauges; pass variable=rainfall for observed rainfall gauges, which report incremental millimetres and carry no flood classification. Status reporting, not flood prediction.
      tags:
      - Gauges
      parameters:
      - name: variable
        in: query
        description: Measured variable. Defaults to water_level; rainfall returns observed rain gauges (millimetres, incremental, no flood class).
        schema:
          type: string
          enum:
          - water_level
          - rainfall
          default: water_level
      - name: state
        in: query
        description: Lowercase state code (nsw, vic, qld, sa, wa, tas, nt, act)
        schema:
          type: string
        example: nsw
      - name: floodClass
        in: query
        description: 'Filter to gauges at or above this class (>= semantics: minor matches moderate and major too). Water-level only; cannot combine with variable=rainfall.'
        schema:
          type: string
          enum:
          - minor
          - moderate
          - major
      - name: lga
        in: query
        description: ABS LGA code (the same LGA_2022 vocabulary as the declarations API)
        schema:
          type: string
        example: '17750'
      - name: source
        in: query
        description: Polling source (hydstra-nsw, hydstra-vic, hydstra-qld, aquarius-sa, aquarius-tas, aquarius-nt, bom-kiwis, bcc-telemetry)
        schema:
          type: string
      - name: bbox
        in: query
        description: Bounding box minLng,minLat,maxLng,maxLat (within Australia)
        schema:
          type: string
        example: 138.4,-35.4,139.0,-34.6
      - name: limit
        in: query
        description: Max results per page (1-500, default 100)
        schema:
          type: integer
          default: 100
          maximum: 500
      - name: cursor
        in: query
        description: Pagination cursor from meta.nextCursor
        schema:
          type: string
      security:
      - BearerAuth: []
      - PaymentAuth: []
      x-payment-info:
        offers:
        - amount: '80000'
          currency: '0x20C000000000000000000000b9537d11c60E8b50'
          description: One request
          intent: charge
          method: tempo
        price:
          mode: fixed
          currency: USD
          amount: '0.08'
        protocols:
        - mpp:
            method: tempo
            intent: charge
            currency: '0x20C000000000000000000000b9537d11c60E8b50'
        - x402:
            scheme: exact
            network: eip155:8453
            asset: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
            amount: '80000'
      responses:
        '200':
          description: Gauge stations with latest readings and flood status
          headers:
            Payment-Receipt:
              $ref: '#/components/headers/PaymentReceipt'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GaugeCollection'
        '401':
          description: Missing or invalid API key. While pay per request is on, a request with no Authorization header gets 402 instead.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '402':
          description: 'Pay per request: no key was sent, so the answer is a price. The WWW-Authenticate header carries an MPP Payment challenge; pay it and send the request again with Authorization: Payment. Also sent, with a fresh price, when a payment fails its checks or its price has expired. Only while pay per request is on; otherwise a request without a key gets 401.'
          headers:
            WWW-Authenticate:
              $ref: '#/components/headers/PaymentChallenge'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
  /api/v1/gauges/{id}:
    get:
      operationId: getGauge
      summary: One gauge with a 6-hour recent window
      description: Returns a single gauge station plus its trailing 6 hours of raw readings (enough to see the current trend). Deeper history is the tier-gated /api/v1/gauges/{id}/readings endpoint.
      tags:
      - Gauges
      parameters:
      - name: id
        in: path
        required: true
        description: Gauge id from /api/v1/gauges (e.g. hydstra-nsw-410001)
        schema:
          type: string
      security:
      - BearerAuth: []
      - PaymentAuth: []
      x-payment-info:
        offers:
        - amount: '80000'
          currency: '0x20C000000000000000000000b9537d11c60E8b50'
          description: One request
          intent: charge
          method: tempo
        price:
          mode: fixed
          currency: USD
          amount: '0.08'
        protocols:
        - mpp:
            method: tempo
            intent: charge
            currency: '0x20C000000000000000000000b9537d11c60E8b50'
        - x402:
            scheme: exact
            network: eip155:8453
            asset: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
            amount: '80000'
      responses:
        '200':
          description: The gauge and its recent readings
          headers:
            Payment-Receipt:
              $ref: '#/components/headers/PaymentReceipt'
          content:
            application/json:
              schema:
                type: object
                properties:
                  gauge:
                    $ref: '#/components/schemas/Gauge'
                  recent:
                    type: array
                    items:
                      $ref: '#/components/schemas/GaugeReading'
                  meta:
                    type: object
                    properties:
                      recentWindowHours:
                        type: integer
                        description: 'The window recent covers: 6 hours.'
                      totalMm:
                        type: number
                        description: 'Rainfall gauges only: the sum of the window''s readings, in millimetres. Longer totals come from /api/v1/gauges/{id}/readings.'
                      unit:
                        type: string
                        description: 'Rainfall gauges only: mm.'
                      generatedAt:
                        type: string
                        format: date-time
                  links:
                    type: object
                    properties:
                      self:
                        type: string
                      readings:
                        type: string
                        description: This gauge's reading history.
                  disclaimer:
                    type: string
                  attribution:
                    type: string
                    format: uri
        '402':
          description: 'Pay per request: no key was sent, so the answer is a price. The WWW-Authenticate header carries an MPP Payment challenge; pay it and send the request again with Authorization: Payment. Also sent, with a fresh price, when a payment fails its checks or its price has expired. Only while pay per request is on; otherwise a request without a key gets 401.'
          headers:
            WWW-Authenticate:
              $ref: '#/components/headers/PaymentChallenge'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: No active gauge with that id
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
  /api/v1/gauges/{id}/readings:
    get:
      operationId: listGaugeReadings
      summary: Gauge reading history (paid tier)
      description: 'Historical water level readings for one gauge. Free tier is blocked (the free surface is current readings on /api/v1/gauges and the 6-hour window on /api/v1/gauges/{id}). Starter tier limited to 1 year lookback, Developer and Business to 5 years, Pro, Organisation and Enterprise unlimited. Retention ladder: raw 30 days, hourly rollups 90 days, daily forever, plus full-resolution raw inside flood-event windows kept forever. interval=auto picks the finest granularity available for the requested window.'
      tags:
      - Gauges
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: after
        in: query
        description: Start of range (ISO 8601, inclusive). Tier-limited.
        schema:
          type: string
          format: date-time
      - name: before
        in: query
        description: End of range (ISO 8601, exclusive). Defaults to now.
        schema:
          type: string
          format: date-time
      - name: interval
        in: query
        description: raw, hourly, daily, or auto (default)
        schema:
          type: string
          enum:
          - raw
          - hourly
          - daily
          - auto
          default: auto
      - name: above
        in: query
        description: Only readings at/above this published flood classification for the gauge
        schema:
          type: string
          enum:
          - minor
          - moderate
          - major
      - name: limit
        in: query
        schema:
          type: integer
          default: 500
          maximum: 1000
      - name: cursor
        in: query
        description: Pagination cursor from meta.nextCursor (ISO timestamp keyset)
        schema:
          type: string
      security:
      - BearerAuth: []
      - PaymentAuth: []
      x-payment-info:
        offers:
        - amount: '80000'
          currency: '0x20C000000000000000000000b9537d11c60E8b50'
          description: One request
          intent: charge
          method: tempo
        price:
          mode: fixed
          currency: USD
          amount: '0.08'
        protocols:
        - mpp:
            method: tempo
            intent: charge
            currency: '0x20C000000000000000000000b9537d11c60E8b50'
        - x402:
            scheme: exact
            network: eip155:8453
            asset: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
            amount: '80000'
      responses:
        '200':
          description: Readings for the gauge, newest first
          headers:
            Payment-Receipt:
              $ref: '#/components/headers/PaymentReceipt'
          content:
            application/json:
              schema:
                type: object
                properties:
                  gaugeId:
                    type: string
                  interval:
                    type: string
                  above:
                    type: string
                    enum:
                    - minor
                    - moderate
                    - major
                    description: 'Present with the above filter: the class asked for.'
                  aboveThresholdM:
                    type: number
                    description: 'Present with the above filter: that class''s published threshold for this gauge, in metres.'
                  readings:
                    type: array
                    items:
                      $ref: '#/components/schemas/GaugeReading'
                  meta:
                    type: object
                    properties:
                      count:
                        type: integer
                      hasMore:
                        type: boolean
                      nextCursor:
                        type: string
                        description: 'Present when hasMore: the last reading''s time (an ISO timestamp, or a date for daily buckets); pass it back as cursor.'
                      unit:
                        type: string
                        description: mm for rainfall; for water level, metres and the gauge's datum, e.g. m (local gauge datum).
                      aboveNote:
                        type: string
                        description: 'Present with the above filter: how an aggregated bucket matches it.'
                      generatedAt:
                        type: string
                        format: date-time
                  links:
                    type: object
                    properties:
                      self:
                        type: string
                  disclaimer:
                    type: string
                  attribution:
                    type: string
                    format: uri
        '402':
          description: 'Pay per request: no key was sent, so the answer is a price. The WWW-Authenticate header carries an MPP Payment challenge; pay it and send the request again with Authorization: Payment. Also sent, with a fresh price, when a payment fails its checks or its price has expired. Only while pay per request is on; otherwise a request without a key gets 401.'
          headers:
            WWW-Authenticate:
              $ref: '#/components/headers/PaymentChallenge'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Free tier blocked or depth limit exceeded
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
  /api/v1/gauges/summary:
    get:
      operationId: getGaugeSummary
      summary: Flood status counts by state or LGA
      description: 'Counts of gauges at or above minor/moderate/major flood classification, grouped by state or LGA, plus the full list of at-or-above-minor stations (capped at 500). STALE GUARD: only readings within the staleness horizon enter class counts: a days-old reading above minor is counted as stale, never as a current flood signal.'
      tags:
      - Gauges
      parameters:
      - name: variable
        in: query
        description: Measured variable. Defaults to water_level (rain gauges carry no flood class, so they are excluded from the counts by default).
        schema:
          type: string
          enum:
          - water_level
          - rainfall
          default: water_level
      - name: groupBy
        in: query
        description: state (default) or lga (requires the state parameter)
        schema:
          type: string
          enum:
          - state
          - lga
          default: state
      - name: state
        in: query
        schema:
          type: string
        example: sa
      security:
      - BearerAuth: []
      - PaymentAuth: []
      x-payment-info:
        offers:
        - amount: '80000'
          currency: '0x20C000000000000000000000b9537d11c60E8b50'
          description: One request
          intent: charge
          method: tempo
        price:
          mode: fixed
          currency: USD
          amount: '0.08'
        protocols:
        - mpp:
            method: tempo
            intent: charge
            currency: '0x20C000000000000000000000b9537d11c60E8b50'
        - x402:
            scheme: exact
            network: eip155:8453
            asset: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
            amount: '80000'
      responses:
        '200':
          description: Flood status summary
          headers:
            Payment-Receipt:
              $ref: '#/components/headers/PaymentReceipt'
          content:
            application/json:
              schema:
                type: object
                properties:
                  summary:
                    type: object
                    properties:
                      total:
                        type: integer
                      minor:
                        type: integer
                      moderate:
                        type: integer
                      major:
                        type: integer
                      belowMinor:
                        type: integer
                        description: Gauges with a current reading below the minor threshold.
                      stale:
                        type: integer
                      unclassified:
                        type: integer
                      atOrAboveMinor:
                        type: integer
                  groupBy:
                    type: string
                    enum:
                    - state
                    - lga
                  groups:
                    type: array
                    description: One entry per state (key state) or LGA (key lgaCode, or unassigned), with that group's total, minor, moderate, major, belowMinor, stale and unclassified counts.
                    items:
                      type: object
                  aboveMinorStations:
                    type: array
                    items:
                      $ref: '#/components/schemas/Gauge'
                  meta:
                    type: object
                    properties:
                      stationsEvaluated:
                        type: integer
                      truncated:
                        type: boolean
                        description: True when more gauges are at or above minor than aboveMinorStations lists (500 at most).
                      staleGuard:
                        type: string
                      generatedAt:
                        type: string
                        format: date-time
                  links:
                    type: object
                    properties:
                      self:
                        type: string
                  disclaimer:
                    type: string
                  attribution:
                    type: string
                    format: uri
        '402':
          description: 'Pay per request: no key was sent, so the answer is a price. The WWW-Authenticate header carries an MPP Payment challenge; pay it and send the request again with Authorization: Payment. Also sent, with a fresh price, when a payment fails its checks or its price has expired. Only while pay per request is on; otherwise a request without a key gets 401.'
          headers:
            WWW-Authenticate:
              $ref: '#/components/headers/PaymentChallenge'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
components:
  headers:
    PaymentReceipt:
      description: 'Sent only on the response to a paid request (Authorization: Payment): the receipt for the payment, naming its transaction. Never sent when a key was used.'
      schema:
        type: string
    PaymentChallenge:
      description: 'The MPP payment challenge, scheme Payment: the price, the token, where to pay, the realm (dataquoll.io) and when the price expires, 5 minutes after it is issued. Pay it with an MPP client and send the request again with Authorization: Payment.'
      schema:
        type: string
  schemas:
    ProblemDetails:
      type: object
      description: RFC 9457 Problem Details
      properties:
        type:
          type: string
          example: https://emergencyapi.com/errors/rate-limit-exceeded
        title:
          type: string
          example: Rate Limit Exceeded
        status:
          type: integer
          example: 429
        detail:
          type: string
        instance:
          type: string
    GaugeCollection:
      type: object
      properties:
        gauges:
          type: array
          items:
            $ref: '#/components/schemas/Gauge'
        meta:
          type: object
          properties:
            count:
              type: integer
            hasMore:
              type: boolean
            nextCursor:
              type: string
            generatedAt:
              type: string
              format: date-time
        links:
          type: object
          properties:
            self:
              type: string
        disclaimer:
          type: string
        attribution:
          type: string
    Gauge:
      type: object
      description: A gauge station with its latest reading. Water-level readings are metres relative to the gauge's local datum, not sea level; rainfall readings are incremental millimetres. floodClass, thresholds and datum are present only on water-level gauges.
      properties:
        id:
          type: string
          example: hydstra-nsw-410001
        name:
          type: string
        river:
          type:
          - string
          - 'null'
        state:
          type: string
          example: NSW
        agency:
          type:
          - string
          - 'null'
        source:
          type: string
        variable:
          type: string
          enum:
          - water_level
          - rainfall
          description: The measured variable. Rainfall gauges carry no floodClass, thresholds or datum.
        awrcStationNo:
          type:
          - string
          - 'null'
        coordinates:
          type: object
          properties:
            lat:
              type: number
            lng:
              type: number
        lga:
          type:
          - object
          - 'null'
          properties:
            code:
              type: string
            name:
              type:
              - string
              - 'null'
        latest:
          type:
          - object
          - 'null'
          properties:
            value:
              type: number
            observedAt:
              type: string
              format: date-time
            quality:
              type:
              - string
              - 'null'
        readingStatus:
          type: string
          enum:
          - live
          - stale
        unit:
          type: string
          description: Present on rainfall gauges (always 'mm'). Water-level gauges carry their unit inside thresholds.unit.
          example: mm
        floodClass:
          type: string
          enum:
          - below_minor
          - minor
          - moderate
          - major
          - unclassified
          description: Water-level gauges only. Derived at read time from the latest reading vs the published BoM thresholds; never stored as judgement.
        thresholds:
          type: object
          description: Water-level gauges only.
          properties:
            minor:
              type:
              - number
              - 'null'
            moderate:
              type:
              - number
              - 'null'
            major:
              type:
              - number
              - 'null'
            unit:
              type: string
            source:
              type:
              - string
              - 'null'
            version:
              type:
              - string
              - 'null'
            fetchedAt:
              type:
              - string
              - 'null'
              format: date-time
        datum:
          type:
          - object
          - 'null'
          description: Water-level gauges only.
          properties:
            gaugeZeroM:
              type:
              - number
              - 'null'
            datum:
              type:
              - string
              - 'null'
    GaugeReading:
      type: object
      description: A raw reading (observedAt/value/quality) or an aggregated bucket (bucket/min/max/mean/nObs), depending on the interval.
      properties:
        observedAt:
          type: string
          format: date-time
        value:
          type: number
        quality:
          type:
          - string
          - 'null'
        bucket:
          type: string
        min:
          type: number
        max:
          type: number
        mean:
          type: number
        nObs:
          type: integer
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: 'API key in format: eak_live_... . Keys work from any origin by default. A key can optionally be restricted to specific browser origins in the dashboard; a request from a browser origin not on the allowlist is rejected with 403. Requests without an Origin header (server-side) are never blocked by this.'
    PaymentAuth:
      type: http
      scheme: payment
      description: 'Pay per request with MPP (the Machine Payments Protocol), for an agent with no API key. Send the request with no Authorization header and the 402 response carries the price in its WWW-Authenticate header. Pay it in USDC.e on Tempo with an MPP client, then send the request again with `Authorization: Payment <credential>`; the response carries a Payment-Receipt header. Offered only on the operations that list it, and only while pay per request is on. A request with a Bearer key is never charged. Prices, receipts and refunds: https://docs.dataquoll.io/machine-payments'
x-service-info:
  docs:
    homepage: https://dataquoll.io
    apiReference: https://docs.dataquoll.io
    llms: https://dataquoll.io/llms.txt