NOAA ERDDAP Discovery API

openapi: 3.2.0
info:
  title: ERDDAP REST Discovery API
  version: '2.23'
  description: 'OpenAPI specification for ERDDAP (Environmental Research Division''s Data

    Access Program), a scientific data server providing simple, consistent

    access to gridded and tabular scientific datasets.'
  contact:
    name: ERDDAP Project
    url: https://github.com/ERDDAP/erddap
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
servers:
- url: https://coastwatch.pfeg.noaa.gov/erddap
  description: NOAA CoastWatch West Coast Node (reference server)
- url: https://erddap.ioos.us/erddap
  description: US IOOS ERDDAP
- url: '{baseUrl}'
  description: Any ERDDAP server — replace with the instance base URL
  variables:
    baseUrl:
      default: https://coastwatch.pfeg.noaa.gov/erddap
      description: 'Base URL of any ERDDAP server, including the /erddap path segment

        if present (e.g. https://example.org/erddap).

        '
tags:
- name: Discovery
  description: Search and browse available datasets.
paths:
  /search/index.{fileType}:
    get:
      summary: Full-text search across all datasets
      operationId: searchDatasets
      tags:
      - Discovery
      description: 'Google-like search of dataset metadata. Words are matched separately

        (AND logic). Phrase search: `"wind speed"`. Exclude a word: `-salinity`.

        Case-insensitive; partial words are matched.'
      parameters:
      - $ref: '#/components/parameters/metadataFileType'
      - name: searchFor
        in: query
        required: true
        schema:
          type: string
        example: sea surface temperature
      - $ref: '#/components/parameters/page'
      - $ref: '#/components/parameters/itemsPerPage'
      responses:
        '200':
          description: Matching datasets.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DatasetList'
            text/csv:
              schema:
                type: string
  /search/advanced.{fileType}:
    get:
      summary: Advanced search with metadata and spatial/temporal filters
      operationId: searchDatasetsAdvanced
      tags:
      - Discovery
      description: 'Filter datasets by protocol, CDM data type, institution, IOOS category,

        CF standard name, variable name, bounding box, and time range.

        All filter parameters default to `(ANY)` (no filter applied).'
      parameters:
      - $ref: '#/components/parameters/metadataFileType'
      - name: searchFor
        in: query
        description: Free-text search terms (same syntax as simple search).
        schema:
          type: string
      - name: protocol
        in: query
        schema:
          type: string
          enum:
          - (ANY)
          - tabledap
          - griddap
          - wms
          - wcs
          default: (ANY)
      - name: cdm_data_type
        in: query
        description: CF Discrete Sampling Geometry type.
        schema:
          type: string
          enum:
          - (ANY)
          - Grid
          - TimeSeries
          - TimeSeriesProfile
          - Trajectory
          - TrajectoryProfile
          - Point
          - Profile
          - Other
          default: (ANY)
      - name: institution
        in: query
        schema:
          type: string
          default: (ANY)
      - name: ioos_category
        in: query
        description: IOOS data category (e.g. Temperature, Salinity, Currents).
        schema:
          type: string
          default: (ANY)
      - name: keywords
        in: query
        schema:
          type: string
          default: (ANY)
      - name: long_name
        in: query
        schema:
          type: string
          default: (ANY)
      - name: standard_name
        in: query
        description: CF standard name (e.g. sea_surface_temperature).
        schema:
          type: string
          default: (ANY)
      - name: variableName
        in: query
        description: Variable short name as it appears in the dataset.
        schema:
          type: string
          default: (ANY)
      - name: minLon
        in: query
        description: Western boundary (decimal degrees, -180 to 180).
        schema:
          type: number
          minimum: -180
          maximum: 180
      - name: maxLon
        in: query
        description: Eastern boundary (decimal degrees, -180 to 180).
        schema:
          type: number
          minimum: -180
          maximum: 180
      - name: minLat
        in: query
        description: Southern boundary (decimal degrees, -90 to 90).
        schema:
          type: number
          minimum: -90
          maximum: 90
      - name: maxLat
        in: query
        description: Northern boundary (decimal degrees, -90 to 90).
        schema:
          type: number
          minimum: -90
          maximum: 90
      - name: minTime
        in: query
        description: Earliest time (ISO 8601 or seconds since 1970-01-01T00:00:00Z).
        schema:
          type: string
        example: '2020-01-01T00:00:00Z'
      - name: maxTime
        in: query
        description: Latest time (ISO 8601 or seconds since 1970-01-01T00:00:00Z).
        schema:
          type: string
        example: '2020-12-31T23:59:59Z'
      - $ref: '#/components/parameters/page'
      - $ref: '#/components/parameters/itemsPerPage'
      responses:
        '200':
          description: Matching datasets.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DatasetList'
            text/csv:
              schema:
                type: string
  /info/index.{fileType}:
    get:
      summary: List all datasets available on this server
      operationId: listAllDatasets
      tags:
      - Discovery
      description: Returns every dataset the server exposes, with title, institution, and access URLs.
      parameters:
      - $ref: '#/components/parameters/metadataFileType'
      - $ref: '#/components/parameters/itemsPerPage'
      responses:
        '200':
          description: All datasets on this ERDDAP server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DatasetList'
            text/csv:
              schema:
                type: string
  /categorize/{attribute}/index.{fileType}:
    get:
      summary: List all distinct values for a metadata attribute
      operationId: listAttributeValues
      tags:
      - Discovery
      description: Returns every distinct value that appears for the given attribute across all datasets on this server.
      parameters:
      - $ref: '#/components/parameters/categorizeAttribute'
      - $ref: '#/components/parameters/metadataFileType'
      responses:
        '200':
          description: All distinct values for the attribute across this server's datasets.
  /categorize/{attribute}/{value}/index.{fileType}:
    get:
      summary: List datasets that match a specific metadata attribute value
      operationId: listDatasetsByAttribute
      tags:
      - Discovery
      description: Filters the full dataset list to those whose metadata contains the specified attribute value (case-insensitive).
      parameters:
      - $ref: '#/components/parameters/categorizeAttribute'
      - name: value
        in: path
        required: true
        description: The attribute value to filter by (case-insensitive).
        schema:
          type: string
        example: temperature
      - $ref: '#/components/parameters/metadataFileType'
      responses:
        '200':
          description: Datasets whose metadata matches the given attribute value.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DatasetList'
            text/csv:
              schema:
                type: string
components:
  parameters:
    itemsPerPage:
      name: itemsPerPage
      in: query
      description: Maximum number of results to return.
      schema:
        type: integer
        minimum: 1
        default: 1000000
    page:
      name: page
      in: query
      description: Page number (1-based).
      schema:
        type: integer
        minimum: 1
        default: 1
    metadataFileType:
      name: fileType
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/MetadataFileType'
    categorizeAttribute:
      name: attribute
      in: path
      required: true
      description: Metadata attribute to categorize by.
      schema:
        type: string
        enum:
        - cdm_data_type
        - institution
        - ioos_category
        - keywords
        - keywords_vocabulary
        - long_name
        - standard_name
        - variableName
  schemas:
    MetadataFileType:
      type: string
      description: Response format for discovery and metadata endpoints.
      enum:
      - html
      - csv
      - csvp
      - csv0
      - json
      - jsonlCSV1
      - jsonlCSV
      - jsonlKVP
      - tsv
      - tsvp
      - tsv0
      - xhtml
    DatasetList:
      type: object
      description: 'ERDDAP wraps all JSON responses in a `table` envelope with parallel

        `columnNames`, `columnTypes`, and `rows` arrays.

        '
      properties:
        table:
          type: object
          required:
          - columnNames
          - columnTypes
          - rows
          properties:
            columnNames:
              type: array
              items:
                type: string
              example:
              - griddap
              - Subset
              - tabledap
              - Make A Graph
              - wms
              - files
              - Accessible
              - Title
              - Summary
              - FGDC
              - ISO 19115
              - Info
              - Background Info
              - RSS
              - Email
              - Institution
              - ID
            columnTypes:
              type: array
              items:
                type: string
              example:
              - String
              - String
              - String
              - String
              - String
              - String
              - String
              - String
              - String
              - String
              - String
              - String
              - String
              - String
              - String
              - String
              - String
            rows:
              type: array
              description: One array per dataset; values correspond to columnNames.
              items:
                type: array
                items: {}