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