Open Geospatial Consortium (OGC) Maps API

openapi: 3.2.0
info:
  version: '1.0'
  title: OGC Maps API
  description: 'Example API Definition for OGC API - Maps - Part 1: Core'
  contact:
    name: Open Geospatial Consortium
    email: info@ogc.org
  license:
    name: OGC License
    url: http://www.opengeospatial.org/legal/
servers:
- description: Example OGC API - Maps server
  url: https://maps.gnosis.earth/ogcapi
tags:
- name: Maps
paths:
  /map:
    get:
      tags:
      - Maps
      summary: Retrieve a default map of the whole dataset
      operationId: .dataset.getMap
      parameters:
      - $ref: '#/components/parameters/bbox'
      - $ref: '#/components/parameters/datetime'
      - $ref: '#/components/parameters/collections'
      - $ref: '#/components/parameters/subset'
      - $ref: '#/components/parameters/crs'
      - $ref: '#/components/parameters/bbox-crs'
      - $ref: '#/components/parameters/subset-crs'
      - $ref: '#/components/parameters/bgcolor'
      - $ref: '#/components/parameters/transparent'
      - $ref: '#/components/parameters/void-color'
      - $ref: '#/components/parameters/void-transparent'
      - $ref: '#/components/parameters/width'
      - $ref: '#/components/parameters/height'
      - $ref: '#/components/parameters/center'
      - $ref: '#/components/parameters/center-crs'
      - $ref: '#/components/parameters/scale-denominator'
      - $ref: '#/components/parameters/mm-per-pixel'
      - $ref: '#/components/parameters/orientation'
      - $ref: '#/components/parameters/crs-proj-method'
      - $ref: '#/components/parameters/crs-proj-center'
      - $ref: '#/components/parameters/crs-proj-params'
      - $ref: '#/components/parameters/crs-datum'
      - $ref: '#/components/parameters/f-map'
      responses:
        '200':
          $ref: '#/components/responses/Map'
        '204':
          $ref: '#/components/responses/EmptyMap'
        '404':
          $ref: '#/components/responses/NotFound'
        '406':
          $ref: '#/components/responses/NotAcceptable'
        '500':
          $ref: '#/components/responses/ServerError'
  /styles/{styleId}/map:
    get:
      tags:
      - Maps
      summary: Retrieve a styled map of the whole dataset
      operationId: .dataset.style.getMap
      parameters:
      - $ref: '#/components/parameters/bbox'
      - $ref: '#/components/parameters/datetime'
      - $ref: '#/components/parameters/collections'
      - $ref: '#/components/parameters/subset'
      - $ref: '#/components/parameters/crs'
      - $ref: '#/components/parameters/bbox-crs'
      - $ref: '#/components/parameters/subset-crs'
      - $ref: '#/components/parameters/bgcolor'
      - $ref: '#/components/parameters/transparent'
      - $ref: '#/components/parameters/void-color'
      - $ref: '#/components/parameters/void-transparent'
      - $ref: '#/components/parameters/width'
      - $ref: '#/components/parameters/height'
      - $ref: '#/components/parameters/center'
      - $ref: '#/components/parameters/center-crs'
      - $ref: '#/components/parameters/scale-denominator'
      - $ref: '#/components/parameters/mm-per-pixel'
      - $ref: '#/components/parameters/orientation'
      - $ref: '#/components/parameters/crs-proj-method'
      - $ref: '#/components/parameters/crs-proj-center'
      - $ref: '#/components/parameters/crs-proj-params'
      - $ref: '#/components/parameters/crs-datum'
      - $ref: '#/components/parameters/styleId'
      - $ref: '#/components/parameters/f-map'
      responses:
        '200':
          $ref: '#/components/responses/Map'
        '204':
          $ref: '#/components/responses/EmptyMap'
        '404':
          $ref: '#/components/responses/NotFound'
        '406':
          $ref: '#/components/responses/NotAcceptable'
        '500':
          $ref: '#/components/responses/ServerError'
  /collections/{collectionId}/map:
    get:
      tags:
      - Maps
      summary: Retrieve a map for the specified collection
      operationId: .collection.getMap
      parameters:
      - $ref: '#/components/parameters/bbox'
      - $ref: '#/components/parameters/datetime'
      - $ref: '#/components/parameters/collectionId-all'
      - $ref: '#/components/parameters/collections'
      - $ref: '#/components/parameters/subset'
      - $ref: '#/components/parameters/crs'
      - $ref: '#/components/parameters/bbox-crs'
      - $ref: '#/components/parameters/subset-crs'
      - $ref: '#/components/parameters/bgcolor'
      - $ref: '#/components/parameters/transparent'
      - $ref: '#/components/parameters/void-color'
      - $ref: '#/components/parameters/void-transparent'
      - $ref: '#/components/parameters/width'
      - $ref: '#/components/parameters/height'
      - $ref: '#/components/parameters/center'
      - $ref: '#/components/parameters/center-crs'
      - $ref: '#/components/parameters/scale-denominator'
      - $ref: '#/components/parameters/mm-per-pixel'
      - $ref: '#/components/parameters/orientation'
      - $ref: '#/components/parameters/crs-proj-method'
      - $ref: '#/components/parameters/crs-proj-center'
      - $ref: '#/components/parameters/crs-proj-params'
      - $ref: '#/components/parameters/crs-datum'
      - $ref: '#/components/parameters/f-map'
      responses:
        '200':
          $ref: '#/components/responses/Map'
        '204':
          $ref: '#/components/responses/EmptyMap'
        '404':
          $ref: '#/components/responses/NotFound'
        '406':
          $ref: '#/components/responses/NotAcceptable'
        '500':
          $ref: '#/components/responses/ServerError'
  /collections/{collectionId}/styles/{styleId}/map:
    get:
      tags:
      - Maps
      summary: Retrieve a map for a specified collection and style
      operationId: .collection.style.getMap
      parameters:
      - $ref: '#/components/parameters/bbox'
      - $ref: '#/components/parameters/datetime'
      - $ref: '#/components/parameters/collectionId-all'
      - $ref: '#/components/parameters/collections'
      - $ref: '#/components/parameters/subset'
      - $ref: '#/components/parameters/crs'
      - $ref: '#/components/parameters/bbox-crs'
      - $ref: '#/components/parameters/subset-crs'
      - $ref: '#/components/parameters/bgcolor'
      - $ref: '#/components/parameters/transparent'
      - $ref: '#/components/parameters/void-color'
      - $ref: '#/components/parameters/void-transparent'
      - $ref: '#/components/parameters/width'
      - $ref: '#/components/parameters/height'
      - $ref: '#/components/parameters/center'
      - $ref: '#/components/parameters/center-crs'
      - $ref: '#/components/parameters/scale-denominator'
      - $ref: '#/components/parameters/mm-per-pixel'
      - $ref: '#/components/parameters/orientation'
      - $ref: '#/components/parameters/crs-proj-method'
      - $ref: '#/components/parameters/crs-proj-center'
      - $ref: '#/components/parameters/crs-proj-params'
      - $ref: '#/components/parameters/crs-datum'
      - $ref: '#/components/parameters/styleId-collection'
      - $ref: '#/components/parameters/f-map'
      responses:
        '200':
          $ref: '#/components/responses/Map'
        '204':
          $ref: '#/components/responses/EmptyMap'
        '404':
          $ref: '#/components/responses/NotFound'
        '406':
          $ref: '#/components/responses/NotAcceptable'
        '500':
          $ref: '#/components/responses/ServerError'
components:
  responses:
    EmptyMap:
      description: No data available for this map extent.
    NotFound:
      description: The requested resource does not exist on the server. For example, a path parameter had an incorrect value.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/exception'
        text/html:
          schema:
            type: string
    ServerError:
      description: A server error occurred.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/exception'
        text/html:
          schema:
            type: string
    NotAcceptable:
      description: Content negotiation failed. For example, the `Accept` header submitted in the request did not support any of the media types supported by the server for the requested resource.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/exception'
        text/html:
          schema:
            type: string
    Map:
      description: A map image returned as a response.
      content:
        image/png:
          schema:
            type: string
            format: binary
        image/jpeg:
          schema:
            type: string
            format: binary
        image/tiff; application=geotiff:
          schema:
            type: string
            format: binary
  parameters:
    orientation:
      name: orientation
      in: query
      description: Orientation in degrees by which the content of the map is to be rotated around the center of the subset area as pivot point in a counter-clockwise direction, resulting in the viewing perspective being rotated by the same orientation in a clockwise direction.
      required: false
      style: form
      explode: false
      schema:
        type: number
        default: 0
    collectionId-all:
      name: collectionId
      in: path
      description: Local identifier of a collection
      required: true
      schema:
        $ref: '#/components/schemas/all-collections'
    center-crs:
      name: center-crs
      in: query
      description: CRS for the specified center point
      required: false
      style: form
      explode: true
      schema:
        type: string
    transparent:
      name: transparent
      in: query
      description: Background transparency of map (defaults to `true` without a `bgcolor` specified, but to `false` when a `bgcolor` is used).
      required: false
      style: form
      explode: false
      schema:
        type: boolean
        default: true
    styleId-collection:
      name: styleId
      in: path
      description: An identifier representing a specific style.
      required: true
      allowEmptyValue: false
      schema:
        type: string
    styleId:
      name: styleId
      in: path
      description: An identifier representing a specific style.
      required: true
      allowEmptyValue: false
      schema:
        $ref: '#/components/schemas/styles'
    center:
      name: center
      in: query
      description: Coordinates of center point for subsetting, in conjunction with the `width` and/or `height` parameters, taking into consideration the scale and display resolution of the map. The center coordinates are comma-separated and interpreted as [ogc:CRS84], unless the `center-crs` parameter specifies otherwise.
      required: false
      style: form
      explode: false
      schema:
        type: array
        minItems: 2
        maxItems: 2
        items:
          type: number
    bgcolor:
      name: bgcolor
      in: query
      description: Web color name or hexadecimal 0x[AA]RRGGBB color value for the background color (default to 0x9C9C9C gray). If alpha is not specified, full opacity is assumed.
      required: false
      style: form
      explode: false
      schema:
        type: string
        default: '0xFFFFFF'
    datetime:
      name: datetime
      in: query
      description: 'Either a date-time or an interval. Date and time expressions adhere to RFC 3339, section 5.6. Intervals may be bounded or half-bounded (double-dots at start or end). Server implementations may or may not support times expressed using time offsets from UTC, but need to support UTC time with the notation ending with a Z.

        Examples:

        * A date-time: "2018-02-12T23:20:50Z" * A bounded interval: "2018-02-12T00:00:00Z/2018-03-18T12:31:12Z" * Half-bounded intervals: "2018-02-12T00:00:00Z/.." or "../2018-03-18T12:31:12Z"

        Only resources 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
    subset:
      name: subset
      in: query
      description: 'Retrieve only part of the data by slicing or trimming along one or more axis

        For trimming: {axisAbbrev}({low}:{high}) (preserves dimensionality)

        For slicing:  {axisAbbrev}({value})      (reduces dimensionality)

        An asterisk (`*`) can be used instead of {low} or {high} to indicate the minimum/maximum value.

        For a temporal dimension, a single asterisk can be used to indicate the high value.

        Support for `*` is required for time, but optional for spatial and other dimensions.

        '
      style: form
      explode: false
      required: false
      schema:
        type: array
        items:
          type: string
    collections:
      name: collections
      in: query
      style: form
      description: The collections that should be included in the response. The parameter value is a comma-separated list of collection identifiers. If the parameters is missing, some or all collections will be included. The collection will be rendered in the order specified, with the last one showing on top, unless the priority is overridden by styling rules.
      required: false
      explode: false
      schema:
        type: array
        items:
          $ref: '#/components/schemas/all-collections'
    mm-per-pixel:
      name: mm-per-pixel
      in: query
      description: Display resolution of the target rendering device in millimeters per pixel. This parameter controls the relationship between the dimensions of the resulting map in pixels and the scale of the map. The display resolution is taken into account for applying symbology rules, for the `scale-denominator` parameter, and for the spatial subsetting using a `center`, `width` and `height` parameters.
      required: false
      style: form
      explode: false
      schema:
        type: number
        default: 0.28
    scale-denominator:
      name: scale-denominator
      in: query
      description: Scale denominator of the map specifying to how many units in the real world one of the same unit on the map corresponds, as printed or displayed, taking into account the display resolution (`mm-per-pixel` or 0.28 mm/pixel default). This parameter can only be used together with the `width` or `height` parameters (which provide an alternative mechanism to control the scale) if the implementation also supports subsetting, in which case those `width` and `height` parameters then control the subset of the map returned rather than the scale. If `scale-denominator` is omitted, the scale is implied from the dimensions of the returned map compared to its spatial subset area.
      required: false
      style: form
      explode: false
      schema:
        type: number
    bbox-crs:
      name: bbox-crs
      in: query
      description: crs for the specified bbox
      required: false
      style: form
      explode: true
      schema:
        type: string
    crs-proj-method:
      name: crs-proj-method
      in: query
      description: Projection operation method for a custom projection CRS.
      required: false
      style: form
      explode: false
      schema:
        type: string
    void-color:
      name: void-color
      in: query
      description: Web color name or hexadecimal 0x[AA]RRGGBB color value for the void color for parts of the map outside of the valid area of the projection / CRS. If not specified, this defaults to the same as `bgcolor`.
      required: false
      style: form
      explode: false
      schema:
        type: string
        default: '0xFFFFFF'
    f-map:
      name: f
      in: query
      description: The format of the map response (e.g. png). Accepted values are 'png', 'jpg' or 'tiff' (GeoTIFF).
      required: false
      schema:
        type: string
        enum:
        - png
        - jpg
        - tiff
      style: form
      explode: false
    subset-crs:
      name: subset-crs
      in: query
      description: crs for the specified subset
      required: false
      style: form
      explode: true
      schema:
        type: string
    crs:
      name: crs
      in: query
      description: reproject the output to the given crs
      required: false
      style: form
      explode: true
      schema:
        type: string
    height:
      name: height
      in: query
      description: Height of the map in pixels. If omitted and `width` is specified, defaults to the height maintaining a 1:1 aspect ratio. If both `width` and `height` are omitted, the server will select default dimensions. When used together with the `center` and/or `scale-denominator` parameter, `height` takes on a subsetting role rather than scaling (resampling), defining the vertical portion of the map to subset based on the scale (native scale, or specified by `scale-denominator`) and display resolution (0.28 mm/pixel, or specified by `mm-per-pixel`).
      required: false
      style: form
      explode: false
      schema:
        type: integer
    crs-proj-params:
      name: crs-proj-params
      in: query
      description: Operation method parameters for a custom projection CRS.
      required: false
      style: form
      explode: false
      schema:
        type: string
    crs-datum:
      name: crs-datum
      in: query
      description: Datum for a custom projection CRS, implying a particular ellipsoid.
      required: false
      style: form
      explode: false
      schema:
        type: string
    void-transparent:
      name: void-transparent
      in: query
      description: Background transparency for parts of the map outside of the valid areas of the CRS / projection (defaults to the same as `transparent` if not specified).
      required: false
      style: form
      explode: false
      schema:
        type: boolean
        default: true
    crs-proj-center:
      name: crs-proj-center
      in: query
      description: Projection center for a custom projection CRS corresponding to specific projection operation method parameters for latitude and longitude.
      required: false
      style: form
      explode: false
      schema:
        type: string
    width:
      name: width
      in: query
      description: Width of the map in pixels. If omitted and `height` is specified, defaults to the width maintaining a 1:1 aspect ratio. If both `width` and `height` are omitted, the server will select default dimensions. When used together with the `center` and/or `scale-denominator` parameter, `width` takes on a subsetting role rather than scaling (resampling), defining the horizontal portion of the map to subset based on the scale (native scale, or specified by `scale-denominator`) and display resolution (0.28 mm/pixel, or specified by `mm-per-pixel`).
      required: false
      style: form
      explode: false
      schema:
        type: integer
    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 * 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 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
        oneOf:
        - minItems: 4
          maxItems: 4
        - minItems: 6
          maxItems: 6
        items:
          type: number
      style: form
      explode: false
  schemas:
    styles:
      type: string
      enum:
      - default
    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
    all-collections:
      type: string
      enum:
      - blueMarble
      - NaturalEarth:raster:HYP_HR_SR_OB_DR
      - NaturalEarth:cultural:ne_10m_admin_0_countries
      - NaturalEarth:physical:bathymetry
      - SRTM_ViewFinderPanorama
      - HRDEM-Ottawa
      - HRDEM-RedRiver