openapi: 3.0.2
info:
  contact:
    name: US Geological Survey - Water Data for the Nation
    url: https://waterdata.usgs.gov
    x-ogc-serviceContact:
      addresses: []
      emails:
      - value: wdfn@usgs.gov
      hoursOfService: pointOfContact
      links:
      - href: https://waterdata.usgs.gov/questions-comments/?referrerUrl=https://api.waterdata.usgs.gov
        type: text/html
      name: WDFN Support
  description: 'These APIs provide OGC-compliant interfaces to USGS water data, letting you download continuous sensor measurements, discrete field measurements, metadata about monitoring locations, and more.

    '
  license:
    name: US Government work in the public domain
    url: https://creativecommons.org/publicdomain/zero/1.0/
  termsOfService: https://creativecommons.org/publicdomain/zero/1.0/
  title: USGS Water Data OGC APIs agency-codes countries API
  version: 0.56.0
  x-keywords:
  - geospatial
  - data
  - api
  - hydrology
  - USGS
servers:
- description: 'These APIs provide OGC-compliant interfaces to USGS water data, letting you download continuous sensor measurements, discrete field measurements, metadata about monitoring locations, and more.

    '
  url: https://api.waterdata.usgs.gov/ogcapi/v0
tags:
- description: 'FIPS country codes and names.

    '
  name: countries
paths:
  /collections/countries:
    get:
      description: 'FIPS country codes and names.

        '
      operationId: describeCountriesCollection
      parameters:
      - $ref: '#/components/parameters/f'
      - $ref: '#/components/parameters/lang'
      responses:
        '200':
          $ref: https://schemas.opengis.net/ogcapi/features/part1/1.0/openapi/ogcapi-features-1.yaml#/components/responses/Collection
        '400':
          $ref: https://schemas.opengis.net/ogcapi/features/part1/1.0/openapi/ogcapi-features-1.yaml#/components/responses/InvalidParameter
        '403':
          $ref: '#/components/responses/Forbidden403'
        '404':
          $ref: https://schemas.opengis.net/ogcapi/features/part1/1.0/openapi/ogcapi-features-1.yaml#/components/responses/NotFound
        '429':
          $ref: '#/components/responses/TooManyRequests429'
        '500':
          $ref: https://schemas.opengis.net/ogcapi/features/part1/1.0/openapi/ogcapi-features-1.yaml#/components/responses/ServerError
      summary: Get Country identifiers metadata
      tags:
      - countries
  /collections/countries/items:
    get:
      description: 'FIPS country codes and names.

        '
      operationId: getCountriesFeatures
      parameters:
      - description: The optional f parameter indicates the output format which the server shall provide as part of the response document.  The default format is GeoJSON.
        explode: false
        in: query
        name: f
        required: false
        schema:
          default: json
          enum:
          - json
          - html
          - jsonld
          - csv
          type: string
        style: form
      - $ref: '#/components/parameters/lang'
      - $ref: '#/components/parameters/bbox'
      - description: The optional limit parameter limits the number of items that are presented in the response document (maximum=50000, default=10000).
        explode: false
        in: query
        name: limit
        required: false
        schema:
          default: 10000
          maximum: 50000
          minimum: 1
          type: integer
        style: form
      - $ref: '#/components/parameters/crs'
      - $ref: '#/components/parameters/bbox-crs'
      - description: The properties that should be included. The parameter value is a comma-separated list of property names.
        explode: false
        in: query
        name: properties
        required: false
        schema:
          items:
            enum:
            - id
            - country_name
            type: string
          type: array
        style: form
      - $ref: '#/components/parameters/skipGeometry'
      - $ref: https://raw.githubusercontent.com/opengeospatial/ogcapi-records/master/core/openapi/parameters/sortby.yaml
      - $ref: '#/components/parameters/offset'
      - description: 'FIPS country code as defined by FIPS PUB 10-4: Countries, Dependencies, Areas of Special Sovereignty, and Their Principal Administrative Divisions.'
        explode: false
        in: query
        name: id
        required: false
        schema:
          description: 'FIPS country code as defined by FIPS PUB 10-4: Countries, Dependencies, Areas of Special Sovereignty, and Their Principal Administrative Divisions.'
          type: string
        style: form
      - description: Country name.
        explode: false
        in: query
        name: country_name
        required: false
        schema:
          description: Country name.
          type: string
        style: form
      - $ref: '#/components/parameters/filter'
      responses:
        '200':
          $ref: https://schemas.opengis.net/ogcapi/features/part1/1.0/openapi/ogcapi-features-1.yaml#/components/responses/Features
        '400':
          $ref: https://schemas.opengis.net/ogcapi/features/part1/1.0/openapi/ogcapi-features-1.yaml#/components/responses/InvalidParameter
        '403':
          $ref: '#/components/responses/Forbidden403'
        '404':
          $ref: https://schemas.opengis.net/ogcapi/features/part1/1.0/openapi/ogcapi-features-1.yaml#/components/responses/NotFound
        '429':
          $ref: '#/components/responses/TooManyRequests429'
        '500':
          $ref: https://schemas.opengis.net/ogcapi/features/part1/1.0/openapi/ogcapi-features-1.yaml#/components/responses/ServerError
      security:
      - ApiKeyQuery: []
      - ApiKeyHeader: []
      summary: Get Country identifiers items
      tags:
      - countries
    options:
      description: 'FIPS country codes and names.

        '
      operationId: optionsCountriesFeatures
      responses:
        '200':
          description: options response
      security:
      - ApiKeyQuery: []
      - ApiKeyHeader: []
      summary: Options for Country identifiers items
      tags:
      - countries
    post:
      description: 'FIPS country codes and names.

        '
      operationId: getCQL2CountriesFeatures
      requestBody:
        content:
          application/json:
            schema:
              $ref: https://schemas.opengis.net/cql2/1.0/cql2.json
        description: Get items with CQL2
        required: true
      responses:
        '200':
          $ref: https://schemas.opengis.net/ogcapi/features/part1/1.0/openapi/ogcapi-features-1.yaml#/components/responses/Features
        '400':
          $ref: https://schemas.opengis.net/ogcapi/features/part1/1.0/openapi/ogcapi-features-1.yaml#/components/responses/InvalidParameter
        '403':
          $ref: '#/components/responses/Forbidden403'
        '429':
          $ref: '#/components/responses/TooManyRequests429'
        '500':
          $ref: https://schemas.opengis.net/ogcapi/features/part1/1.0/openapi/ogcapi-features-1.yaml#/components/responses/ServerError
      security:
      - ApiKeyQuery: []
      - ApiKeyHeader: []
      summary: Get Country identifiers items with CQL2
      tags:
      - countries
  /collections/countries/items/{featureId}:
    get:
      description: 'FIPS country codes and names.

        '
      operationId: getCountriesFeature
      parameters:
      - $ref: https://schemas.opengis.net/ogcapi/features/part1/1.0/openapi/ogcapi-features-1.yaml#/components/parameters/featureId
      - $ref: '#/components/parameters/crs'
      - $ref: '#/components/parameters/f'
      - $ref: '#/components/parameters/lang'
      responses:
        '200':
          $ref: https://schemas.opengis.net/ogcapi/features/part1/1.0/openapi/ogcapi-features-1.yaml#/components/responses/Feature
        '400':
          $ref: https://schemas.opengis.net/ogcapi/features/part1/1.0/openapi/ogcapi-features-1.yaml#/components/responses/InvalidParameter
        '403':
          $ref: '#/components/responses/Forbidden403'
        '404':
          $ref: https://schemas.opengis.net/ogcapi/features/part1/1.0/openapi/ogcapi-features-1.yaml#/components/responses/NotFound
        '429':
          $ref: '#/components/responses/TooManyRequests429'
        '500':
          $ref: https://schemas.opengis.net/ogcapi/features/part1/1.0/openapi/ogcapi-features-1.yaml#/components/responses/ServerError
      security:
      - ApiKeyQuery: []
      - ApiKeyHeader: []
      summary: Get Country identifiers item by id
      tags:
      - countries
    options:
      description: 'FIPS country codes and names.

        '
      operationId: optionsCountriesFeature
      parameters:
      - $ref: https://schemas.opengis.net/ogcapi/features/part1/1.0/openapi/ogcapi-features-1.yaml#/components/parameters/featureId
      responses:
        '200':
          description: options response
      security:
      - ApiKeyQuery: []
      - ApiKeyHeader: []
      summary: Options for Country identifiers item by id
      tags:
      - countries
  /collections/countries/queryables:
    get:
      description: 'FIPS country codes and names.

        '
      operationId: getCountriesQueryables
      parameters:
      - description: The properties that should be included. The parameter value is a comma-separated list of property names.
        explode: false
        in: query
        name: properties
        required: false
        schema:
          items:
            enum:
            - id
            - country_name
            type: string
          type: array
        style: form
      - $ref: '#/components/parameters/f'
      - description: The profile to be applied to a given request
        explode: false
        in: query
        name: profile
        required: false
        schema:
          enum:
          - actual-domain
          - valid-domain
          type: string
        style: form
      - $ref: '#/components/parameters/lang'
      responses:
        '200':
          $ref: '#/components/responses/Queryables'
        '400':
          $ref: https://schemas.opengis.net/ogcapi/features/part1/1.0/openapi/ogcapi-features-1.yaml#/components/responses/InvalidParameter
        '403':
          $ref: '#/components/responses/Forbidden403'
        '404':
          $ref: https://schemas.opengis.net/ogcapi/features/part1/1.0/openapi/ogcapi-features-1.yaml#/components/responses/NotFound
        '429':
          $ref: '#/components/responses/TooManyRequests429'
        '500':
          $ref: https://schemas.opengis.net/ogcapi/features/part1/1.0/openapi/ogcapi-features-1.yaml#/components/responses/ServerError
      security:
      - ApiKeyQuery: []
      - ApiKeyHeader: []
      summary: Get Country identifiers queryables
      tags:
      - countries
  /collections/countries/schema:
    get:
      description: 'FIPS country codes and names.

        '
      operationId: getCountriesSchema
      parameters:
      - $ref: '#/components/parameters/f'
      - $ref: '#/components/parameters/lang'
      responses:
        '200':
          $ref: '#/components/responses/Queryables'
        '400':
          $ref: https://schemas.opengis.net/ogcapi/features/part1/1.0/openapi/ogcapi-features-1.yaml#/components/responses/InvalidParameter
        '403':
          $ref: '#/components/responses/Forbidden403'
        '404':
          $ref: https://schemas.opengis.net/ogcapi/features/part1/1.0/openapi/ogcapi-features-1.yaml#/components/responses/NotFound
        '429':
          $ref: '#/components/responses/TooManyRequests429'
        '500':
          $ref: https://schemas.opengis.net/ogcapi/features/part1/1.0/openapi/ogcapi-features-1.yaml#/components/responses/ServerError
      security:
      - ApiKeyQuery: []
      - ApiKeyHeader: []
      summary: Get Country identifiers schema
      tags:
      - countries
components:
  parameters:
    offset:
      description: The optional offset parameter indicates the index within the result set from which the server shall begin presenting results in the response document.  The first element has an index of 0 (default).
      explode: false
      in: query
      name: offset
      required: false
      schema:
        default: 0
        minimum: 0
        type: integer
      style: form
    skipGeometry:
      description: This option can be used to skip response geometries for each feature.
      explode: false
      in: query
      name: skipGeometry
      required: false
      schema:
        default: false
        type: boolean
      style: form
    f:
      description: The optional f parameter indicates the output format which the server shall provide as part of the response document.  The default format is GeoJSON.  CSV is also available.
      explode: false
      in: query
      name: f
      required: false
      schema:
        default: json
        enum:
        - json
        - html
        - jsonld
        - csv
        type: string
      style: form
    filter:
      description: "CQL Text filter expression.  CQL JSON cannot be used here, only in the body. \nSee also: https://docs.pygeoapi.io/en/latest/cql.html \n\nExample: time_series_id IN ('64ee32f5350a4ec4967435dcd2e364ea', '3e55d9c2d8a54bec9ca5e292b07d5a96')"
      in: query
      name: filter
      required: false
      schema:
        type: string
    lang:
      description: The optional lang parameter instructs the server return a response in a certain language, if supported.  If the language is not among the available values, the Accept-Language header language will be used if it is supported. If the header is missing, the default server language is used. Note that providers may only support a single language (or often no language at all), that can be different from the server language.  Language strings can be written in a complex (e.g. "fr-CA,fr;q=0.9,en-US;q=0.8,en;q=0.7"), simple (e.g. "de") or locale-like (e.g. "de-CH" or "fr_BE") fashion.
      in: query
      name: lang
      required: false
      schema:
        default: en-US
        enum:
        - en-US
        type: string
    crs:
      description: Indicates the coordinate reference system for the results.
      explode: false
      in: query
      name: crs
      required: false
      schema:
        format: uri
        type: string
      style: form
    bbox-crs:
      description: Indicates the coordinate reference system for the given bbox coordinates.
      explode: false
      in: query
      name: bbox-crs
      required: false
      schema:
        format: uri
        type: string
      style: form
    bbox:
      description: Only features that have a geometry that intersects the bounding box are selected.The bounding box is provided as four or six numbers, depending on whether the coordinate reference system includes a vertical axis (height or depth).
      explode: false
      in: query
      name: bbox
      required: false
      schema:
        items:
          type: number
        maxItems: 6
        minItems: 4
        type: array
      style: form
  responses:
    Queryables:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/queryables'
      description: successful queryables operation
    TooManyRequests429:
      content:
        application/json:
          examples:
            rateLimitExceeded:
              summary: Rate Limit Exceeded
              value:
                error:
                  code: OVER_RATE_LIMIT
                  message: You have exceeded your rate limit. Make sure you provided your API key from https://api.waterdata.usgs.gov/signup/, then either try again later or contact us at https://waterdata.usgs.gov/questions-comments/?referrerUrl=https://api.waterdata.usgs.gov for assistance.
          schema:
            $ref: '#/components/schemas/Error'
        application/xml:
          example: "&ltresponse&gt\n      &lterror&gt\n        &ltcode&gtOVER_RATE_LIMIT&lt/code&gt\n        &ltmessage&gtYou have exceeded your rate limit. Make sure you provided your API key from https://api.waterdata.usgs.gov/signup/, then either try again later or contact us at https://waterdata.usgs.gov/questions-comments/?referrerUrl=https://api.waterdata.usgs.gov for assistance.&lt/message&gt\n      &lt/error&gt\n    &lt/response&gt"
          schema:
            properties:
              response:
                properties:
                  error:
                    properties:
                      code:
                        type: string
                      message:
                        type: string
                    required:
                    - code
                    - message
                    type: object
                required:
                - error
                type: object
            type: object
        text/csv:
          examples:
            rateLimitCsv:
              summary: Rate Limit Exceeded (CSV)
              value: 'Error Code,Error Message

                OVER_RATE_LIMIT,You have exceeded your rate limit. Make sure you provided your API key from https://api.waterdata.usgs.gov/signup/, then either try again later or contact us at https://waterdata.usgs.gov/questions-comments/?referrerUrl=https://api.waterdata.usgs.gov for assistance.'
          schema:
            type: string
        text/html:
          examples:
            rateLimitHtml:
              summary: Rate Limit Exceeded (HTML)
              value: "&lthtml&gt\n      &ltbody&gt\n        &lth1&gtOVER_RATE_LIMIT&lt/h1&gt\n        &ltp&gtYou have exceeded your rate limit. Make sure you provided your API key from https://api.waterdata.usgs.gov/signup/, then either try again later or contact us at https://waterdata.usgs.gov/questions-comments/?referrerUrl=https://api.waterdata.usgs.gov for assistance.&lt/p&gt\n      &lt/body&gt\n    &lt/html&gt"
          schema:
            type: string
      description: Too Many Requests - Rate limit exceeded.
    Forbidden403:
      content:
        application/json:
          examples:
            missingApiKey:
              summary: Missing API Key
              value:
                error:
                  code: API_KEY_MISSING
                  message: No api_key was supplied. Get one at https://api.waterdata.usgs.gov/signup/
          schema:
            $ref: '#/components/schemas/Error'
        application/xml:
          example: "&ltresponse&gt\n      &lterror&gt\n        &ltcode&gtAPI_KEY_MISSING&lt/code&gt\n        &ltmessage&gtNo api_key was supplied. Get one at https://api.waterdata.usgs.gov/signup/&lt/message&gt\n      &lt/error&gt\n    &lt/response&gt"
          schema:
            properties:
              response:
                properties:
                  error:
                    properties:
                      code:
                        type: string
                      message:
                        type: string
                    required:
                    - code
                    - message
                    type: object
                required:
                - error
                type: object
            type: object
        text/csv:
          examples:
            missingApiKeyCsv:
              summary: Missing API Key (CSV)
              value: 'Error Code,Error Message

                API_KEY_MISSING, No api_key was supplied. Get one at https://api.waterdata.usgs.gov/signup/'
          schema:
            type: string
        text/html:
          examples:
            missingApiKeyHtml:
              summary: Missing API Key (HTML)
              value: "&lthtml&gt\n      &ltbody&gt\n        &lth1&gtAPI_KEY_MISSING&lt/h1&gt\n        &ltp&gtNo api_key was supplied. Get one at https://api.waterdata.usgs.gov/signup/&lt/p&gt\n      &lt/body&gt\n    &lt/html&gt"
          schema:
            type: string
      description: Forbidden - API key is missing or not authorized for this resource.
  schemas:
    Error:
      properties:
        error:
          properties:
            code:
              description: Error code such as OVER_RATE_LIMIT, see https://api.data.gov/docs/developer-manual/#general-web-service-errors
              type: string
            message:
              description: Error message
              type: string
          required:
          - code
          - message
          type: object
      type: object
    queryable:
      properties:
        description:
          description: a human-readable narrative describing the queryable
          type: string
        language:
          default: en
          description: the language used for the title and description
          type: string
        queryable:
          description: the token that may be used in a CQL predicate
          type: string
        title:
          description: a human readable title for the queryable
          type: string
        type:
          description: the data type of the queryable
          type: string
        type-ref:
          description: a reference to the formal definition of the type
          format: url
          type: string
      required:
      - queryable
      - type
      type: object
    queryables:
      properties:
        queryables:
          items:
            $ref: '#/components/schemas/queryable'
          type: array
      required:
      - queryables
      type: object
  securitySchemes:
    ApiKeyHeader:
      description: Providing your API key gives you higher rate limits when querying our APIs. You can obtain an API key at https://api.waterdata.usgs.gov/signup
      in: header
      name: api_key
      type: apiKey
    ApiKeyQuery:
      description: Providing your API key gives you higher rate limits when querying our APIs. You can obtain an API key at https://api.waterdata.usgs.gov/signup
      in: query
      name: api_key
      type: apiKey