api-spec/spec.yaml

swagger: '2.0'
info:
  title: An API for SpatioTemporal Asset Catalogs
  version: 0.0.3
  description: >-
    The SpatioTemporal Asset Catalog specification aims to standardize the way
    geospatial assets are exposed online and queried.  A 'spatiotemporal asset'
    is any file that represents information about the earth captured in a
    certain space and time. Most of the initial  use cases are related to
    imagery, but the api is designed to enable search of any spatiotemporal data
    items. SpatioTemporal Asset Catalogs  can be completely static, implemented
    as flat files on the web that can be crawled. This API has the same
    responses as a static catalog, but also offers querying capabilities in
    addition to exposing data online. This API was inspired by  WFS 3.0, and the
    goal is to make it compatible with that specification.


    WARNING - THIS IS WORK IN PROGRESS. Implementations are encouraged, but
    please give feedback on github.

    TODO - Update responses to be in line with static catalogs, give example

    TODO - Add in schema responses

    TODO - Explain extensibility, how to return different content & operations

    TODO - Add the querying capabilities
  contact:
    name: STAC Spec Contributors
    email: stac-spec@googlegroups.com
    url: 'https://github.com/radiantearth/stac-spec/'
  license:
    name: CC-BY 4.0 license
    url: 'https://creativecommons.org/licenses/by/4.0/'
schemes:
  - http
host: data.example.org
basePath: /
paths:
  /api:
    get:
      summary: the API description - this document
      operationId: getApiDescription
      tags:
        - Capabilities
      produces:
        - application/json
      responses:
        '200':
          description: >-
            The formal documentation of this API according to the OpenAPI
            specification, version 3.0. I.e., this document.
          schema:
            type: object
        default:
          description: An error occured.
          schema:
            $ref: '#/definitions/exception'
  /items:
    get:
      summary: Retrieve STAC compliant Items matching filters
      description: >-
        Returns a pageable GeoJSON feature collection of the Items matching the
        query
      operationId: getItems
      tags:
        - Items
      parameters:
        - $ref: '#/parameters/bbox'
        - $ref: '#/parameters/time'
        - $ref: '#/parameters/filter'
        - $ref: '#/parameters/limit'
        - $ref: '#/parameters/next'
      produces:
        - application/geo+json
      responses:
        '200':
          description: Description here
          schema:
            $ref: '#/definitions/ItemCollection'
        default:
          description: An error occured.
          schema:
            $ref: '#/definitions/exception'
    post:
      summary: >-
        Retrieve items matching filters. The request is a string that matches
        the GET query exactly. POST is primarily to be used when the request
        length exceeds GET maximums (which is not uncommon with geospatial
        queries)
      operationId: getItemsPost
      tags:
        - Items
      produces:
        - application/geo+json
      responses:
        '200':
          description: >-
            Returns a pageable GeoJSON feature collection of the items matching
            the query
          schema:
            $ref: '#/definitions/ItemCollection'
        default:
          description: An error occured.
          schema:
            $ref: '#/definitions/exception'
  '/items/{id}':
    get:
      summary: Retreive item by id
      operationId: getItem
      tags:
        - Items
      parameters:
        - $ref: '#/parameters/id'
      produces:
        - application/geo+json
      responses:
        '200':
          description: An item.
          schema:
            $ref: '#/definitions/Item'
        '404':
          description: 'The item with id {id} does not exist.'
          schema:
            $ref: '#/definitions/exception'
        default:
          description: An error occured.
          schema:
            $ref: '#/definitions/exception'
parameters:
  next:
    name: next
    in: query
    type: string
    description: Token for the next set of paginated data.
  limit:
    name: limit
    in: query
    type: integer
    description: Defines the maximum number or results retruned by the API
  time:
    name: time
    type: array
    description: An array of date-time strings that adheres to RFC3339 (for example 1985-04-12T23:20:50.52Z). One date-time in the array is the time to match. Two date-times represent a range. Any additional items in the array will be ignored.
    items:
      type: string
    in: query
    collectionFormat: csv
  bbox:
    name: bbox
    in: query
    description: >-
      Only items that have a geometry that intersects the bounding box are
      selected. The bounding box is provided as four numbers, in longitude & latitude:

      * West, South, East, North
    type: array
    items:
      type: number
      minItems: 4
      maxItems: 4
      minimum: -180
      maximum: 180
    collectionFormat: csv
  filter:
    name: filter
    in: query
    type: string
    description: A placeholder for a future filter implementation. The queryl language is still to be determined.
  id:
    name: id
    in: path
    description: The id of an item
    required: true
    type: string
definitions:
  exception:
    type: object
    required:
      - code
    properties:
      code:
        type: string
      description:
        type: string
  bbox:
    description: 'West, South, East, North'
    type: array
    items:
      minItems: 4
      maxItems: 4
      type: number
      minimum: -180
      maximum: 180
    example:
      - -180
      - -90
      - 180
      - 90
  link:
    type: object
    required:
      - href
    properties:
      href:
        type: string
      rel:
        type: string
        example: prev
      type:
        type: string
        example: application/geo+json
      hreflang:
        type: string
        example: en
  ItemCollection:
    type: object
    required:
      - features
      - type
    properties:
      type:
        type: string
        enum:
          - FeatureCollection
      features:
        type: array
        items:
          $ref: '#/definitions/Item'
      nextPageToken:
        type: string
        description: A token to obtain the next paginated data set
        example: ANsXtp9mrqN0yrKWhf-y2PUpHRLQb1GT-mtxNcXou8TwkXhi1Jbk
      links:
        $ref: '#/definitions/ItemCollectionLinks'
  Item:
    type: object
    required:
      - id
      - type
      - geometry
      - links
      - properties
    properties:
      id:
        type: string
        example: path/to/example.tif
        description: 'unique ID, potentially link to file'
      bbox:
        $ref: '#/definitions/bbox'
      geometry:
        type: object
        description: footprint of the item
      type:
        type: string
        description: The GeoJSON type
        enum:
          - Feature
      properties:
        $ref: '#/definitions/ItemProperties'
      links:
        $ref: '#/definitions/ItemLinks'
    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:
        start: '2016-05-03T13:21:30.040Z'
        end: '2016-05-03T13:21:30.410Z'
        provider: 'http://www.cool-sat.com'
        license: CC-BY-4.0
      links:
        - rel: self
          href: 'http://cool-sat.com/catalog/CS3-20160503_132130_04/CS3-20160503_132130_04.json'
        - rel: thumbnail
          href: 'http://cool-sat.com/catalog/CS3-20160503_132130_04/thumbnail.png'
      assets:
        - href: relative-path/to/analytic.tif
          name: 4-Band Analytic
  ItemProperties:
    type: object
    required:
      - start
      - end
    description: provides the core metatdata fields plus extensions
    properties:
      start:
        $ref: '#/definitions/Time'
      end:
        $ref: '#/definitions/Time'
      provider:
        type: string
        description: Information about the provider
      license:
        type: string
        description: Data license name based on SPDX License List
    additionalProperties:
      type: object
  ItemLinks:
    type: object
    required:
      - self
      - thumbnail
    properties:
      self:
        type: string
      thumbnail:
        type: string
  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
  Time:
    type: string
    description: A single date-time string that adheres to RFC3339, for example 1985-04-12T23:20:50.52Z
  StringSet:
    type: array
    items:
      type: string
  Int64Set:
    type: array
    items:
      type: integer
      format: int64
  TimeRange:
    description: begin and end timestamps adhering to RFC3339
    properties:
      begin:
        type: string
      end:
        type: string
  Int64Range:
    description: An integer range with begin and end
    properties:
      begin:
        type: integer
        format: int64
      end:
        type: integer
        format: int64
  DoubleRange:
    description: A double range with begin and end
    properties:
      begin:
        type: number
        format: double
      end:
        type: number
        format: double
  Doc:
    description: Arbitrary json document
    additionalProperties:
      type: object
  GeoJson:
    description: root geojson object
    properties:
      type:
        $ref: '#/definitions/ItemType'
    required:
      - type
    discriminator: type
  ItemType:
    type: string
    enum:
      - Point
      - MultiPoint
      - LineString
      - MultiLineString
      - Polygon
      - MultiPolygon
      - GeometryCollection
      - Item
      - ItemCollection
  GeometryCollection:
    allOf:
      - $ref: '#/definitions/GeoJson'
      - type: object
        properties:
          geometries:
            $ref: '#/definitions/GeometryCollection2D'
        required:
          - geometries
  MultiPolygon:
    allOf:
      - $ref: '#/definitions/GeoJson'
      - type: object
        properties:
          coordinates:
            $ref: '#/definitions/MultiPolygon2D'
        required:
          - coordinates
  MultiLineString:
    allOf:
      - $ref: '#/definitions/GeoJson'
      - type: object
        properties:
          coordinates:
            $ref: '#/definitions/MultiLineString2D'
        required:
          - coordinates
  MultiPoint:
    allOf:
      - $ref: '#/definitions/GeoJson'
      - type: object
        properties:
          coordinates:
            $ref: '#/definitions/MultiPoint2D'
        required:
          - coordinates
  Polygon:
    allOf:
      - $ref: '#/definitions/GeoJson'
      - type: object
        properties:
          coordinates:
            $ref: '#/definitions/Polygon2D'
        required:
          - coordinates
  LineString:
    allOf:
      - $ref: '#/definitions/GeoJson'
      - type: object
        properties:
          coordinates:
            $ref: '#/definitions/LineString2D'
        required:
          - coordinates
  Point:
    allOf:
      - $ref: '#/definitions/GeoJson'
      - type: object
        properties:
          coordinates:
            $ref: '#/definitions/Point2D'
        required:
          - coordinates
  GeoPolygon2D:
    description: A geojson 2d polygon
    type: object
    properties:
      type:
        description: Type of geometry
        type: string
        enum:
          - Polygon
      coordinates:
        $ref: '#/definitions/Polygon2D'
    required:
      - type
      - coordinates
  GeometryCollection2D:
    type: array
    items:
      $ref: '#/definitions/GeoJson'
  MultiPolygon2D:
    type: array
    items:
      $ref: '#/definitions/Polygon2D'
  Polygon2D:
    type: array
    minItems: 1
    items:
      $ref: '#/definitions/LinearRing2D'
  MultiLineString2D:
    type: array
    items:
      $ref: '#/definitions/LineString2D'
  LinearRing2D:
    type: array
    minItems: 4
    items:
      $ref: '#/definitions/Point2D'
  LineString2D:
    type: array
    minItems: 2
    items:
      $ref: '#/definitions/Point2D'
  MultiPoint2D:
    type: array
    minItems: 2
    items:
      $ref: '#/definitions/Point2D'
  Point2D:
    description: A 2d geojson point
    type: array
    minimum: 2
    maximum: 2
    items:
      type: number
      format: double
tags:
  - name: Capabilities
    description: >-
      Essential characteristics of this API including information about the
      data.
  - name: Items
    description: Access to data (items).