openapi: 3.0.1
info:
  title: Harmony API conforming to OGC API - Coverages Capabilities Coverage API
  description: Harmony API for requesting coverages for a range of NASA EOSDIS data using thc OGC API - Coverages
  version: 1.0.0
servers:
- url: /{cmrCollectionId}/ogc-api-coverages/1.0.0
  description: Harmony server
  variables:
    cmrCollectionId:
      default: no-default-cmr-collection
      description: The CMR Collection ID for the dataset whose coverage is being accessed
tags:
- name: Coverage
  description: Access to data (coverage).
paths:
  /collections/{collectionId}/coverage:
    get:
      tags:
      - Coverage
      summary: (Not yet implemented) description of the coverage offering identified by {collectionId} including envelope
      description: Not yet implemented
      operationId: getCoverageOffering
      parameters:
      - name: collectionId
        in: path
        description: Identifier (name) of a specific collection
        required: true
        style: simple
        explode: false
        schema:
          type: string
      responses:
        '200':
          description: Information about the coverage collection.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/coverageOffering'
            text/html:
              schema:
                type: string
        default:
          $ref: '#/components/responses/default'
  /collections/{collectionId}/coverage/description:
    get:
      tags:
      - Coverage
      summary: (Not yet implemented) returns the whole coverage description consisting of domainset, rangetype, and metadata (but not the rangeset)
      description: Not yet implemented
      operationId: getCoverageDescription
      parameters:
      - name: collectionId
        in: path
        description: Identifier (name) of a specific collection
        required: true
        style: simple
        explode: false
        schema:
          type: string
      - name: subset
        in: query
        description: Not yet implemented
        required: false
        style: form
        explode: true
        schema:
          type: string
      responses:
        '200':
          description: A coverage description.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/coverageDescription'
            text/html:
              schema:
                type: string
        default:
          $ref: '#/components/responses/default'
  /collections/{collectionId}/coverage/domainset:
    get:
      tags:
      - Coverage
      summary: (Not yet implemented) retrieve a coverages domainset; use content negotiation to request HTML or GeoJSON
      description: Not yet implemented
      operationId: getCoverageDomainSet
      parameters:
      - name: collectionId
        in: path
        description: Identifier (name) of a specific collection
        required: true
        style: simple
        explode: false
        schema:
          type: string
      - name: subset
        in: query
        description: Not yet implemented
        required: false
        style: form
        explode: true
        schema:
          type: string
      responses:
        '200':
          description: A coverages domainset.
          content:
            application/json:
              schema:
                $ref: http://schemas.opengis.net/cis/1.1/json/coverage-schema.json#/definitions/domainSet
            text/html:
              schema:
                type: string
        default:
          $ref: '#/components/responses/default'
  /collections/{collectionId}/coverage/rangetype:
    get:
      tags:
      - Coverage
      summary: (Not yet implemented) retrieve a coverage's rangetype; use content negotiation to request HTML or GeoJSON
      description: Not yet implemented
      operationId: getCoverageRangeType
      parameters:
      - $ref: '#/components/parameters/collectionId'
      responses:
        '200':
          description: A coverage's rangetype.
          content:
            application/geo+json:
              schema:
                $ref: http://schemas.opengis.net/cis/1.1/json/coverage-schema.json#/definitions/rangeType
            text/html:
              schema:
                type: string
        default:
          $ref: '#/components/responses/default'
  /collections/{collectionId}/coverage/metadata:
    get:
      tags:
      - Coverage
      summary: (Not yet implemented) retrieve a coverage's metadata; use content negotiation to request HTML or GeoJSON
      description: Not yet implemented
      operationId: getCoverageMetadata
      parameters:
      - $ref: '#/components/parameters/collectionId'
      responses:
        '200':
          description: A coverage's metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/coverageMetadata'
            text/html:
              schema:
                type: string
        default:
          $ref: '#/components/responses/default'
  /collections/{collectionId}/coverage/rangeset:
    get:
      tags:
      - Coverage
      summary: Retrieve a coverage's rangeset
      description: Retrieve the coverage's rangeset, i.e. its data values in their native format
      operationId: getCoverageRangeset
      parameters:
      - $ref: '#/components/parameters/collectionId'
      - $ref: '#/components/parameters/outputCrs'
      - $ref: '#/components/parameters/subset'
      - $ref: '#/components/parameters/interpolation'
      - $ref: '#/components/parameters/scaleExtent'
      - $ref: '#/components/parameters/scaleSize'
      - $ref: '#/components/parameters/concatenate'
      - $ref: '#/components/parameters/granuleId'
      - $ref: '#/components/parameters/point'
      - $ref: '#/components/parameters/width'
      - $ref: '#/components/parameters/height'
      - $ref: '#/components/parameters/format'
      - $ref: '#/components/parameters/forceAsync'
      - $ref: '#/components/parameters/serviceId'
      - $ref: '#/components/parameters/maxResults'
      - $ref: '#/components/parameters/skipPreview'
      - $ref: '#/components/parameters/ignoreErrors'
      - $ref: '#/components/parameters/destinationUrl'
      - $ref: '#/components/parameters/granuleName'
      - $ref: '#/components/parameters/grid'
      - $ref: '#/components/parameters/extend'
      - $ref: '#/components/parameters/variable'
      - $ref: '#/components/parameters/average'
      - $ref: '#/components/parameters/label'
      - $ref: '#/components/parameters/pixelSubset'
      responses:
        '200':
          description: A coverage's range set.
          content:
            image/*:
              schema:
                $ref: '#/components/schemas/rangeSetImage'
            application/*:
              schema:
                $ref: '#/components/schemas/rangeSetImage'
        default:
          $ref: '#/components/responses/default'
    post:
      tags:
      - Coverage
      summary: Retrieve a coverage's rangeset
      description: Retrieve the coverage's rangeset, i.e. its data values in their native format
      operationId: postCoverageRangeset
      parameters:
      - $ref: '#/components/parameters/collectionId'
      - $ref: '#/components/parameters/outputCrs'
      - $ref: '#/components/parameters/subset'
      - $ref: '#/components/parameters/interpolation'
      - $ref: '#/components/parameters/scaleExtent'
      - $ref: '#/components/parameters/scaleSize'
      - $ref: '#/components/parameters/concatenate'
      - $ref: '#/components/parameters/granuleId'
      - $ref: '#/components/parameters/point'
      - $ref: '#/components/parameters/width'
      - $ref: '#/components/parameters/height'
      - $ref: '#/components/parameters/format'
      - $ref: '#/components/parameters/forceAsync'
      - $ref: '#/components/parameters/serviceId'
      - $ref: '#/components/parameters/maxResults'
      - $ref: '#/components/parameters/skipPreview'
      - $ref: '#/components/parameters/ignoreErrors'
      - $ref: '#/components/parameters/destinationUrl'
      - $ref: '#/components/parameters/granuleName'
      - $ref: '#/components/parameters/grid'
      - $ref: '#/components/parameters/extend'
      - $ref: '#/components/parameters/variable'
      - $ref: '#/components/parameters/average'
      - $ref: '#/components/parameters/label'
      - $ref: '#/components/parameters/pixelSubset'
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                shapefile:
                  type: string
                  format: binary
            encoding:
              shapefile:
                contentType: application/geo+json,application/shapefile+zip,application/vnd.google-earth.kml+xml
      responses:
        '200':
          description: A coverage's range set.
          content:
            image/*:
              schema:
                $ref: '#/components/schemas/rangeSetImage'
            application/*:
              schema:
                $ref: '#/components/schemas/rangeSetImage'
        default:
          $ref: '#/components/responses/default'
  /collections/{collectionId}/coverage/all:
    get:
      tags:
      - Coverage
      summary: (Not yet implemented) retrieve a coverages rangeset; use content negotiation to request HTML or GeoJSON
      description: Not yet implemented
      operationId: getCoverageAll
      parameters:
      - $ref: '#/components/parameters/collectionId'
      - $ref: '#/components/parameters/subset'
      - $ref: '#/components/parameters/rangeSubset'
      - $ref: '#/components/parameters/scaleFactor'
      - $ref: '#/components/parameters/scaleAxis'
      - $ref: '#/components/parameters/scaleSize'
      - $ref: '#/components/parameters/scaleExtent'
      - $ref: '#/components/parameters/subsettingCrs'
      - $ref: '#/components/parameters/outputCrs'
      - $ref: '#/components/parameters/interpolation'
      responses:
        '200':
          description: A full coverage.
          content:
            application/multipart+related:
              schema:
                $ref: '#/components/schemas/coverageMultipart'
            image/*:
              schema:
                $ref: '#/components/schemas/rangeSetImage'
            application/*:
              schema:
                $ref: '#/components/schemas/rangeSetImage'
            text/html:
              schema:
                type: string
        default:
          $ref: '#/components/responses/default'
components:
  parameters:
    subsettingCrs:
      name: subsettingcrs
      in: query
      description: specify the projection in which the subsets are expressed
      required: false
      style: form
      explode: true
      schema:
        type: string
    forceAsync:
      name: forceAsync
      in: query
      description: if "true", override the default API behavior and always treat the request as asynchronous
      required: false
      schema:
        type: string
    scaleExtent:
      name: scaleExtent
      in: query
      description: scale the resulting coverage either among one axis to a given extent
      required: false
      style: form
      explode: false
      schema:
        minItems: 4
        maxItems: 4
        type: array
        items:
          type: number
    grid:
      name: grid
      in: query
      description: 'the name of the output grid to use for regridding requests. The name must match the UMM

        grid name in the CMR.

        '
      required: false
      schema:
        type: string
    granuleId:
      name: granuleId
      in: query
      description: The CMR Granule ID for the granule which should be retrieved
      required: false
      style: form
      explode: true
      schema:
        type: array
        items:
          type: string
          minLength: 1
    ignoreErrors:
      name: ignoreErrors
      in: query
      description: 'if "true", continue processing a request to completion even if some items fail. If "false",

        immediately fail the request on the first failure. Defaults to true.

        '
      required: false
      schema:
        type: string
    serviceId:
      name: serviceId
      in: query
      description: Either the CMR concept ID or the name in services.yml for the UMM-S service chain to invoke. Useful for testing a service chain against a collection not yet configured for use with that service chain.
      required: false
      style: form
      explode: true
      schema:
        type: string
    subset:
      name: subset
      in: query
      description: ' get a subset of the coverage by slicing or trimming among one axis.  Harmony supports the axes "lat" and "lon" for spatial subsetting, and "time" for temporal, regardless of the names of those axes in the data files. Harmony also supports arbitrary dimension names for subsetting on numeric ranges for that dimension.

        Examples: - Subset to the lat/lon bounding box with southwest corner (-10, -10) and northeast corner (10, 10) subset=lat(-10:10)&subset=lon(-10:10) - Subset to all latitudes north of -10 degrees and all longitudes west of 10 degrees subset=lat(-10:*)&subset=lon(*:10) - Subset to only points with latitudes from -10 to 10 degrees, disregarding longitude subset=lat(-10:10) - Subset to the first month of 2020 subset=time("2020-01-01T00:00:00Z":"2020-02-01T00:00:00Z") - Subset on arbitrary dimension "vertical" with a value between 0 and 20 subset=vertical(0:20)

        For full syntax and examples, see https://github.com/opengeospatial/ogc_api_coverages/blob/master/standard/clause_9_subset.adoc'
      required: false
      style: form
      explode: true
      schema:
        type: array
        items:
          type: string
    collectionId:
      name: collectionId
      in: path
      description: 'Names or concept ids of the UMM-Var variables to be retrieved, or "all" to retrieve all variables within the CMR collection(s).

        Multiple variables may be retrieved by separating them with a comma.  This API interprets OGC "collections" to be

        equivalent to CMR "variables" which produces some overloading in the name.  In this document, a "collection" is

        a CMR / UMM-Var variable and a "CMR collection" is a CMR / UMM-C collection.'
      required: true
      style: simple
      explode: false
      schema:
        type: string
    outputCrs:
      name: outputcrs
      in: query
      description: reproject the output coverage to the given CRS.  Recognizes CRS types that can be inferred by gdal, including EPSG codes, Proj4 strings, and OGC URLs (http://www.opengis.net/def/crs/...)
      required: false
      style: form
      explode: true
      schema:
        type: string
    width:
      name: width
      in: query
      description: number of columns to return in the output coverage
      required: false
      schema:
        type: integer
        minimum: 1
    rangeSubset:
      name: rangeSubset
      in: query
      description: subset the resulting coverage by choosing and/or rearrange particular fields
      required: false
      style: form
      explode: true
      schema:
        type: string
    destinationUrl:
      name: destinationUrl
      in: query
      description: 'destination url specified by the client, currently only s3 link url is supported

        (e.g. s3://my-bucket-name/mypath) and will result in the job being run asynchronously

        '
      required: false
      schema:
        type: string
    height:
      name: height
      in: query
      description: number of rows to return in the output coverage
      required: false
      schema:
        type: integer
        minimum: 1
    scaleSize:
      name: scaleSize
      in: query
      description: scale the resulting coverage either among one axis to a given size
      required: false
      style: form
      explode: false
      schema:
        minItems: 2
        maxItems: 2
        type: array
        items:
          type: number
          minimum: 0
    maxResults:
      name: maxResults
      in: query
      description: limits the number of input granules processed in the request
      required: false
      schema:
        type: integer
        minimum: 1
    skipPreview:
      name: skipPreview
      in: query
      description: if "true", override the default API behavior and never auto-pause jobs
      required: false
      schema:
        type: string
    average:
      name: average
      in: query
      description: 'requests the data to be averaged over time or area

        '
      required: false
      schema:
        type: string
    point:
      name: point
      in: query
      description: 'Only collections that have a geometry that contains a spatial point are selected. The spatial point is provided as two numbers:

        * Longitude, coordinate axis 1 * Latitude, coordinate axis 2

        The coordinate reference system of the values is WGS84 longitude/latitude (http://www.opengis.net/def/crs/OGC/1.3/CRS84).

        '
      required: false
      style: form
      explode: false
      schema:
        maxItems: 2
        minItems: 2
        type: array
        items:
          type: number
    scaleAxis:
      name: scaleAxis
      in: query
      description: scale the resulting coverage either among one axis by a given factor
      required: false
      style: form
      explode: true
      schema:
        type: string
    concatenate:
      name: concatenate
      in: query
      description: requests results to be concatenated into a single result
      required: false
      schema:
        type: string
    granuleName:
      name: granuleName
      in: query
      description: 'passed to the CMR search as the readable_granule_name parameter. Supports * and ? wildcards

        for multiple and single character matches. Wildcards can be used any place in the name,

        but leading wildcards are discouraged as they require a lot of resources for the underlying

        search.

        '
      required: false
      style: form
      explode: true
      schema:
        type: array
        items:
          type: string
          minLength: 1
    label:
      name: label
      in: query
      description: 'the labels for the job

        '
      required: false
      style: form
      explode: true
      schema:
        type: array
        items:
          type: string
          minLength: 1
    scaleFactor:
      name: scaleFactor
      in: query
      description: scale the resulting coverage either among all axes by a given factor
      required: false
      style: form
      explode: true
      schema:
        type: string
    variable:
      name: variable
      in: query
      description: 'the names or concept ids of the variables to subset

        '
      required: false
      style: form
      explode: true
      schema:
        type: array
        items:
          type: string
          minLength: 1
    format:
      name: format
      in: query
      description: the output mime type to return
      required: false
      schema:
        type: string
        example:
        - application/x-zarr
        - image/tiff
        - image/png
    interpolation:
      name: interpolation
      in: query
      description: specify the interpolation method used during reprojection and scaling
      required: false
      style: form
      explode: true
      schema:
        type: string
    pixelSubset:
      name: pixelSubset
      in: query
      description: if "true", pixel subset will be performed by the service
      required: false
      schema:
        type: string
    extend:
      name: extend
      in: query
      description: 'the name or concept id of the variable to extend

        '
      required: false
      schema:
        type: string
  schemas:
    exception:
      required:
      - code
      type: object
      properties:
        code:
          type: string
        description:
          type: string
    coverageMetadata:
      type: string
    coverageMultipart:
      type: string
    rangeSetImage:
      type: string
    coverageDescription:
      type: string
    coverageOffering:
      type: string
  responses:
    default:
      description: An error occured.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/exception'
        text/html:
          schema:
            type: string