openapi: 3.0.3
info:
  title: USGS Earthquake Catalog Collections Monitoring Locations API
  description: The USGS Earthquake Catalog API is an implementation of the FDSN Event Web Service Specification, providing real-time and historical access to earthquake catalog data from the USGS National Earthquake Information Center (NEIC) and contributing networks. The API allows queries by location, time, magnitude, depth, and other parameters with results in multiple formats.
  version: '1.0'
  contact:
    email: eq_questions@usgs.gov
    url: https://earthquake.usgs.gov/fdsnws/event/1/
  license:
    name: US Government Work
    url: https://www.usa.gov/government-works
servers:
- url: https://earthquake.usgs.gov/fdsnws/event/1
  description: USGS Earthquake Catalog Production Server
tags:
- name: Monitoring Locations
  description: Geographic and metadata for USGS monitoring stations
paths:
  /collections/monitoring-locations/items:
    get:
      operationId: queryMonitoringLocations
      summary: Query Monitoring Locations
      description: Returns geographic and identification information for USGS water monitoring stations including names, identifiers, coordinates, and hydrologic unit codes.
      tags:
      - Monitoring Locations
      parameters:
      - $ref: '#/components/parameters/bboxParam'
      - $ref: '#/components/parameters/limitParam'
      - $ref: '#/components/parameters/offsetParam'
      - $ref: '#/components/parameters/filterParam'
      - $ref: '#/components/parameters/formatParam'
      - name: monitoringLocationIdentifier
        in: query
        description: USGS monitoring location identifier
        required: false
        schema:
          type: string
      - name: monitoringLocationType
        in: query
        description: Type of monitoring location (e.g., Stream, Lake, Well)
        required: false
        schema:
          type: string
      - name: stateCd
        in: query
        description: Two-letter state abbreviation
        required: false
        schema:
          type: string
      - name: countyCd
        in: query
        description: County FIPS code
        required: false
        schema:
          type: string
      - name: hucCd
        in: query
        description: Hydrologic Unit Code (HUC)
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Monitoring location features
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FeatureCollection'
        '400':
          description: Bad request
        '403':
          $ref: '#/components/responses/Unauthorized'
  /collections/monitoring-locations/items/{featureId}:
    get:
      operationId: getMonitoringLocation
      summary: Get Monitoring Location
      description: Returns details for a single USGS water monitoring location by feature ID.
      tags:
      - Monitoring Locations
      parameters:
      - name: featureId
        in: path
        description: Unique feature identifier for the monitoring location
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/formatParam'
      responses:
        '200':
          description: Monitoring location feature
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Feature'
        '404':
          description: Feature not found
        '403':
          $ref: '#/components/responses/Unauthorized'
components:
  schemas:
    Feature:
      type: object
      properties:
        type:
          type: string
          enum:
          - Feature
        id:
          type: string
          description: Unique feature identifier
        geometry:
          type: object
          nullable: true
          description: GeoJSON geometry object
        properties:
          type: object
          description: Feature properties
    FeatureCollection:
      type: object
      properties:
        type:
          type: string
          enum:
          - FeatureCollection
        features:
          type: array
          items:
            $ref: '#/components/schemas/Feature'
        numberMatched:
          type: integer
          description: Total number of features matching the query
        numberReturned:
          type: integer
          description: Number of features returned in this response
        links:
          type: array
          items:
            $ref: '#/components/schemas/Link'
    ApiError:
      type: object
      properties:
        code:
          type: string
          description: Error code
          enum:
          - API_KEY_MISSING
          - OVER_RATE_LIMIT
        message:
          type: string
          description: Human-readable error message
    Link:
      type: object
      properties:
        href:
          type: string
          description: URL of the link
        rel:
          type: string
          description: Link relation type
        type:
          type: string
          description: Media type
        title:
          type: string
          description: Human-readable title
  parameters:
    bboxParam:
      name: bbox
      in: query
      description: Bounding box for spatial filtering (minLon,minLat,maxLon,maxLat)
      required: false
      schema:
        type: array
        items:
          type: number
        minItems: 4
        maxItems: 6
      style: form
      explode: false
    offsetParam:
      name: offset
      in: query
      description: Starting offset for pagination
      required: false
      schema:
        type: integer
        minimum: 0
        default: 0
    filterParam:
      name: filter
      in: query
      description: CQL2 text filter expression for advanced querying
      required: false
      schema:
        type: string
    limitParam:
      name: limit
      in: query
      description: Maximum number of features to return
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 10000
        default: 100
    formatParam:
      name: f
      in: query
      description: Response format
      required: false
      schema:
        type: string
        enum:
        - json
        - html
        - jsonld
        - csv
        default: json
  responses:
    Unauthorized:
      description: API key missing or invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'