openapi: 3.0.3
info:
  title: OGC API
  version: 0.1.0
  description: |-
    This is an OpenAPI definition of various OGC API specifications as well as
    the SpatioTemporal Asset Catalog (STAC) API specification.
  contact:
    name: Balthasar Teuscher
    email: balthasar.teuscher@gmail.com
  license:
    name: CC-BY 4.0 license
    url: https://creativecommons.org/licenses/by/4.0/
servers:
  - url: http://localhost:8484
    description: "Development server"
tags:
  - name: server
  - name: Capabilities
    description: essential characteristics of this API
  - name: Data
    description: access to data (features)
paths:
  /:
    get:
      description: >-
        The landing page provides links to the API definition and the
        conformance statements for this API.
      operationId: getLandingPage
      responses:
        200:
          $ref: "#/components/responses/LandingPage"
        400:
          $ref: "#/components/responses/400"
        500:
          $ref: "#/components/responses/500"
      summary: Landing page
      tags:
        - server
  /api:
    get:
      description: This document
      responses:
        200:
          $ref: "#/components/responses/200"
        400:
          $ref: "#/components/responses/400"
        default:
          $ref: "#/components/responses/500"
      summary: This document
      tags:
        - server
  /conformance:
    get:
      description: >-
        A list of all conformance classes specified in a standard that the
        server conforms to.
      operationId: getConformanceDeclaration
      responses:
        200:
          $ref: "#/components/responses/ConformanceDeclaration"
        400:
          $ref: "#/components/responses/400"
        500:
          $ref: "#/components/responses/500"
      summary: API conformance definition
      tags:
        - server
  /collections:
    get:
      tags:
        - Capabilities
      summary: the feature collections in the dataset
      operationId: getCollections
      responses:
        200:
          $ref: "#/components/schemas/collections"
        500:
          $ref: "#/components/schemas/exception"
  /collections/{collectionId}:
    get:
      tags:
        - Capabilities
      summary: describe the feature collection with id `collectionId`
      operationId: describeCollection
      parameters:
        - $ref: "#/components/parameters/collectionId"
      responses:
        200:
          $ref: "#/components/schemas/collectionDesc"
        404:
          $ref: "#/components/schemas/exception"
        500:
          $ref: "#/components/schemas/exception"
  /collections/{collectionId}/items:
    get:
      tags:
        - Data
      summary: fetch features
      description: |-
        Fetch features of the feature collection with id `collectionId`.

        Every feature in a dataset belongs to a collection. A dataset may
        consist of multiple feature collections. A feature collection is often a
        collection of features of a similar type, based on a common schema.

        Use content negotiation to request HTML or GeoJSON.
      operationId: getFeatures
      parameters:
        - $ref: "#/components/parameters/collectionId"
        - $ref: "#/components/parameters/limit"
        - $ref: "#/components/parameters/bbox"
        - $ref: "#/components/parameters/bbox-crs"
        - $ref: "#/components/parameters/datetime"
        - $ref: "#/components/parameters/crs"
      responses:
        200:
          $ref: "#/components/responses/FeatureCollection"
        400:
          $ref: "#/components/schemas/exception"
        404:
          $ref: "#/components/schemas/exception"
        500:
          $ref: "#/components/schemas/exception"
  /collections/{collectionId}/items/{featureId}:
    get:
      tags:
        - Data
      summary: fetch a single feature
      description: |-
        Fetch the feature with id `featureId` in the feature collection
        with id `collectionId`.

        Use content negotiation to request HTML or GeoJSON.
      operationId: getFeature
      parameters:
        - $ref: "#/components/parameters/collectionId"
        - $ref: "#/components/parameters/featureId"
        - $ref: "#/components/parameters/crs"
      responses:
        200:
          $ref: "#/components/responses/Feature"
        404:
          $ref: "#/components/schemas/exception"
        500:
          $ref: "#/components/schemas/exception"
components:
  headers:
    Content-Crs:
      description: a URI, in angular brackets, identifying the coordinate reference system used in the content / payload
      schema:
        type: string
      example: "<http://www.opengis.net/def/crs/EPSG/0/3395>"
  parameters:
    bbox:
      name: bbox
      in: query
      description: >-
        Only resources 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)

        If the value consists of four numbers, the coordinate reference system 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`.

        If the value consists of six numbers, the coordinate reference system is WGS 84 
        longitude/latitude/ellipsoidal height (http://www.opengis.net/def/crs/OGC/0/CRS84h)
        unless a different coordinate reference system is specified in a 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 the vertical axis is included, the third and the sixth number are the
        bottom and the top of the 3-dimensional bounding box.

        If a resource 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
    bbox-crs:
      name: bbox-crs
      description: |-
        Asserts the CRS used for the coordinate values of the bbox parameter.
        The default is WGS 84 longitude/latitude (http://www.opengis.net/def/crs/OGC/1.3/CRS84)
        for a value with 4 numbers and WGS 84 longitude/latitude/ellipsoidal
        height (http://www.opengis.net/def/crs/OGC/0/CRS84h) for a value with 6 numbers.
      in: query
      required: false
      schema:
        type: string
        format: uri
      style: form
      explode: false
    collectionId:
      name: collectionId
      in: path
      description: local identifier of a collection
      required: true
      schema:
        type: string
    crs:
      name: crs
      description: |-
        If the parameter is specified, then the coordinates of all geometry-valued
        properties in the response document are in the requested CRS. Otherwise
        the coordinates are in the default CRS, that is http://www.opengis.net/def/crs/OGC/1.3/CRS84
        for coordinates without height and http://www.opengis.net/def/crs/OGC/0/CRS84h
        for coordinates with ellipsoidal height.
      in: query
      required: false
      schema:
        type: string
        format: uri
      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
    featureId:
      name: featureId
      in: path
      description: local identifier of a feature
      required: true
      schema:
        type: string
    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
  responses:
    ConformanceDeclaration:
      description: |-
        The URIs of all conformance classes supported by the server.
        To support "generic" clients that want to access multiple
        OGC API Features implementations - and not "just" a specific
        API / server, the server declares the conformance
        classes it implements and conforms to.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/confClasses"
          example:
            conformsTo:
              - "http://www.opengis.net/spec/ogcapi-common-1/1.0/conf/core"
              - "http://www.opengis.net/spec/ogcapi-common-1/1.0/conf/landingPage"
              - "http://www.opengis.net/spec/ogcapi-common-1/1.0/conf/oas30"
              - "http://www.opengis.net/spec/ogcapi-common-1/1.0/conf/html"
              - "http://www.opengis.net/spec/ogcapi-common-1/1.0/conf/json"
        text/html:
          schema:
            type: string
    FeatureCollection:
      description: Paginated GeoJSON feature collection
      headers:
        Content-Crs:
          $ref: "#/components/headers/Content-Crs"
      content:
        application/geo+json:
          schema:
            $ref: "#/components/schemas/featureCollectionGeoJSON"
    Feature:
      description: GeoJSON feature of a collection
      headers:
        Content-Crs:
          $ref: "#/components/headers/Content-Crs"
      content:
        application/geo+json:
          schema:
            $ref: "#/components/schemas/featureGeoJSON"
    LandingPage:
      description: |-
        The landing page provides links to the API definition
        (link relations `service-desc` and `service-doc`),
        and the Conformance declaration (path `/conformance`,
        link relation `conformance`).
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/landingPage"
        text/html:
          schema:
            type: string
    exception:
      description: An error occurred.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/exception"
        text/html:
          schema:
            type: string
    200:
      description: |-
        General Success response.
    400:
      description: |-
        General HTTP error response.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/exception"
        text/html:
          schema:
            type: string
    500:
      description: |-
        A server error occurred.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/exception"
        text/html:
          schema:
            type: string
  schemas:
    collectionDesc:
      type: object
      required:
        - id
        - links
      properties:
        id:
          description: identifier of the collection used, for example, in URIs
          type: string
          example: address
        title:
          description: human readable title of the collection
          type: string
          example: address
        description:
          description: a description of the features in the collection
          type: string
          example: An address
        attribution:
          type: string
          title: attribution for the collection
        links:
          type: array
          items:
            $ref: "#/components/schemas/link"
        extent:
          $ref: "#/components/schemas/extent"
        itemType:
          description: An indicator about the type of the items in the collection
          type: string
        crs:
          description: |-
            the list of coordinate reference systems supported by the API; the
            first item is the default coordinate reference system
          type: array
          items:
            type: string
          default:
            - http://www.opengis.net/def/crs/OGC/1.3/CRS84
          example:
            - http://www.opengis.net/def/crs/OGC/1.3/CRS84
            - http://www.opengis.net/def/crs/EPSG/0/4326
        storageCrs:
          description: |-
            the CRS identifier, from the list of supported CRS identifiers, 
            that may be used to retrieve features from a collection without the
            need to apply a CRS transformation
          type: string
          format: uri
        storageCrsCoordinateEpoch:
          description: |-
            point in time at which coordinates in the spatial feature 
            collection are referenced to the dynamic coordinate reference 
            system in `storageCrs`, that may be used to retrieve features from 
            a collection without the need to apply a change of coordinate 
            epoch. It is expressed as a decimal year in the Gregorian calendar
          type: number
          example: "2017-03-25 in the Gregorian calendar is epoch 2017.23"
    collections:
      type: object
      required:
        - links
        - collections
      properties:
        links:
          type: array
          items:
            $ref: "#/components/schemas/link"
        timeStamp:
          type: string
          format: date-time
        numberMatched:
          type: integer
          minimum: 0
        numberReturned:
          type: integer
          minimum: 0
        crs:
          description: |-
            a global list of CRS identifiers that are supported by spatial feature 
            collections offered by the service
          type: array
          items:
            type: string
            format: uri
        collections:
          type: array
          items:
            $ref: "#/components/schemas/collectionDesc"
    confClasses:
      type: object
      required:
        - conformsTo
      properties:
        conformsTo:
          type: array
          items:
            type: string
            example: http://www.opengis.net/spec/ogcapi-common-1/1.0/conf/core
    exception:
      title: Exception Schema
      description: JSON schema for exceptions based on RFC 7807
      type: object
      required:
        - type
      properties:
        type:
          type: string
        title:
          type: string
        status:
          type: integer
        detail:
          type: string
        instance:
          type: string
    extent:
      description: |-
        The extent of the features in the collection. In the Core only spatial and temporal
        extents are specified. Extensions may add additional members to represent other
        extents, for example, thermal or pressure ranges.

        The first item in the array describes the overall extent of
        the data. All subsequent items describe more precise extents, 
        e.g., to identify clusters of data.
        Clients only interested in the overall extent will only need to
        access the first item in each array.
      type: object
      properties:
        spatial:
          description: |-
            The spatial extent of the features in the collection.
          type: object
          properties:
            bbox:
              description: |-
                One or more bounding boxes that describe the spatial extent of the dataset.
                In the Core only a single bounding box is supported.

                Extensions may support additional areas.
                The first bounding box describes the overall spatial
                extent of the data. All subsequent bounding boxes describe 
                more precise bounding boxes, e.g., to identify clusters of data.
                Clients only interested in the overall spatial extent will
                only need to access the first item in each array.
              type: array
              minItems: 1
              items:
                description: |-
                  Each bounding box is provided as four or six numbers, depending on
                  whether the coordinate reference system includes a vertical axis
                  (height or depth):

                  * Lower left corner, coordinate axis 1
                  * Lower left corner, coordinate axis 2
                  * Minimum value, coordinate axis 3 (optional)
                  * Upper right corner, coordinate axis 1
                  * Upper right corner, coordinate axis 2
                  * Maximum value, coordinate axis 3 (optional)

                  If the value consists of four numbers, the coordinate reference system is
                  WGS 84 longitude/latitude (http://www.opengis.net/def/crs/OGC/1.3/CRS84)
                  unless a different coordinate reference system is specified in a parameter `bbox-crs`.

                  If the value consists of six numbers, the coordinate reference system is
                  WGS 84 longitude/latitude/height (http://www.opengis.net/def/crs/OGC/0/CRS84h)
                  unless a different coordinate reference system is specified in a 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 the vertical axis is included, the third and the sixth number are
                  the bottom and the top of the 3-dimensional bounding box.

                  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.
                type: array
                oneOf:
                  - minItems: 4
                    maxItems: 4
                  - minItems: 6
                    maxItems: 6
                items:
                  type: number
                example:
                  - -180
                  - -90
                  - 180
                  - 90
            crs:
              description: |-
                Coordinate reference system of the coordinates in the spatial extent
                (property `bbox`). The default reference system is WGS 84 longitude/latitude.
                In the Core the only other supported coordinate reference system is
                WGS 84 longitude/latitude/height for coordinates with height.
                Extensions may support additional coordinate reference systems and add
                additional enum values.
              type: string
              enum:
                - "http://www.opengis.net/def/crs/OGC/1.3/CRS84"
                - "http://www.opengis.net/def/crs/OGC/0/CRS84h"
              default: "http://www.opengis.net/def/crs/OGC/1.3/CRS84"
        temporal:
          description: |-
            The temporal extent of the features in the collection.
          type: object
          properties:
            interval:
              description: |-
                One or more time intervals that describe the temporal extent of the dataset.
                In the Core only a single time interval is supported.

                Extensions may support multiple intervals.
                The first time interval describes the overall
                temporal extent of the data. All subsequent time intervals describe 
                more precise time intervals, e.g., to identify clusters of data.
                Clients only interested in the overall extent will only need
                to access the first item in each array.
              type: array
              minItems: 1
              items:
                description: |-
                  Begin and end times of the time interval. The timestamps are in the
                  temporal coordinate reference system specified in `trs`. By default
                  this is the Gregorian calendar.

                  The value `null` is supported and indicates an open time interval.
                type: array
                minItems: 2
                maxItems: 2
                items:
                  type: string
                  format: date-time
                  nullable: true
                example:
                  - "2011-11-11T12:22:11Z"
                  - null
            trs:
              description: |-
                Coordinate reference system of the coordinates in the temporal extent
                (property `interval`). The default reference system is the Gregorian calendar.
                In the Core this is the only supported temporal coordinate reference system.
                Extensions may support additional temporal coordinate reference systems and add
                additional enum values.
              type: string
              enum:
                - "http://www.opengis.net/def/uom/ISO-8601/0/Gregorian"
              default: "http://www.opengis.net/def/uom/ISO-8601/0/Gregorian"
    featureCollectionGeoJSON:
      type: object
      required:
        - type
        - features
      properties:
        type:
          type: string
          enum:
            - FeatureCollection
        features:
          type: array
          items:
            $ref: "#/components/schemas/featureGeoJSON"
        links:
          type: array
          items:
            $ref: "#/components/schemas/link"
        timeStamp:
          type: string
          format: date-time
        numberMatched:
          type: integer
          minimum: 0
        numberReturned:
          type: integer
          minimum: 0
    featureGeoJSON:
      type: object
      required:
        - type
        - geometry
        - properties
      properties:
        type:
          type: string
          enum:
            - Feature
        geometry:
          $ref: "#/components/schemas/geometryGeoJSON"
        properties:
          type: object
          nullable: true
        id:
          oneOf:
            - type: string
            - type: integer
        links:
          type: array
          items:
            $ref: "#/components/schemas/link"
    geometryGeoJSON:
      oneOf:
        - $ref: "#/components/schemas/pointGeoJSON"
        - $ref: "#/components/schemas/multipointGeoJSON"
        - $ref: "#/components/schemas/linestringGeoJSON"
        - $ref: "#/components/schemas/multilinestringGeoJSON"
        - $ref: "#/components/schemas/polygonGeoJSON"
        - $ref: "#/components/schemas/multipolygonGeoJSON"
        - $ref: "#/components/schemas/geometrycollectionGeoJSON"
    geometrycollectionGeoJSON:
      type: object
      required:
        - type
        - geometries
      properties:
        type:
          type: string
          enum:
            - GeometryCollection
        geometries:
          type: array
          items:
            $ref: "#/components/schemas/geometryGeoJSON"
    landingPage:
      type: object
      required:
        - links
      properties:
        title:
          type: string
          title: The title of the API.
          description: While a title is not required, implementers are strongly advised to include one.
          example: Buildings in Bonn
        description:
          type: string
          example: Access to data about buildings in the city of Bonn via a Web API that conforms to the OGC API Common specification.
        attribution:
          type: string
          title: attribution for the API
          description: The `attribution` should be short and intended for presentation to a user, for example, in a corner of a map. Parts of the text can be links to other resources if additional information is needed. The string can include HTML markup.
        links:
          type: array
          items:
            $ref: "#/components/schemas/link"
    linestringGeoJSON:
      type: object
      required:
        - type
        - coordinates
      properties:
        type:
          type: string
          enum:
            - LineString
        coordinates:
          type: array
          minItems: 2
          items:
            type: array
            minItems: 2
            items:
              type: number
    link:
      type: object
      required:
        - href
        - rel
      properties:
        href:
          type: string
          description: Supplies the URI to a remote resource (or resource fragment).
          example: http://data.example.com/buildings/123
        rel:
          type: string
          description: The type or semantics of the relation.
          example: alternate
        type:
          type: string
          description: A hint indicating what the media type of the result of dereferencing the link should be.
          example: application/geo+json
        hreflang:
          type: string
          description: A hint indicating what the language of the result of dereferencing the link should be.
          example: en
        title:
          type: string
          description: Used to label the destination of a link such that it can be used as a human-readable identifier.
          example: Trierer Strasse 70, 53115 Bonn
        length:
          type: integer
    multilinestringGeoJSON:
      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
    multipointGeoJSON:
      type: object
      required:
        - type
        - coordinates
      properties:
        type:
          type: string
          enum:
            - MultiPoint
        coordinates:
          type: array
          items:
            type: array
            minItems: 2
            items:
              type: number
    multipolygonGeoJSON:
      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
    numberMatched:
      description: |-
        The number of features of the feature type that match the selection
        parameters like `bbox`.
      type: integer
      minimum: 0
      example: 127
    numberReturned:
      description: |-
        The number of features in the feature collection.

        A server may omit this information in a response, if the information
        about the number of features is not known or difficult to compute.

        If the value is provided, the value shall be identical to the number
        of items in the "features" array.
      type: integer
      minimum: 0
      example: 10
    pointGeoJSON:
      type: object
      required:
        - type
        - coordinates
      properties:
        type:
          type: string
          enum:
            - Point
        coordinates:
          type: array
          minItems: 2
          items:
            type: number
    polygonGeoJSON:
      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
    timeStamp:
      description: This property indicates the time and date when the response was generated.
      type: string
      format: date-time
      example: "2017-08-17T08:05:32Z"