swagger: '2.0'
info:
  title: CMR Search Capabilities STAC API
  version: 1.0.0
  description: CMR Search API
host: cmr.earthdata.nasa.gov
basePath: /search
schemes:
- https
consumes: []
produces: []
tags:
- name: STAC
  description: Extension to WFS3 Core to support STAC metadata model and search API
paths:
  /{providerId}/search:
    get:
      summary: Search STAC items with simple filtering.
      description: 'Retrieve Items matching filters. Intended as a shorthand API for simple queries.


        This method is optional, but you MUST implement `POST /stac/search` if you want to implement this method.'
      operationId: getSearchSTAC
      tags:
      - STAC
      parameters:
      - $ref: '#/components/parameters/providerId'
      - $ref: '#/components/parameters/bbox'
      - $ref: '#/components/parameters/datetime'
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/page'
      - $ref: '#/components/parameters/ids'
      - $ref: '#/components/parameters/collections'
      responses:
        '200':
          description: A feature collection.
          content:
            application/geo+json:
              schema:
                $ref: '#/components/schemas/itemCollection'
            text/html:
              schema:
                type: string
        default:
          description: An error occurred.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/exception'
            text/html:
              schema:
                type: string
    post:
      summary: Search STAC items with full-featured filtering.
      description: 'retrieve items matching filters. Intended as the standard, full-featured query API.


        This method is mandatory to implement if `GET /stac/search` is implemented. If this endpoint is implemented on a server, it is required to add a link with `rel` set to `search` to the `links` array in `GET /stac` that refers to this endpoint.'
      operationId: postSearchSTAC
      tags:
      - STAC
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/searchBody'
      responses:
        '200':
          description: A feature collection.
          content:
            application/geo+json:
              schema:
                $ref: '#/components/schemas/itemCollection'
            text/html:
              schema:
                type: string
        default:
          description: An error occurred.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/exception'
            text/html:
              schema:
                type: string
components:
  schemas:
    stac_extensions:
      title: STAC extensions
      type: array
      uniqueItems: true
      items:
        anyOf:
        - title: Reference to a JSON Schema
          type: string
          format: uri
        - title: Reference to a core extension
          type: string
    exception:
      type: object
      description: 'Information about the exception: an error code plus an optional description.'
      properties:
        code:
          type: string
        description:
          type: string
      required:
      - code
    datetimeFilter:
      description: An object representing a date+time based filter.
      type: object
      properties:
        datetime:
          $ref: '#/components/schemas/datetime'
    item:
      description: A GeoJSON Feature augmented with foreign members that contain values relevant to a STAC entity
      type: object
      required:
      - stac_version
      - id
      - type
      - geometry
      - bbox
      - links
      - properties
      - assets
      properties:
        stac_version:
          $ref: '#/components/schemas/stac_version'
        stac_extensions:
          $ref: '#/components/schemas/stac_extensions'
        id:
          $ref: '#/components/schemas/itemId'
        bbox:
          $ref: '#/components/schemas/bbox'
        geometry:
          $schema: http://json-schema.org/draft-07/schema#
          $id: https://geojson.org/schema/Geometry.json
          title: GeoJSON Geometry
          oneOf:
          - title: GeoJSON Point
            type: object
            required:
            - type
            - coordinates
            properties:
              type:
                type: string
                enum:
                - Point
              coordinates:
                type: array
                minItems: 2
                items:
                  type: number
              bbox:
                type: array
                minItems: 4
                items:
                  type: number
          - title: GeoJSON LineString
            type: object
            required:
            - type
            - coordinates
            properties:
              type:
                type: string
                enum:
                - LineString
              coordinates:
                type: array
                minItems: 2
                items:
                  type: array
                  minItems: 2
                  items:
                    type: number
              bbox:
                type: array
                minItems: 4
                items:
                  type: number
          - title: GeoJSON Polygon
            type: object
            required:
            - type
            - coordinates
            properties:
              type:
                type: string
                enum:
                - Polygon
              coordinates:
                type: array
                items:
                  type: array
                  minItems: 4
                  items:
                    type: array
                    minItems: 2
                    items:
                      type: number
              bbox:
                type: array
                minItems: 4
                items:
                  type: number
          - title: GeoJSON MultiPoint
            type: object
            required:
            - type
            - coordinates
            properties:
              type:
                type: string
                enum:
                - MultiPoint
              coordinates:
                type: array
                items:
                  type: array
                  minItems: 2
                  items:
                    type: number
              bbox:
                type: array
                minItems: 4
                items:
                  type: number
          - title: GeoJSON MultiLineString
            type: object
            required:
            - type
            - coordinates
            properties:
              type:
                type: string
                enum:
                - MultiLineString
              coordinates:
                type: array
                items:
                  type: array
                  minItems: 2
                  items:
                    type: array
                    minItems: 2
                    items:
                      type: number
              bbox:
                type: array
                minItems: 4
                items:
                  type: number
          - title: GeoJSON MultiPolygon
            type: object
            required:
            - type
            - coordinates
            properties:
              type:
                type: string
                enum:
                - MultiPolygon
              coordinates:
                type: array
                items:
                  type: array
                  items:
                    type: array
                    minItems: 4
                    items:
                      type: array
                      minItems: 2
                      items:
                        type: number
              bbox:
                type: array
                minItems: 4
                items:
                  type: number
        type:
          $ref: '#/components/schemas/itemType'
        properties:
          $ref: '#/components/schemas/itemProperties'
        links:
          type: array
          items:
            $ref: '#/components/schemas/link'
        assets:
          $ref: '#/components/schemas/itemAssets'
      example:
        stac_version: 1.0.0
        type: Feature
        id: CS3-20160503_132130_04
        bbox:
        - -122.59750209
        - 37.48803556
        - -122.2880486
        - 37.613537207
        geometry:
          type: Polygon
          coordinates:
          - - - -122.308150179
              - 37.488035566
            - - -122.597502109
              - 37.538869539
            - - -122.576687533
              - 37.613537207
            - - -122.2880486
              - 37.562818007
            - - -122.308150179
              - 37.488035566
        properties:
          datetime: '2016-05-03T13:21:30.040Z'
        links:
        - rel: self
          href: http://cool-sat.com/catalog/collections/cs/items/CS3-20160503_132130_04.json
        assets:
          analytic:
            title: 4-Band Analytic
            href: http://cool-sat.com/catalog/collections/cs/items/CS3-20160503_132130_04/analytic.tif
          thumbnail:
            title: Thumbnail
            href: http://cool-sat.com/catalog/collections/cs/items/CS3-20160503_132130_04/thumb.png
            type: image/png
    bboxFilter:
      type: object
      description: Only return items that intersect the provided bounding box.
      properties:
        bbox:
          $ref: '#/components/schemas/bbox'
    link:
      type: object
      properties:
        href:
          type: string
          example: http://www.geoserver.example/stac/naip/child/catalog.json
          format: url
        rel:
          type: string
          example: child
        type:
          type: string
          example: application/json
        hreflang:
          type: string
          example: en
        title:
          type: string
          example: NAIP Child Catalog
        length:
          type: integer
      title: Link
      description: A generic link.
      required:
      - href
      - rel
    bbox:
      description: "Only features that have a geometry that intersects the bounding box are\nselected. The bounding box is provided as four or six numbers,\ndepending on whether the coordinate reference system includes a\nvertical axis (elevation or depth):\n\n* Lower left corner, coordinate axis 1\n* Lower left corner, coordinate axis 2  \n* Lower left corner, coordinate axis 3 (optional) \n* Upper right corner, coordinate axis 1 \n* Upper right corner, coordinate axis 2 \n* Upper right corner, coordinate axis 3 (optional)\n\nThe coordinate reference system of the values is WGS84\nlongitude/latitude (http://www.opengis.net/def/crs/OGC/1.3/CRS84) unless\na different coordinate reference system is specified in the parameter\n`bbox-crs`.\n\nFor WGS84 longitude/latitude the values are in most cases the sequence\nof minimum longitude, minimum latitude, maximum longitude and maximum\nlatitude. However, in cases where the box spans the antimeridian the\nfirst value (west-most box edge) is larger than the third value\n(east-most box edge).\n\n\nIf a feature has multiple spatial geometry properties, it is the\ndecision of the server whether only a single spatial geometry property\nis used to determine the extent or all relevant geometries.\n"
      type: array
      minItems: 4
      maxItems: 6
      items:
        type: number
      example:
      - -110
      - 39.5
      - -105
      - 40.5
    intersectsFilter:
      type: object
      description: Only returns items that intersect with the provided polygon.
      properties:
        intersects:
          $ref: '#/components/schemas/item/properties/geometry'
    itemCollection:
      description: A GeoJSON FeatureCollection augmented with foreign members that contain values relevant to a STAC entity
      type: object
      required:
      - features
      - type
      properties:
        type:
          type: string
          enum:
          - FeatureCollection
        features:
          type: array
          items:
            $ref: '#/components/schemas/item'
        links:
          $ref: '#/components/schemas/itemCollectionLinks'
    itemProperties:
      type: object
      required:
      - datetime
      description: provides the core metatdata fields plus extensions
      properties:
        datetime:
          $ref: '#/components/schemas/datetime'
      additionalProperties:
        description: Any additional properties added in via Item specification or extensions.
    itemAssets:
      type: object
      additionalProperties:
        type: object
        required:
        - href
        properties:
          href:
            type: string
            format: url
            description: Link to the asset object
            example: http://cool-sat.com/catalog/collections/cs/items/CS3-20160503_132130_04/thumb.png
          title:
            type: string
            description: Displayed title
            example: Thumbnail
          type:
            type: string
            description: Media type of the asset
            example: image/png
    datetime:
      type: string
      description: 'Either a date-time or an interval, open or closed. Date and time expressions

        adhere to RFC 3339. Open intervals are expressed using double-dots.


        Examples:


        * A date-time: "2018-02-12T23:20:50Z"

        * A closed interval: "2018-02-12T00:00:00Z/2018-03-18T12:31:12Z"

        * Open intervals: "2018-02-12T00:00:00Z/.." or "../2018-03-18T12:31:12Z"


        Only features that have a temporal property that intersects the value of

        `datetime` are selected.


        If a feature has multiple temporal properties, it is the decision of the

        server whether only a single temporal property is used to determine

        the extent or all relevant temporal properties.'
      example: 2018-02-12T00:00:00Z/2018-03-18T12:31:12Z
    itemCollectionLinks:
      type: array
      description: An array of links. Can be used for pagination, e.g. by providing a link with the `next` relation type.
      items:
        $ref: '#/components/schemas/link'
      example:
      - rel: next
        href: http://api.cool-sat.com/stac/search?next=ANsXtp9mrqN0yrKWhf-y2PUpHRLQb1GT-mtxNcXou8TwkXhi1Jbk
    stac_version:
      title: STAC version
      type: string
      example: 1.0.0
    itemId:
      type: string
      example: path/to/example.tif
      description: Provider identifier, a unique ID, potentially a link to a file.
    itemType:
      type: string
      description: The GeoJSON type
      enum:
      - Feature
    searchBody:
      description: The search criteria
      type: object
      allOf:
      - $ref: '#/components/schemas/bboxFilter'
      - $ref: '#/components/schemas/datetimeFilter'
      - $ref: '#/components/schemas/intersectsFilter'
      - type: object
        properties:
          limit:
            type: integer
            example: 10
  parameters:
    bbox:
      name: bbox
      in: query
      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 (elevation or depth):


        * Lower left corner, coordinate axis 1

        * Lower left corner, coordinate axis 2

        * Lower left corner, coordinate axis 3 (optional)

        * Upper right corner, coordinate axis 1

        * Upper right corner, coordinate axis 2

        * Upper right corner, coordinate axis 3 (optional)


        The coordinate reference system of the values is WGS 84 longitude/latitude

        (http://www.opengis.net/def/crs/OGC/1.3/CRS84) unless a different coordinate

        reference system is specified in the parameter `bbox-crs`.


        For WGS 84 longitude/latitude the values are in most cases the sequence of

        minimum longitude, minimum latitude, maximum longitude and maximum latitude.

        However, in cases where the box spans the antimeridian the first value

        (west-most box edge) is larger than the third value (east-most box edge).


        If a feature has multiple spatial geometry properties, it is the decision of the

        server whether only a single spatial geometry property is used to determine

        the extent or all relevant geometries.'
      required: false
      schema:
        type: array
        minItems: 4
        maxItems: 6
        items:
          type: number
      style: form
      explode: false
    datetime:
      name: datetime
      in: query
      description: 'Either a date-time or an interval, open or closed. Date and time expressions

        adhere to RFC 3339. Open intervals are expressed using double-dots.


        Examples:


        * A date-time: "2018-02-12T23:20:50Z"

        * A closed interval: "2018-02-12T00:00:00Z/2018-03-18T12:31:12Z"

        * Open intervals: "2018-02-12T00:00:00Z/.." or "../2018-03-18T12:31:12Z"


        Only features that have a temporal property that intersects the value of

        `datetime` are selected.


        If a feature has multiple temporal properties, it is the decision of the

        server whether only a single temporal property is used to determine

        the extent or all relevant temporal properties.'
      required: false
      schema:
        type: string
      style: form
      explode: false
    limit:
      name: limit
      in: query
      description: 'The optional limit parameter limits the number of items that are presented in the response document.


        Only items are counted that are on the first level of the collection in the response document.

        Nested objects contained within the explicitly requested items shall not be counted.


        Minimum = 1. Maximum = 10000. Default = 10.'
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 10000
        default: 10
      style: form
      explode: false
    providerId:
      name: providerId
      in: path
      description: local identifier of a provider
      required: true
      schema:
        type: string
    page:
      name: page
      in: query
      description: 'The optional page parameter returns the specified page of results

        (with each page having size=limit).


        * Minimum = 1

        * Default = 1

        '
      required: false
      schema:
        type: integer
        minimum: 1
        default: 1
      style: form
      explode: false
    ids:
      name: ids
      in: query
      description: 'The optional ids parameter returns a FeatureCollection of all matching ids.

        If provided all other parameters that further restrict the number of search results (except `page` and `limit`) will be ignored.

        '
      required: false
      schema:
        type: array
        minItems: 1
        items:
          type: string
      explode: false
    collections:
      name: collections
      in: query
      description: 'The collections search parameter is a list of of collection IDs for Items to match.

        Only items that are included in one of these collections will be returned, otherwise

        all collections will be searched.

        '
      required: false
      schema:
        type: array
        minItems: 1
        items:
          type: string
      explode: false