STAC-fragment.yaml

paths:
  /search/stac:
    get:
      summary: >-
        retrieve items matching filters. Intended as a shorthand API for simple queries.
        This method is optional.
      operationId: getSearchSTAC
      tags:
        - STAC
      parameters:
      - $ref: '#/components/parameters/bbox'
      - $ref: '#/components/parameters/time'
      - $ref: '#/components/parameters/limit'
      responses:
        '200':
          description: A feature collection.
          content:
            application/geo+json:
              schema:
                $ref: '#/components/schemas/itemCollection'
            text/html:
              schema:
                type: string
        default:
          description: An error occured.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/exception'
            text/html:
              schema:
                type: string
    post:
      summary: >- 
        retrieve items matching filters. Intended as the standard, full-featured
        query API. This method is mandatory.
      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 occured.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/exception'
            text/html:
              schema:
                type: string
components:
  parameters:
    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
    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 WGS84
        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 WGS84 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:
        $ref: '#/components/schemas/bbox'
      style: form
      explode: false
    time:
      name: time
      in: query
      description: >-
        Either a date-time or a period string that adheres to RFC3339. Examples:
        * A date-time: "2018-02-12T23:20:50Z"
        * A period: "2018-02-12T00:00:00Z/2018-03-18T12:31:12Z" or "2018-02-12T00:00:00Z/P1M6DT12H31M12S"
        Only features that have a temporal property that intersects the value of
        `time` 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
  schemas:
    searchBody:
      description: The search criteria
      type: object
      allOf:
        - $ref: '#/components/schemas/bboxFilter'
        - $ref: '#/components/schemas/timeFilter'
        - $ref: '#/components/schemas/intersectsFilter'
      example:
        bbox:
        - -110
        - 39
        - -105
        - 41
        time: "2018-03-15T00:00:00.000Z"
    bboxFilter:
      type: object
      description: Only return items that intersect the provided bounding box.
      properties:
        bbox:
          $ref: '#/components/parameters/bbox'
    timeFilter:
      description: An object representing a time based filter.
      type: object
      properties:
        time:
          $ref: '#/components/parameters/time'
    intersectsFilter:
      type: object
      description: Only returns items that intersect with the provided polygon.
      properties:
        intersects:
          $ref: '#/components/schemas/polygon'
    polygon:
      type: object
      properties:
        type:
          type: string
          enum:
            - polygon
        coordinates:
          $ref: '#/components/schemas/polygon2D'
      required:
        - type
        - coordinates
    polygon2D:
      type: array
      minItems: 1
      items:
        $ref: '#/components/schemas/linearRing2D'
    linearRing2D:
      type: array
      minItems: 4
      items:
        $ref: '#/components/schemas/point2D'
      example:
        - - -104
          - 35
        - - -103
          - 35
        - - -103
          - 34
        - - -104
          - 34
        - - -104
          - 35
    point2D:
      description: A 2d geojson point
      type: array
      minimum: 2
      maximum: 2
      items:
        type: number
        format: double
      example:
        - -104
        - 35
    time:
      type: string
      description: >-
        A single date-time string that adheres to RFC3339, for example
        1985-04-12T23:20:50.52Z
    itemCollection:
      type: object
      required:
        - features
        - type
      properties:
        type:
          type: string
          enum:
            - FeatureCollection
        features:
          type: array
          items:
            $ref: '#/components/schemas/item'
        links:
          $ref: '#/components/schemas/itemCollectionLinks'
    item:
      type: object
      required:
        - id
        - type
        - geometry
        - links
        - properties
        - assets
      properties:
        id:
          type: string
          example: path/to/example.tif
          description: 'unique ID, potentially link to file'
        bbox:
          $ref: '#/components/parameters/bbox'
        geometry:
          type: object
          description: footprint of the item
        type:
          type: string
          description: The GeoJSON type
          enum:
            - Feature
        properties:
          $ref: '#/components/schemas/itemProperties'
        links:
          type: object
          additionalProperties:
            type: object
            required:
              - href
              - rel
            properties:
              href:
                type: string
              rel:
                type: string
        assets:
          type: object
          additionalProperties:
            type: object
            required:
              - href
            properties:
              href:
                type: string
              name:
                type: string
      example:
        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'
          provider: 'http://www.cool-sat.com'
          license: CC-BY-4.0
        links:
          self:
            rel: self
            href: >-
              http://cool-sat.com/catalog/collections/cs/items/CS3-20160503_132130_04.json
        assets:
          analytic:
            name: 4-Band Analytic
            href: >-
              http://cool-sat.com/catalog/collections/cs/items/CS3-20160503_132130_04/analytic.tif
          thumbnail:
            name: thumbnail
            href: >-
              http://cool-sat.com/catalog/collections/cs/items/CS3-20160503_132130_04/thumb.png
    itemProperties:
      type: object
      required:
        - datetime
      description: provides the core metatdata fields plus extensions
      properties:
        datetime:
          $ref: '#/components/schemas/time'
        provider:
          type: string
          description: Information about the provider
        license:
          type: string
          description: Data license name based on SPDX License List
      additionalProperties:
        type: object
    itemCollectionLinks:
      type: object
      properties:
        next:
          type: string
          format: url
          description: >-
            A URL to obtain the next paginated data set. If not present, the
            client should utilize the `nextPageToken`.
          example: http://api.cool-sat.com/query/gasd312fsaeg/ANsXtp9mrqN0yrKWhf-y2PUpHRLQb1GT-mtxNcXou8TwkXhi1Jbk
tags:
  - name: STAC
    description: 'Extension to WFS3 Core to support STAC metadata model and search API'