NOAA ERDDAP Discovery API

openapi: 3.1.0
info:
  title: ERDDAP REST Data Access Discovery API
  version: '2.23'
  description: "OpenAPI specification for ERDDAP (Environmental Research Division's Data\nAccess Program), a scientific data server providing simple, consistent\naccess to gridded and tabular scientific datasets.\n\nERDDAP runs at many institutions worldwide. Set the server URL to the base\nURL of the instance you want to access.\n\n## Two-phase workflow for data access\n\n1. **Discover** — search for datasets (`/search/`) or list all (`/info/index.json`).\n2. **Inspect** — fetch dataset metadata (`/info/{datasetID}/index.json`) to learn\n   variable names, data types, units, and coordinate ranges.\n3. **Download** — request data from `/tabledap/` or `/griddap/` using the\n   variable names and constraint ranges discovered in step 2.\n\n## Constraint syntax (tabledap and griddap)\n\nConstraints are appended to the query string as `&varName>=value` pairs.\n\n| Operator | Meaning |\n|----------|---------|\n| `=`  | equals |\n| `!=` | not equals |\n| `<`, `<=`, `>`, `>=` | numeric / time comparison |\n| `=~` | Java regular expression match |\n\nString values must be double-quoted: `&stationType=\"fixed\"`.\nTime values can be ISO 8601 (`2020-01-01T00:00:00Z`), seconds since\n1970-01-01 (Unix epoch), or relative expressions (`now-7days`, `now-1hour`).\nSpatial relative extremes are also supported: `&latitude<min(latitude)+10`.\n\n## Response format selection\n\nThe desired format is embedded in the path (`.json`, `.csv`, `.nc`, etc.)\nrather than in an `Accept` header. See the `MetadataFileType` and\n`DataFileType` schemas for the full list.\n"
  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:
  schemas:
    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: {}
    MetadataFileType:
      type: string
      description: Response format for discovery and metadata endpoints.
      enum:
      - html
      - csv
      - csvp
      - csv0
      - json
      - jsonlCSV1
      - jsonlCSV
      - jsonlKVP
      - tsv
      - tsvp
      - tsv0
      - xhtml
  parameters:
    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
    itemsPerPage:
      name: itemsPerPage
      in: query
      description: Maximum number of results to return.
      schema:
        type: integer
        minimum: 1
        default: 1000000
    metadataFileType:
      name: fileType
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/MetadataFileType'
    page:
      name: page
      in: query
      description: Page number (1-based).
      schema:
        type: integer
        minimum: 1
        default: 1