2.1.  Requirements classes defining resources

Requirements Class “Core” (https://www.opengis.net/spec/ogcapi-maps-1/1.0/req/core)

The Maps API Core specifies requirements that any Web API implementation instance of the Maps API Standard must implement to claim conformance with the OGC API — Maps — Part 1: Core Standard. This requirements class defines an operation to retrieve a map but does not define any query parameters to customize the map.

An example request is below:

.../map

Requirements Class “Map Tilesets” (https://www.opengis.net/spec/ogcapi-maps-1/1.0/req/tilesets)

The map tilesets requirements class defines a mechanism to list available map tilesets supported by the Web API instance and a mechanism for retrieving tiles of the map representation. The terms ’tile’ and ’tile set’ (alias tileset) are defined in the OGC Two Dimensional Tile Matrix Set Standard (OGC 17-083r4).

Example requests are below:

.../map/tiles
.../map/tiles/WorldCRS84Quad
.../map/tiles/WorldCRS84Quad/0/0/0

2.2.  Requirements classes defining parameters

These requirements classes of the Maps API define parameters that can be used together with any map resource.

Requirements Class “Background” (https://www.opengis.net/spec/ogcapi-maps-1/1.0/req/background)

The background requirements class defines how to request two particular background colors (bgcolor and void-color) and to specify whether areas of the map with no data or where the CRS / projection is invalid are transparent (using transparent and void-transparent).

Example requests are below:

.../map?bgcolor=0x001122&transparent=false&void-transparent=true

Requirements Class “Collection Selection” (https://www.opengis.net/spec/ogcapi-maps-1/1.0/req/collections-selection)

The collection selection requirements class defines how to list specific geospatial data collection resources from which to retrieve maps.

An example request is below:

.../map?collections=buildings,roads,...

Requirements Class “Scaling” (https://www.opengis.net/spec/ogcapi-maps-1/1.0/req/scaling) The scaling requirements class defines how to retrieve a resampled map. This is done by specifying a width and/or height parameter (in pixels), or a scale-denominator parameter.

Example requests are below:

.../map?width=1024&height=512
.../map?scale-denominator=20000

Requirements Class “Display Resolution” (https://www.opengis.net/spec/ogcapi-maps-1/1.0/req/display-resolution) The display resolution requirements class defines how to specify the resolution of the display (the size of a pixel in millimeters) using the mm-per-pixel parameter at which the map will be visualized so as to properly interpret scale denominators and apply scale-dependent symbology rules.

An example request is below:

.../map?mm-per-pixel=0.14

Requirements Class “Spatial Subsetting” (https://www.opengis.net/spec/ogcapi-maps-1/1.0/req/spatial-subsetting) The spatial subsetting requirements class defines how to retrieve a spatial subset of a map using either a bbox or subset parameter.

Example subsetting requests using bounding box are below:

.../map?bbox=120,30,180,90
.../map?bbox-crs=[EPSG:3857]&bbox=500000,430000,1000000,1000000

Example subsetting requests using subset are below:

.../map?subset=Lat(30:90),Lon(120:180)
.../map?subset-crs=[EPSG:3857]&subset=X(500000:1000000),Y(430000:1000000)

This class also specifies how to retrieve a subset of a map using a center parameter, together with width and height parameters.

Example subsetting requests using center point and dimensions:

.../map?center=-120,60&width=1024&height=512
.../map?center-crs=[EPSG:3857]&center=750000,70000&width=1024&height=512

Requirements Class “Date and Time” (https://www.opengis.net/spec/ogcapi-maps-1/1.0/req/datetime) The temporal subsetting requirements class specifies how to request a temporal subset of the data using the datetime parameter, or the subset parameter for the time dimension.

Example requests are below:

.../map?datetime=2018-02-12T23:20:52Z
.../map?subset=time("2018-02-12T23:20:52Z")

Requirements Class “General Subsetting” (https://www.opengis.net/spec/ogcapi-maps-1/1.0/req/general-subsetting) The general subsetting requirements class specifies how to request a subset of dimensions of the data besides the spatial and temporal dimensions using the subset parameter. This parameter also implies adopting a consistent way to describe all dimensions of the data in the collection’s extent description.

An example request is below:

.../map?subset=atm_pressure_hpa(500)

Requirements Class “Coordinate Reference System” (https://www.opengis.net/spec/ogcapi-maps-1/1.0/req/crs)

The Coordinate Reference System requirements class defines how to specify the output Coordinate Reference System (CRS) of the map by referencing a Uniform Resource Identifier (URI) or compact URI (CURIE) of a CRS definition.

An example request is below:

.../map?crs=[EPSG:3031]

Requirements Class “Orientation” (https://www.opengis.net/spec/ogcapi-maps-1/1.0/req/orientation) The orientation requirements class defines how to specify an angle (expressed in degrees) for re-orienting how the map is displayed (orientation).

An example orientation request is below:

.../map?orientation=40

Requirements Class “Custom Projection CRS” (https://www.opengis.net/spec/ogcapi-maps-1/1.0/req/projection) The custom projection CRS requirements class defines how to specify a custom CRS through a projection, including the coordinate operation method (crs-proj-method) and associated parameters (crs-proj-params), as well as a datum (crs-datum). This class also defines a crs-proj-center parameter for facilitating the selection of the most likely parameters to center the projection on an area of interest.

An example of an orthographic projection request is below:

.../map?
   crs-proj-method=[epsg-method:9840]&
   crs-proj-center=Lat(40),Lon(-120)

An example of a Lambert Conic Conformal projection with two standard parallels request is below:

.../map?
   crs-proj-method=[epsg-method:9802]&
   crs-proj-params=[epsg-parameter:8823](40),[epsg-parameter:8824](90)&
   crs-datum=[epsg-datum:6230]

2.3.  Requirements classes defining origins

Requirements Class “Collection Map” (https://www.opengis.net/spec/ogcapi-maps-1/1.0/req/collection-map)

The collection map requirements class specifies how to retrieve maps from a specific geospatial data resource.

An example request is below:

/collections/buildings/map

Requirements Class “Dataset Map” (https://www.opengis.net/spec/ogcapi-maps-1/1.0/req/dataset-map)

The dataset map requirements class specifies how to retrieve maps for a whole dataset potentially made up of multiple geospatial data resources. Any Web API implementing this requirements class must support dataset maps following this OGC API — Maps — Part 1: Core Standard. Dataset maps may combine content from multiple geospatial resources, regardless of whether those are available separately (as maps or otherwise).

An example request is below:

/map

Requirements Class “Styled Maps” (https://www.opengis.net/spec/ogcapi-maps-1/1.0/req/styled-map)

The styled map requirements class specifies how to retrieve maps for a styled resource.

An example request is below:

.../styles/night/map

2.4.  Requirements classes defining representations

Requirements Classes for Encodings

The Maps API Standard does not mandate a specific encoding or format for representing maps. Requirements classes are provided for the following common map formats.

PNG (https://www.opengis.net/spec/ogcapi-maps-1/1.0/req/png)

Media type: image/png

JPEG (https://www.opengis.net/spec/ogcapi-maps-1/1.0/req/jpeg)

Media type: image/jpeg

JPEG XL (https://www.opengis.net/spec/ogcapi-maps-1/1.0/req/jpegxl)

Media type: image/jxl

TIFF (https://www.opengis.net/spec/ogcapi-maps-1/1.0/req/tiff)

Media type: image/tiff

SVG (https://www.opengis.net/spec/ogcapi-maps-1/1.0/req/svg)

Media type: image/svg+xml

HTML (https://www.opengis.net/spec/ogcapi-maps-1/1.0/req/html)

Media type: text/html

The Standard remains flexible and extensible for using other formats that users and providers might need through HTTP content negotiation.

That said, this Standard includes recommendations to support, where practical, HTML.

Requirements Class “API Operations” (https://www.opengis.net/spec/ogcapi-maps-1/1.0/req/api-operations)

The API Operations requirements class specifies requirements to fully describe the Maps API operations and use specific operation identifier suffixes when providing an API definition. This requirements class is intended to be used in conjunction with other conformance classes for a specific API definition language and/or version, such as the OpenAPI 3.0 requirements class defined in OGC API — Common — Part 1: Core, or another eventual requirements class for OpenAPI 3.1.

Requirements Class “CORS” (https://www.opengis.net/spec/ogcapi-maps-1/1.0/req/cors)

The CORS requirements class specifies a requirement to implement CORS to support JavaScript clients (e.g. Web Browser applications) from a domain different from the OGC API — Maps endpoint.

All requirements classes and conformance classes described in this Standard are owned by the Standard(s) identified.

2.5.  Summary of conformance URIs

Table 1 — Conformance class URIs

5.1.  Identifiers

The normative provisions in this standard are denoted by the URI https://www.opengis.net/spec/ogcapi-maps-1/1.0.

All requirements and conformance tests that appear in this document are denoted by partial URIs which are relative to this base.

5.2.  Link relations

To express relationships between resources, RFC 8288 (Web Linking) is used.

Note that the CURIE based on the pattern [ogc-rel:<relation>] is also considered equivalent. For example, [ogc-rel:map] corresponds to https://www.opengis.net/def/rel/ogc/1.0/map.

The following IANA link relation types are used in this document:

• alternate: Refers to a substitute for this context.

• self: Conveys an identifier for the link’s context.

• item: The target IRI points to a resource that is a member of the collection represented by the context IRI.

• preview: Refers to a resource that provides a preview of the link’s context. In the context of this specification, it used to link to a low-resolution preview of the map.

• service-desc: Identifies service description for the context that is primarily intended for consumption by machines (Web API definitions are considered service descriptions).

• service-doc: Identifies service documentation for the context that is primarily intended for human consumption.

• stylesheet: Refers to a stylesheet. In the context of this specification, it refers to a cartographic stylesheet, as provided by OGC API — Styles.

In addition, the following link relation type is used for which no applicable registered link relation type could be identified:

• https://www.opengis.net/def/rel/ogc/1.0/map: Refers to a resource that is map representation of another geospatial resource (e.g., a collection).

• https://www.opengis.net/def/rel/ogc/1.0/legend: Refers to a legend for the map.

Used in combination with OGC API — Tiles — Part 1: Core, other link relation types will be used, including:

• https://www.opengis.net/def/rel/ogc/1.0/tilesets-map: The target IRI points to a resource that describes how to provide tile sets of the context resource in map format.

Used in combination with OGC API — Styles, other link relation types will be used, including:

• https://www.opengis.net/def/rel/ogc/1.0/styles: The target IRI points to a resource that describes how to provide styles of the context resource that internally can contain links to maps.

Used in combination with OGC API — Features — Part 1: Core or OGC API — Common — Part 1: Core, other link relation types will be used, including:

• https://www.opengis.net/def/rel/ogc/1.0/conformance: Refers to a resource that identifies the specifications that the link’s context conforms to.

Used in combination with OGC API — Features — Part 1: Core or OGC API — Common — Part 2: Geospatial data, other link relation types will be used, including:

• https://www.opengis.net/def/rel/ogc/1.0/data: Refers to the list of collections available for a dataset.

Each resource representation includes an array of links. Implementations are free to add additional links for all resources provided by the Web API implementing Maps API requirement(s).

5.3.  Use of HTTPS

For simplicity, the Maps API only refers to the HTTP protocol. This is not meant to exclude the use of HTTPS and simply is a shorthand notation for “HTTP or HTTPS.” Following the recent push towards enhancing web security, public facing web servers are expected to use HTTPS rather than HTTP. In the context of Maps API Standard, use of HTTPS provides a layer of security to prevent leaking of information related to users requesting map data for a particular geographical area, which may be private or sensitive in nature (for example, their own location, or the location of endangered species).

6.1.  Introduction

The OGC API — Maps Standard defines building blocks which can be used in a Web API implementation to retrieve geospatial data as maps that are visual portrayals of the data created by applying a style to the data (see Requirements Class “Core”). Maps can present the whole area of the geospatial data or a subset of the content, such as by filtering the data by extent (see Requirements Class “Spatial subsetting”). Maps can be retrieved by arbitrary extent or as tiles (see Requirements Class “Map Tilesets”). The “Core” conformance class is the only mandatory one. All other conformance classes are optional and depend on the “Core”.

An annex with examples of map requests and responses is included as a way to ‘learn by example’ how this standard can be applied. See Annex B(informative)Examples.

An example OpenAPI definition for this Standard is available. Other examples are available on the OGC API website. Details on how to adjust and bundle the modular and reusable components used in this example OpenAPI definition can be found in Requirements Class “API Operations” .

Services and clients are encouraged to support as many of the Coordinate Reference Systems (CRSs) as possible for all geospatial data resources to maximize interoperability. However, this Standard does not require support for any specific CRS.

The OGC API — Maps Standard does not specify any requirement for the type of geospatial data resource that could be delivered as maps. If the geospatial data resources can be organized into maps, they can be supported regardless of whether they are feature data, coverages, a resource that does not represent data per se (e.g., an annotation) and so forth.

These geospatial data resources can advertise one or more map portrayals in several resources, such as the dataset (see Requirements Class “Dataset Map”), a collection (see Requirements Class “Collection Map”), a dataset with a style, or a collection with a style (see Requirements Class “Styled Maps”). Implementations of other OGC API Standards can provide other origins that may be represented as maps. Accessing the geospatial data resource content (other than as maps) or its descriptions is possible but out of the scope of this Standard. If a description of the geospatial data resource is specified by another standard, and this description has a mechanism to add links to other resources, this Standard indicates the need to add a link to a map of this resource.

The OGC API — Maps Standard does not specify how to get a Web API definition, the conformance class list or the collections lists. However, the Maps API Standard assumes that the first two are defined by some OGC API Standard (e.g., OGC API — Common — Part 1: Core) and the latter by an OGC API for collections (e.g., OGC API — Common — Part 2: Geospatial data). A similar definition is provided directly by OGC API — Features — Part 1: Core.

This document is the first part of a series of OGC API — Maps “parts” that follows the core and extensions model. Future parts will specify other extensions, such as how to specify cartographic layout elements to be included on the map, how to specify a filter for which elements should be included on the map, and possibly how to query information for a point in a map.

6.2.  Map interoperability

One of the most significant use cases for the definition of the Maps API is the ability to generate maps on the web from layers, provided by multiple servers, that can be overlaid into a single view. The Maps API Standard provides a clear and common way to request a map image that covers a bounding box of interest with a defined number of pixel rows and columns. When the Maps API is implemented by different organizations that offer different collections of information, the same bounding box, in the same CRS, and the same number of rows and columns can be requested from each organization’s geospatial repository. The result is a set of images that perfectly overlap showing different variables of the same area depending on the collection of geospatial data requested. For example, a population map can be requested from one organization (e.g., SEDAC Population Density) and a weather forecast from another (e.g., NDFD Surface Wind Velocity) in the exact same way allowing to present both together in one overlaid view or side-by-side.

Table 2 — SEDAC GPWv4 Population Density, 2015 and Forecast NDFD, Surface (10m AGL) Wind Velocity (Barb, Knots)

Figure 1

Figure 2

NOTE:    The Requirements Class “Collection Selection” provides a way for clients to instruct a service implementing OGC API - Maps to include multiple sub-resources overlaid in the map response.

Figure 3 — Forecast NDFD wind speed on top of SEDAC Population density

6.3.  How to approach an implementation of an OGC API Standard

There are at least two ways for using an implementation of one or more OGC API Standards:

• Read the landing page, look for links, follow them and discover new links until the desired resource is found

• Read a Web API definition document that specifies a list of paths and path templates to resources.

For the first approach, many resources in a deployed Web API include links with rel properties to document the reason and purpose for this relation. The following figure illustrates the resources as ellipses and the links as arrows with the link rel as a label.

Figure 4 — Resources and relations to them via links

For the second approach, implementations should consider the Requirements Class “API Operations” which defines the use of operationID suffixes, providing a mechanism to associate API paths with the requirements class that they implement.

There is a third way to approach an OGC API implementation instance. This approach relies on assuming a set of predefined paths and path templates. These predefined paths are used in many examples in this document and are presented together in Table 3. It is expected that many implementations of the Maps API Standard will provide a Web API definition document (e.g., OpenAPI) using this set of predefined paths and path templates to get necessary resources directly. All this could mislead the reader into getting the false impression that the predefined paths are enforced. Therefore, building a client that is assuming a predefined set of paths is risky. However, it is expected that many API implementations will follow the predefined set of paths. The clients using this assumption could be successful on many occasions. Again, be aware that these paths are not required by the Maps API Standard.

Table 3 — Overview of resources and common direct links that can be used to define an OGC API — Maps implementation

6.4.  OGC API — Maps within the OGC API family

6.5.  Description of the domain

The Maps API Standard defines how to describe the domain of the maps, including spatiotemporal axes as well as additional dimensions.

With the Collection Map requirements class, the collection description inherited from OGC API — Common — Part 2 contains an extent property that can describe both the spatial and temporal domain of the data. In addition, the Unified Additional Dimensions common building block, specified in the General Subsetting requirements class and used in the example OpenAPI definition, requires that additional dimensions be described in a similar way to the temporal dimension. This allows providing an overall lower and upper bound (the first interval element), as well as optional sparse inner intervals where data is found along each dimension (additional interval elements). A grid property also supports the description of regular and irregular grids. The resolution (the distance between any two neighboring cells, an absolute value) and the number of cells (cellsCount) can be specified for each regular dimension. A list of coordinates where data is found can be specified for irregular dimensions. In addition, the minimum and maximum cell size (minCellSize and maxCellSize) and equivalent scale denominators (minScaleDenominator and maxScaleDenominator) can be specified in the collection resource.

The Dataset Map requirements class specifies the addition of an extent property to the landing page (root resource of the API) of OGC API — Common — Part 1 based on the same schema as for the collection.

6.6.  Subsetting and scaling the map

The core requirements class of the Maps API Standard provides a way to retrieve the map that is modified by other classes allowing for subsetting the domain, specifying a particular size for the output map image, and changing the default assumption about the physical size of a pixel on the rendering device. The combination of these parameters also defines the scale of the map, which affects how scale-dependent symbology rules should be applied. These classes (Scaling, Display resolution and Subsetting) define the following parameters interacting with each other (in a not so trivial manner):

Table 4 — Parameters for scaling and subsetting

All these parameters are optional. The server needs to know the geographic extent covered by the map in physical world units, and the size of the map as rendered on the viewport (in both pixel units and physical units). Some combinations completely define both sizes. Some combinations of parameters generate impossible situations and will result in an error. Other combinations require that the server decides a default value for some parameters not provided to be able to resolve the requested sizes. The Maps API Standard only specifies the default value for mm-per-pixel leaving to the server freedom to decide about the other parameters. The following tables present an overview of the different combinations possible depending on whether the Scaling, Subsetting or both Scaling and Subsetting requirements classes are supported by the implementation, to clarify the relationship between these parameters and provide centralized guidance for implementers.

Table 5 — Always valid requests (no scaling or subsetting parameter)

Table 6 — Always invalid parameter combinations

Table 7 — Parameter combinations for implementations supporting Subsetting, but not Scaling

Table 8 — Parameter combinations for implementations supporting Scaling, but not Subsetting

Table 9 — Parameter combinations for implementations supporting both Subsetting and Scaling

See examples in an annex for computations infering dimensions and infering bounding boxes based on specified parameters.

6.7.  Available formats and map response expectations

The Maps API Standard defines six requirements classes for specific encodings to encode map data. Additional encodings can be supported using HTTP content negotiation, following conventions specific to those encodings.

7.1.  Overview

The core requirements class specifies a map resource. This is a resource that represents geospatial data as a rendered map. Requesting a map resource, as defined in the core, results in retrieving a generic map as a graphical representation of the data in the repository being accessed via the API endpoint. When using an implementation of the core requirements class, the representation is not constrained in any way by the client. Therefore, the server is free to return a total or a partial representation of the resource at an arbitrary size. Additional Maps API requirements classes add query parameters to personalize the server behavior to the client needs. These requirements classes define specific parameters that allow the client to control the map size and resolution of the map (width, height, bounding box and CRS) as well as the background of the map. An additional requirements class defines how a map resource can be retrieved as tiles by applying the OGC API — Tiles.

A map resource can be obtained from an arbitrary geospatial resource by adding /map to the resource URI. The core requirements class does not specify to which resources /map is applicable. However, a list of common paths to resources exposed by the API, where maps can commonly be obtained is presented in the following table. The Collection Maps, Dataset maps and Styled Maps requirements classes define some of these possibilities.

Table 10 — Common map resources in a geospatial API

7.2.  Map resource

A map distribution of a geospatial resource is a pictorial representation of that resource (map). To create a pictorial representation, a style is added to the data in the geospatial resource by a portrayal engine and following portrayal rules. This style can be internal (default style) or can be governed by the client.

This section defines the core resource of the OGC API — Maps Standard: A map representation for a geospatial resource. To keep the core of OGC API — Maps simple, the core only includes a mechanism to retrieve a map of the size and for the spatiotemporal extent that the server considers optimal.

7.2.2.  Response

Requirement 2
Identifier	/req/core/map-response
Included in	Requirements class 1: https://www.opengis.net/spec/ogcapi-maps-1/1.0/req/core
A	A successful execution of a map operation SHALL be a response with an HTTP status code 200.
B	The map response SHALL be in the storage CRS specified in the description of the geospatial resource (such as the associated collection or dataset), or https://www.opengis.net/def/crs/OGC/1.3/CRS84 if none is specified, unless overridden by a specific query parameter (see Requirements Class “Coordinate Reference System”).
C	The headers of the response SHALL include the Content-Crs: header with the URI or the safe CURIEs of the CRS used to render the map, except if the content is in the https://www.opengis.net/def/crs/OGC/1.3/CRS84 CRS.
D	The headers of the response SHALL include a Content-Bbox: header with the actual geospatial boundary of the rendered map.
E	The Content-Bbox: coordinates SHALL be in the response CRS (indicated in the Content-Crs: or https://www.opengis.net/def/crs/OGC/1.3/CRS84 if it is not present) and SHALL contain four comma-separated numbers representing the lower-left and upper-right corners of the response honoring the CRS coordinates order.
F	If the geospatial resource has a temporal aspect (e.g., if a temporal extent is defined in the collection description or in the dataset landing page), the headers of the response SHALL include a Content-Datetime: header with the actual datetime instant or datetime interval of the rendered map.
G	In the Content-Datetime: response header, a datetime interval SHALL be expressed using the notation time-instant / time-instant.
H	In the Content-Datetime: response header, a time instant, whether a single value or the time-instant of an interval, SHALL be expressed as defined in RFC 3339, section 5.6, using either UTC time or local time offsets, with the additional options of: only a year: yyyy a year and a month: yyyy-mm a year, a month and a day: yyyy-mm-dd a year, a month, a day and an hour: yyyy-mm-ddThhZ (or e.g., yyyy-mm-ddThh-04:00) a year, a month, a day, an hour and a minute: yyyy-mm-ddThh:mmZ (or e.g., yyyy-mm-ddThh-04:00)
I	The body of a response of a successful operation SHALL contain a map encoded in the negotiated format.

Below is an example of the successful HTTP response headers describing a PNG image with 1500 columns and 616 rows in the datum WGS84 and projection UTM zone 31N centered in the Barcelona area.

HTTP/1.1 200 OK
Content-Type: image/jpeg
Last-Modified: Fri, 05 Jul 2024 16:46:55 GMT
Content-Crs: <https://www.opengis.net/def/crs/EPSG/0/25831>
Content-Bbox: 392011.47,4563522.45,453461.47,4591522.45
Content-Datetime: 2020-01
Content-Length: 190946

Figure 5 — Example of a successful HTTP response body containing a JPEG image captured by LANDSAT in January 2020

Below is another example of the successful HTTP response headers describing a PNG image in the datum WGS84 and coordinates centered in the Barcelona area.

HTTP/1.1 200 OK
Content-Type: image/png
Last-Modified: Thu, 27 Jul 2023 14:37:46 GMT
Content-Bbox: 2.1486,41.3674,2.1886,41.4074

7.3.  Declaration of conformance classes

To support “generic” clients that want to access implementations of multiple OGC API Standards and extensions — and not “just” a specific API / server, the deployed API must declare the conformance classes it implements and conforms to.

The conformance declaration response mainly consists of a list of links.

If the server declares conformity also to OGC API — Common — Part 1: Core or to OGC API — Features — Part 1: Core, then the OGC API requirements for declaring conformance, such as the use of the /conformance resource, must be considered. In the JSON format, the conformance resource is an array of links following the link schema defined in OGC API — Common — Part 1: Core or in OGC API — Features — Part 1: Core. Below is an example fragment of a conformance information page of an API implementation conformant to OGC API — Common and OGC API — Maps.

An example Conformance Information Page fragment is below:

{
  "conformsTo": [
    "https://www.opengis.net/spec/ogcapi-common-1/1.0/conf/core",
    "https://www.opengis.net/spec/ogcapi-common-2/1.0/conf/collections",
    "https://www.opengis.net/spec/ogcapi-maps-1/1.0/conf/core"
  ]
}

8.1.  Overview

The Map Tilesets requirements class describes how to provide access to a map as tilesets in combination with the OGC API — Tiles Standard, which is based on the OGC 2D Tile Matrix Set and Tileset Metadata Standard. Tiles facilitate caching of data for clients and servers by requesting predefined subsets at fixed resolutions according to multi-resolution set of grids called a TileMatrixSet.

While supporting map tiles and map tilesets without conforming to this requirements class is possible, implementing this requirements class means that the tiles resources support parameters defined by OGC API — Maps in the following requirements classes:

• Background (bgcolor and transparent parameter),

• Display resolution (mm-per-pixel),

• Spatial subsetting (only if a vertical dimension is available, since the 2D Tile Matrix Sets already handle partitioning the other two dimensions, and only for subset and subset-crs parameters),

• General subsetting (subset for dimensions beyond spatial and temporal),

• Scaling (scale-denomimator, width and height which will override the usual tileWidth and tileHeight of the requested tile in pixels from the tile matrix, but those values are still used for calculating the geospatial bounding box corresponding to each tile),

  NOTE 2:    OGC API — Tiles defines its own equivalent requirements class for temporal subsetting.

8.2.  Link from data resource

A map resource can be accessed as tiles if the API implementation instance exposes a link to map tilesets in the resource that is available as map tiles.

Example — Fragment of a collection description document with a links array and with one item of the array pointing to a list of map tilesets.

{
    "links": [
    ...
    {
      "href": "https://data.example.com/collections/buildings/map/tiles",
      "rel": "https://www.opengis.net/def/rel/ogc/1.0/tilesets-map",
      "type": "application/json"
    }
  ]
}

8.3.  Map Tileset

A tileset contains the necessary metadata to enable a client application to formulate a tile request from a single geospatial data resource.

9.1.  Overview

The Background requirements class describes how to define the background of the map that is presented.

9.2.  Map operation

The Maps API core requirements class defines how to get a map. The Map operation requirements class specifies parameters supporting customization of the background of the map.

  bgcolor:
    name: bgcolor
    in: query
    description: |-
      Hexadecimal red-green-blue color value (0-255) or case-insensitive W3C web color name for the
      background color (default=0xFFFFFF). For a six digit hexadecimal value, the first and second
      digits specify the intensity of red. The third and fourth digits specify the intensity of
      green. The fifth and sixth digits specify the intensity of blue.
    required: false
    style: form
    explode: false
    schema:
      type: string
      default: 0xFFFFFF

  name: transparent
  in: query
  description:
    '(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

  void-color:
    name: void-color
    in: query
    description: |-
      Hexadecimal red-green-blue color value (0-255) or case-insensitive W3C web color name for the
      color of parts of the map outside of the valid CRS / projection areas (default=0xFFFFFF). For a six digit hexadecimal value, the first and second
      digits specify the intensity of red. The third and fourth digits specify the intensity of
      green. The fifth and sixth digits specify the intensity of blue.
    required: false
    style: form
    explode: false
    schema:
      type: string
      default: 0xFFFFFF

  name: void-transparent
  in: query
  description:
    '(defaults to the same value, specified or default, as `transparent`).'
  required: false
  style: form
  explode: false
  schema:
    type: boolean
    default: true

10.1.  Overview

In a deployed Web API incorporating elements of the OGC API — Maps Standard that provides access to a complex dataset formed by several geospatial data resources, selecting specific sub-resources of interest when requesting data from this dataset can be useful. The Collection Selection requirements class defines how to include a query parameter when requesting a resource (e.g., dataset tiles) to specify which geospatial data resources (e.g., collections) should be used to generate the response.

This requirements class is particularly useful in conjunction with the Requirements Class “Dataset Map” requirements class. However, sub-components of other resource types could be selected using this requirements class. A requirements class equivalent to this one is included in OGC API — Tiles.

10.2.  Operation

By default, the geospatial data resources included in the dataset maps responses are unspecified but should represent the dataset as a whole (but not necessarily the entire extent of the dataset content). This class adds a mechanism to select the geospatial data resources to be used to generate the derived resources (e.g., maps or map tiles). In practice this enables the capability to generate resources involving more than one geospatial data sub-resource.

  name: collections
  in: query
  required: false
  style: form
  explode: false
  schema:
    type: array
    items:
      type: string

www.example.com/map?collections=buildings,roads

10.3.  Service Metadata

The OGC API — Common — Part 1: Core Standard describes a mechanism to expose service-metadata for the API. See: https://docs.ogc.org/is/19-072/19-072.html#service-metadata-examples

  x-OGC-limits:
    type: object
    properties:
      maps:
        type: object
        properties:
          maxCollections:
            type: integer
            description:
              Maximum number of collections in the collections parameter. If absent the server imposes no limit.
            example: 5

11.1.  Overview

The Scaling requirements class describes how to scale a map for display by specifying a set of parameters that will define its size (width and height) in pixels of a display device that indirectly defines the scale of the map.

11.2.  Map Operation

The Maps API core requirements class defines how to retrieve a map. The Scaling requirements class specifies two alternative mechanisms for specifying the scale of the map, either implicitly by providing output dimensions using width and height parameters, or explicitly by providing a scale-denominator parameter.

  width:
    name: width
    in: query
    description:
      Width of the viewport in pixel units to present the response (the map subset).
    required: false
    style: form
    schema:
      type: number

  height:
    name: height
    in: query
    description:
      Height of the viewport in pixel units to present the response (the map subset).
    required: false
    style: form
    schema:
      type: number

  scale-denominator:
    name: scale-denominator
    in: query
    description:
      Number of units in the real-world corresponding to one such unit on the display.
    required: false
    style: form
    schema:
      type: number

11.3.  Scale and aspect ratio considerations (informative)

Since all parameters for map requests are optional, implementations must fill in missing parameters by using default values or computing appropriate values based on the parameters provided by the client and the specifics of the resource for which a map is being retrieved. Implementations supporting the “Scaling” requirements class should compute these values in a way that respects the scale of the map in all dimensions, and thus the aspect ratio of physical features being represented.

For a non-global map, and for implementations supporting both “Scaling” and “Subsetting” where clients can request a subset of the map for a small local region, implementations should consider the local scale of the map. For example, the applicable scale at the center, or most equatorial latitude of the map. This is as opposed to the global scale (e.g., at the equator). In addition, implementations should aim for the map scale to apply evenly to all dimensions. Consider a CRS such as Plate Carrée projection (CRS84 or EPSG:4326). When filling in an unspecified bbox and/or width and height parameters, this is possible by applying a different linear scaling for the horizontal and vertical dimensions between the CRS units and the pixel dimensions, based on the most equatorial latitude included in the subset.

Another example is using a World Mercator projection (EPSG:3395). Although the CRS unit is “meters”, they are only true meters at the equator. When computing a bounding box extending away from a center and a scale-denominator, the ratio between the CRS unit meters and true physical meters should be considered in order to accurately reflect the requested scale.

The ideal aspect ratio to maintain is the physical_width / physical_height = width / height, whereas physical_width and physical_height refer to the length of features in the horizontal and vertical dimensions respectively, and width and height are the dimensions of the returned map in pixels.

In the case of a Plate Carrée CRS, a simple way to accurately reflect the two-dimensional scale is to use the most equatorial latitude contained in the map response as the standard parallel of the equirectangular projection. This effectively implies scaling the horizontal distances of the Plate Carrée projection (assuming a standard parallel at 0°N) units by the cosine of that most equatorial latitude in order to get a more accurate physical horizontal distance.

In the case of a World Mercator CRS, an implementation could compute the number of CRS units separating one degree of longitude at the center latitude and compare that with the actual number of physical meters, based on the cos(lat) scaling mentioned above, and the length of a degree in meters (WGS84 semi-major axis of 6,378,137 m * Pi / 180, or 111,319.4907932735805 m).

For slightly more accurate calculations, the WGS84 ellipsoid, can be taken into account using the following polynomial equations (from Wikipedia):

metersPerDegLat = 111132.92 - 559.82 * cos(2*lat) + 1.175 * cos(4*lat) - 0.0023 * cos(6*lat)
metersPerDegLon = 111412.84 * cos(lat) - 93.5 * cos(3*lat) + 0.118 * cos(5*lat)

If maintaining the aspect ratio between physical units proves too difficult, implementations could fall back to maintaining the CRS unit aspect ratio instead. This way they ensure that (maxx - minx)/(maxy - miny) = width / height, where minx, miny are the lower bounds of the output CRS unit space in the returned map, maxx, maxy the upper bounds of that output CRS unit space on the map, and width and height are the dimensions of the returned map in pixels.

When neither width nor height is provided or implied, a good practical approach is to default to a reasonable size which is neither too low resolution, nor requiring too much computation power from the server.

When only one of the two dimension parameters is provided and no specific bounding box is requested, the value of the other could be used to return a square map by default.

When a bounding box is requested, the other dimension should be computed so as to preserve the aspect ratio.

When both dimensions are provided, but no bounding box, those dimensions should be used together with the default or requested center, and the scale denominator should be used to compute the bounding box.

Refer to the guidance for implementers provided in a section of the overview on the interactions of subsetting and scaling parameters. This includes the specific combinations of parameters that can be provided based on which requirements classes are implemented, and which parameter assume default values or should be computed in each case.

When bbox, width and height are all provided, as in implementations of the WMS Standard, the client enforces a specific aspect ratio, and these recommendations are not relevant. However, in general circumstances (e.g., 2D representations on a screen), the client should try to provide parameters that preserve the aspect ratio.

See also detailed step-by-step examples in an annex of computations to infer dimensions and infer bounding boxes based on specified parameters.

11.4.  Service Metadata

The OGC API — Common Standard describes a mechanism to expose service-metadata for the API. See Annex B.4 of OGC API — Common — Part 1: Core (OGC 19-072).

  x-OGC-limits:
    type: object
    properties:
      maps:
        type: object
        properties:
          maxWidth:
            type: integer
            description:
              Maximum width parameter value. If absent the server imposes no limit.
            example: 2048
          maxHeight:
            type: integer
            description:
              Maximum height parameter value. If absent the server imposes no limit.
            example: 2048
          maxPixels:
            type: integer
            description:
              Maximum  product of width and height parameter values. If absent the server imposes no limit.
            example: 4194304

  width:
    name: width
    in: query
    description:
      Width of the viewport to present the response in pixel units (the map subset).
    required: false
    style: form
    explode: false
    schema:
      type: number
      maximum: 2048
  height:
    name: height
    in: query
    description:
      Height of the viewport to present the response in pixel units (the map subset).
    required: false
    style: form
    explode: false
    schema:
      type: number
      maximum: 2048

Example — Example of the OpenAPI service metadata section

info:
  title: My Web API
  version: 1.0.0
  description: This example shows population of an OpenAPI Info element with identifying
    metadata for both the service and the service provider.
  x-OGC-limits:
    maps:
      maxWidth: 2048
      maxHeight: 2048
      maxPixels: 10000000

12.1.  Overview

The Display Resolution requirements class describes how to specify an accurate physical size of a pixel for the target display device or medium with a mm-per-pixel parameter. This is instead of a default 0.28 mm/pixel and allows applying symbology rules correctly. The physical pixel size is considered for establishing the relationship between the scale of the map and its output dimensions in pixels.

12.2.  Map Operation

The Display Resolution requirements class specifies the mm-per-pixel parameter to accurately interpret scale denominators and symbology rules.

  mm-per-pixel:
    name: mm-per-pixel
    in: query
    description:
      size (in millimeters) of a pixel of the rendering device that presents the response.
    required: false
    style: form
    schema:
      type: number

13.1.  Overview

The Maps API core requirements class defines the map resource. The Maps API core also defines a minimum set of metadata that enables a client application to formulate a map request. The Subsetting requirements class adds the ability to request an arbitrary 2D or 3D spatial subset of a map using either a bounding box specified using one of two equivalent syntaxes: a bbox parameter similar to the one in WMS 1.3, or a subset parameter similar to WCS 2.1. An alternative possibility is to specify a center point as well as width and/or height parameters taking into account the scale and the display resolution.

How the third (vertical) spatial dimension is applied to filter the output is left to the implementation and may depend on the nature of the data being represented and/or the negotiated output format. For example, the server could include features located within a vertical interval as part of a 2D map being rendered. In a second example, the extent of a 3D perspective view or a 3D model output would include only the subset of the vertical dimension specified. In a third example, a vertical profile could be returned for a single point or for a path across the other spatial dimensions. In this last example, the subset mechanism would likely only be used to subset the vertical dimension, while another mechanism would be used to select an arbitrary path in the horizontal dimensions (this requirements class does not specify how to provide a path in a map request).

13.2.  CRS for subsetting

In WMS 1.3 the CRS parameters had two purposes: Indicate the CRS of the data rendered in the map and the CRS of the coordinates of the bbox parameter. In the Maps API Standard, these two objectives have been separated. This section defines the CRS parameters for subsetting.

In this document the CRS for subsetting can have 3 possible values:

• https://www.opengis.net/def/crs/OGC/1.3/CRS84

• storageCrs indicated in the description of the geospatial resource, such as the collection or dataset.

• the one indicated in the crs parameter (the one picked for the map response). This possibility is described in the “CRS” requirements class.

The CRS advertised in the collection’s spatial extent is always in https://www.opengis.net/def/crs/OGC/1.3/CRS84 (for Earth centric data and as required by OGC API — Features). At least for OGC API — Maps and OGC API — Coverages, a native CRS (also called storage CRS) is defined. The Content-Crs: header (see Overview) specifies the CRS used in the response to avoid confusion.

  bbox-crs:
    name: bbox-crs
    in: query
    description: A URI (or safe CURIE) of the coordinate reference system for the coordinates specified in the `bbox` parameter. The valid values are [OGC:CRS84], the native (storage) CRS (if different), or the output `crs` (if specified).
    required: false
    schema:
      type: string
    example: https://www.opengis.net/def/crs/OGC/1.3/CRS84

  crs:
    name: subset-crs
    in: query
    description: A URI (or safe CURIE) of the coordinate reference system for the coordinates specified in the `subset` parameter. The valid values are [OGC:CRS84], the native (storage) CRS (if different), or the output `crs` (if specified).
    required: false
    schema:
      type: string
    example: https://www.opengis.net/def/crs/OGC/1.3/CRS84

  crs:
    name: center-crs
    in: query
    description: A URI (or safe CURIE) of the coordinate reference system for the coordinates specified in the `center` parameter. The valid values are [OGC:CRS84], the native (storage) CRS (if different), or the output `crs` (if specified).
    required: false
    schema:
      type: string
    example: https://www.opengis.net/def/crs/OGC/1.3/CRS84

13.3.  Subsetting coordinates

  bbox:
    name: bbox
    in: query
    description:
      Bounding box of the rendered map. The bounding box is provided as four or six coordinates

      * 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)

      The coordinate reference system and axis order of the values are indicated in the `bbox-crs` parameter or if the parameter is missing in https://www.opengis.net/def/crs/OGC/1.3/CRS84
    required: false
    schema:
      type: array
      oneOf:
      - minItems: 4
        maxItems: 4
      - minItems: 6
        maxItems: 6
      items:
        type: number
        format: double
    style: form
    explode: false

  SubsetSpec =       "subset" "=" axisName "(" intervalOrSingle ")"
  intervalOrSingle = interval / single
  interval =         low ":" high
  low =              single
  high =             single
  single =           number

  Where:
     `axisName` is an abbreviation identifying an axis starting by a lowercase or uppercase letter A-Z, optionally followed by any number of alphanumeric characters
     `number` is an integer or floating-point number.

13.4.  Response

A successful GET response is described in the Maps API core class (https://www.opengis.net/spec/ogcapi-maps-1/1.0/req/core).

Normally, the content partially outside the map bounding box will be clipped at the extent of the bounding box. This can be done efficiently when map subsets are in raster format (e.g., map tiles). However, maps containing features in vector format may not clip features that are partially outside to ensure continuity of features or for performance.

13.5.  Error conditions

A general summary of the HTTP status codes can be found in OGC API — Features — Part 1: Core, version 1.0 as well as in OGC API — Common.

If the CRS in the parameter value bbox-crs, subset-crs or center-crs is not supported by the server for this resource, or the parameter value is out-of-range, the status code of the response will be 400. If the map is not provided due to lack of data in the area, the status code of the response will be 204 or 404.

14.1.  Overview

The Date and Time Subsetting requirements class defines the way date and time can be used as a parameter to filter the content in the map resource.

14.2.  Describing the temporal extent

Depending on the type of resource, the way the temporal extent and the resolution of the datetime values that are available for the client to request are described may be different:

• For Collection maps, the collection description should specify the temporal extent of the resources. Maps can be requested inside this extent. If the extent is specified in a way that instant values are provided (e.g., by listing them or by including a resolution) then it should be possible to request maps for these instants.

• For Dataset maps, the landing page should specify the temporal extent of the dataset. Maps can be requested inside this extent.

14.3.  datetime query parameter request and response

The datetime parameter is a common building block that is shared with other OGC API Standards.

In the context of this requirements class, the datetime parameter selects a time instant or interval of the resource for which a map is requested.

The datetime parameter is defined as follows:

name: datetime
in: query
required: false
schema:
  type: string
style: form
explode: false

interval-bounded       = instant "/" instant
interval-bounded-start = [".."] "/" instant
interval-bounded-end   = instant "/" [".."]
interval-unbounded     = [".."] "/" [".."]
interval               = interval-bounded / interval-bounded-start / interval-bounded-end / interval-unbounded
datetime               = instant / interval

While the processing of the datetime parameter is specific to the resource and operation for which it is applied, there is a general set of requirements which all implementations must address.

“Intersects” means that the time (instant or period) specified in the parameter datetime includes a timestamp that is part of the temporal geometry of the resource (again, a time instant or period). For time periods this includes the start and end time.

Example 1 — A date-time

For resources with a temporal property that is a timestamp (like lastUpdate), a date-time value would match all resources where the temporal property is identical.

For resources with a temporal property that is a date or a time interval, a date-time value would match all resources where the timestamp is on that day or within the time interval.

Example 2 — Intervals

A template for the definition of the datetime parameter is available at datetime.yaml.

14.4.  subset=time query parameter request and response

The subset parameter is a common building block that is shared with other OGC API Standards. The subset parameter can be specified as an interval between lower and higher bound values or as a single value. An example of an interval is “between 1st of January 2021 and last day of May 2021” subset=time("2021-01-01":"2021-05-31"). An example of single value is “1st of January 2021 at 8am o’clock” subset=time("2021-01-01T08:00:00"). The time dimension can be used within the value specified for this parameter and should ideally match with the axis abbreviation specified in the CRS definition.

The subset parameter is defined as follows:

  SubsetSpec =       "subset" "=" "time" "(" intervalOrSingle ")"
  intervalOrSingle = interval / single
  interval =         low ":" high
  low =              single
  high =             single
  single =           number / text / "*"

  Where:
     `number` is an integer or floating-point number, and
     `text` is some general ASCII text (such as a time and date notation in RFC 3339 section 5.6) enclosed in double quotes (`"`, ASCII code 0x42).
  An asterisk (`*`) can be used for `low` or `high` to indicate the minimum/maximum value.
  A single asterisk can be used to indicate the high value.
  Support for `*` is required for time, but optional for spatial and other dimensions.

While the processing of the subset parameter is specific to the resource and operation for which it is applied, there is a general set of requirements which all implementations must address.

Example 1 — A date-time (subset)

For resources with a temporal property that is a timestamp (such as lastUpdate), a date-time value would match all resources where the temporal property is identical.

For resources with a temporal property that is a date or a time interval, a date-time value would match all resources where the timestamp is on that day or within the time interval.

Example 2 — Intervals (subset)

14.5.  Actual date & time response header

interval     = instant "/" instant
datetime     = instant / interval

14.6.  Closest date & time permission

14.7.  Response

A successful GET response is described in the Maps API core class (https://www.opengis.net/spec/ogcapi-maps-1/1.0/conf/core).

14.8.  Error conditions

A general summary of the HTTP status codes can be found in OGC API — Features — Part 1: Core, version 1.0 as well as in the OGC API – Common – Part 1: Core Standard.

If the parameter value for datetime is outside the domain of the collections, the status code of the response will be 400.

If the request returns no data (e.g., in combination with other types of subsetting), the status code of the response will be 204 or 404. If permission /per/datetime/closest is implemented, this situation is unlikely to occur.

15.1.  Overview

The General Subsetting requirements class defines the way a subset of the map resource in additional dimensions beyond spatial and temporal can be specified using the subset parameter. This functionality is defined as common building blocks shared with other OGC API Standards.

15.2.  Describing the extent of the additional dimensions

When implementing the General Subsetting requirements class, additional dimensions included in an extent description must use a uniform approach to describe the lower and upper bounds of those dimensions based on the intervals property. An example is found in an OGC API collection description response described in OGC API — Common — Part 2 and follows the JSON schema in https://schemas.opengis.net/ogcapi/maps/part1/1.0/openapi/schemas/common-geodata/collectionDesc.yaml. This is the same as with the temporal dimension.

15.3.  subset query parameter

The subset parameter can be specified as an interval between lower and higher bound values or as a single value. An example of an interval is “between 500.0 and 1013.0 hPa” subset=pressure(500:1013). An example of a single value is “750 hPa” subset=pressure(750). The dimensions that can be used within the value specified for this parameter are the axis abbreviations specified in the CRS definition. All additional dimensions listed in the extent as valid dimensions to be used with the subset parameter must be supported.

  SubsetSpec =       "subset" "=" axisName "(" intervalOrSingle ")"
  intervalOrSingle = interval / single
  interval =         low ":" high
  low =              single
  high =             single
  single =           number / text / "*"

  Where:
     `axisName` is an abbreviation identifying an axis starting by a lowercase or uppercase letter A-Z, optionally followed by any number of alphanumeric characters
     `number` is an integer or floating-point number, and
     `text` is some general ASCII text (such as a time and date notation in RFC 3339 section 5.6) enclosed in double-quotes (`"`, ASCII code 0x42).
  An asterisk (`*`) can be used for `low` or `high` to indicate the minimum/maximum value.
  For an additional temporal dimension, a single asterisk may be supported to indicate the latest available time.
  Support for `*` is required for time, but optional for spatial and other dimensions.

15.4.  Response

A successful GET response is described in the Maps API core class (https://www.opengis.net/spec/ogcapi-maps-1/1.0/conf/core).

15.5.  Error conditions

A general summary of the HTTP status codes can be found in the OGC API – Common – Part 1: Core Standard.

If the parameter value for the additional dimensions is outside the domain of the collections, the status code of the response will be 400.

Otherwise, if the request returns no data (e.g., in combination with other types of subsetting), the status code of the response will be 204 or 404.

16.1.  Overview

In WMS 1.3 the CRS parameters had two purposes: To indicate the CRS of the data rendered in the map and the CRS of the coordinates of the BBOX parameter. In the Maps API Standard, these two purposes have been separated. This section describes how to request a map in a specific CRS.

For OGC API — Maps and OGC API — Coverages, a native CRS (also called a storage CRS) is defined. The Content-Crs: header (see Overview) specifies the CRS used in the response to avoid confusion.

16.2.  Operation

The Maps API core requirements class defines how to retrieve a map. The CRS requirements class specifies parameters needed to retrieve a map in a particular output CRS.

  crs:
    name: crs
    in: query
    description: A coordinate reference system of the map response. A list of all supported CRS values can be found under the collection metadata.
    required: false
    schema:
      type: string
    example: https://www.opengis.net/def/crs/OGC/1.3/CRS84

17.1.  Overview

This requirements class defines the ability for clients to request a map whose content is rotated by a counterclockwise orientation specified in degrees, resulting in the viewing perspective being rotated by that same orientation in a clockwise direction.

17.2.  Operation

/map?orientation=40

Content-Crs: <https://www.opengis.net/def/crs/EPSG/0/3995>
Content-Orientation: 40
Content-Bbox: -10000,-4000,10000,4000

18.1.  Overview

The Custom Projection CRS requirements class defines the ability for clients to specify a custom projection CRS based on parameters defining a projection operation method, values for corresponding parameters, as well as a datum. This class also provides a parameter facilitating the task of selecting a projection center across different projections, for which the relevant latitude and longitude parameters differ. Angles are specified in degrees, whereas identifiers for methods, parameters and datums can be specified as URIs or safe CURIEs. Additionally, this requirements class defines a resource at /projectionsAndDatums listing the available operation methods and their associated parameters, as well as the possible datums that can be used as values for these parameters.

18.2.  Operation

/map?
   crs-proj-method=[epsg-method:9840]&
   crs-proj-center=Lat(30),Lon(40)&
   crs-datum=[epsg-datum:6326]

Content-Crs-Method: <https://www.opengis.net/def/method/EPSG/0/9840>
Content-Crs-Method-Params: <https://www.opengis.net/def/parameter/EPSG/0/8801>=30; <https://www.opengis.net/def/parameter/EPSG/0/8802>=40
Content-Crs-Datum: <https://www.opengis.net/def/datum/EPSG/0/6326>
Content-Bbox: -1000,-800,1000,800

18.3.  Available projections

{
   "methods":
   {
      "[epsg-method:9802]":
      {
         "title": "Lambert Conic Conformal",
         "description": "Lambert Conic Conformal projection (2 standard parallels)",
         "parameters":
         {
            "[epsg-parameter:8823]": { "$ref": "#/parameters/[epsg-parameter:8823]" },
            "[epsg-parameter:8824]": { "$ref": "#/parameters/[epsg-parameter:8824]" },
         },
         "centerLatParam": "[epsg-parameter:8823]"
      },
      "[epsg-method:9805]":
      {
         "title": "Mercator",
         "description": "Mercator projection",
         "parameters":
         {
            "[epsg-parameter:8823]": { "$ref": "#/parameters/[epsg-parameter:8823]" },
            "[epsg-parameter:8802]": { "$ref": "#/parameters/[epsg-parameter:8802]" }
         },
         "centerLatParam": "[epsg-parameter:8823]",
         "centerLonParam": "[epsg-parameter:8802]"
      },
      "[epsg-method:9807]":
      {
         "title": "Transverse Mercator",
         "description": "Transverse Mercator projection",
         "parameters":
         {
            "[epsg-parameter:8801]": { "$ref": "#/parameters/[epsg-parameter:8801]" },
            "[epsg-parameter:8802]": { "$ref": "#/parameters/[epsg-parameter:8802]" }
         },
         "centerLatParam": "[epsg-parameter:8801]",
         "centerLonParam": "[epsg-parameter:8802]"
      },
      "[epsg-method:9820]":
      {
         "title": "Lambert Azimuthal Equal Area",
         "description": "Lambert Azimuthal Equal Area projection",
         "parameters":
         {
            "epsg-parameter:8801": { "$ref": "#/parameters/[epsg-parameter:8801]" },
            "epsg-parameter:8802": { "$ref": "#/parameters/[epsg-parameter:8802]" }
         },
         "centerLatParam": "[epsg-parameter:8801]",
         "centerLonParam": "[epsg-parameter:8802]"
      },
      "[epsg-method:9829]":
      {
         "title": "Polar Stereographic",
         "description": "Polar Stereographic projection",
         "parameters":
         {
            "[epsg-parameter:8832]": { "$ref": "#/parameters/[epsg-parameter:8832]" },
            "[epsg-parameter:8833]": { "$ref": "#/parameters/[epsg-parameter:8833]" },
         },
         "centerLatParam": "[epsg-parameter:8832]",
         "centerLonParam": "[epsg-parameter:8833]"
      },
      "[epsg-method:9840]":
      {
         "title": "Orthographic",
         "description": "Orthographic projection",
         "parameters":
         {
            "epsg-parameter:8801": { "$ref": "#/parameters/[epsg-parameter:8801]" },
            "epsg-parameter:8802": { "$ref": "#/parameters/[epsg-parameter:8802]" }
         },
         "centerLatParam": "[epsg-parameter:8801]",
         "centerLonParam": "[epsg-parameter:8802]"
      },
      "mollweide":
      {
         "title": "Mollweide",
         "description": "Mollweide projection",
         "parameters":
         {
            "epsg-parameter:8802": { "$ref": "#/parameters/[epsg-parameter:8802]" }
         },
         "centerLonParam": "[epsg-parameter:8802]"
      }
   },
   "parameters":
   {
      "[epsg-parameter:8801]": { "title": "Latitude of natural origin" },
      "[epsg-parameter:8802]": { "title": "Longitude of natural origin" },
      "[epsg-parameter:8823]": { "title": "Latitude of 1st standard parallel" },
      "[epsg-parameter:8824]": { "title": "Latitude of 2nd standard parallel" },
      "[epsg-parameter:8832]": { "title": "Latitude of standard parallel" },
      "[epsg-parameter:8833]": { "title": "Longitude of origin" }
   },
   "datums":
   {
      "[epsg-datum:6230]":
      {
         "title": "European Datum 1950",
         "description": "European Datum 1950",
         "ellipsoid": "[epsg-ellipsoid:7022]"
      },
      "[epsg-datum:6326]":
      {
         "title": "WGS84",
         "description": "World Geodetic System 1984 ensemble",
         "ellipsoid": "[epsg-ellipsoid:7030]"
      }
   }
}

19.1.  Overview

The Collection Map requirements class specifies how to get maps from particular resources that contain geospatial data. Common resources that can contain geospatial data are the ones at the endpoint /collections/{collectionId} defined by the OGC API — Common or OGC API — Features Standards.

19.2.  General

The Collection Maps requirements class depends on the OGC API — Common — Part 2 — Geospatial data “collections” requirements classes but remains flexible and does not require using OGC API — Common — Part 1: Core. This allows for other API architectures outside the OGC API framework to implement OGC API – Maps requirements classes. However, OGC API servers are normally expected to implement OGC API — Common — Part 1. If so, in practice, this means that the landing page and the conformance page follow OGC API — Common — Part 1: Core. It is also possible to combine this building block with OGC API — Features — Part 1: Core version 1.0 that is not tied to OGC API — Common, which can also be substituted for the OGC API — Common — Part 2 dependency.

19.3.  Geospatial data resources

The Maps API Standard does not specify how geospatial resources are exposed in the API or if they can be retrieved as raw geospatial data (e.g., feature items or coverage cell values). The Maps API Standard expects that other OGC API Standards will define how to expose additional access mechanisms for these geospatial resources. Examples of such standards, all of which also implement OGC API — Common — Part 2: Geospatial data defining the /collections and /collections/{collectionId} paths, are:

• OGC API — Tiles (Tiled vector data and tiled coverage data)

• OGC API — Features (feature collections and features)

• OGC API — Coverages ( coverages and data cubes)

• OGC API — EDR (retrieval of spatiotemporal data)

• OGC API — Processes — Part 3: Workflows and Chaining (“Collection Output” requirements class)

The geospatial resources managed by these OGC API Standards (tiled vector data and tiled coverage data, feature collections and features, coverages and data cubes, spatiotemporal data and collection outputs as a result of a process execution) can be modified or complemented by other resources creating new endpoints indirectly giving access to the modified or complemented resources. Other OGC API Standards will define these mechanisms. An example of doing that is:

• OGC API — Styles which defines how to complement a geospatial resource by adding a style to it. The new resource is an overlap of both resources.

  NOTE 1:    The concept of a geospatial resource path substitutes the concept of “layer” in WMS but it intends to give a better integration between data visualization and data access.

Example — Fragment of a collection with a links array with one item of the array pointing to a map.

{
  "id": "buildings",
  "title": "Buildings in the city of Bonn",
  "description": "This collection contains buildings",
  "attribution": "OpenStreetMap",
  "extent": {
    "spatial" : {
      "bbox" : [ [ -2.2830363, 39.8188272, 6.6350523, 42.7010011 ] ]
      "storageCrsBbox" : [ [ 47736, 4421022, 797736, 4734022 ] ]
    }
  },
  "crs": ["[EPSG:32631]", "[EPSG:23031]", "[EPSG:4326]"],
  "storageCrs": "[EPSG:32631]",
  "storageCrsCoordinateEpoch": 2022.3,
  "links": [
    ...
    {
      "href": "https://data.example.com/collections/buildings/map",
      "rel": "https://www.opengis.net/def/rel/ogc/1.0/map",
      "type": "image/png",
    }
  ]
}

19.4.  Geospatial Data Resource Map

The core requirements class defines a map resource that is associated with an operation that contains the necessary information to later formulate a map request. Nevertheless, the Maps API core does not specify how to retrieve a map resource representing another resource. This section provides one possible workflow to support that use case from a geospatial data resource offered by an implementation of the Maps API.

20.1.  Overview

The Maps API core requirements class defines how to retrieve a map from a resource but does not detail which resources can be “mapped”. The Dataset Map requirements class defines how to retrieve a map resource from the dataset represented by the service. In other words, it provides the path to retrieve a map resource from the dataset behind the API endpoint. This is achieved by adding the map path to the root (a.k.a. the landing page) of the service.

20.2.  General

The Dataset Map describes how to serve maps for a dataset provided through a Web API instance implementing OGC API — Common — Part 1 requirements classes or OGC API — Features — Part 1: Core, version 1.0 as an alternative.

20.3.  Dataset API landing page

The landing page provides links to start exploring the resources offered by the API endpoint. The landing page mainly consists of a list of links to root resources. The Maps API Standard extension specifies a new link in the landing page for getting a dataset map.

{
  "title": "Dataset of the city of Bonn",
  "description": "Dataset containing collections such as buildings",
  "attribution": "OpenStreetMap",
  "extent": {
    "spatial" : {
         "bbox" : [ [ -2.2830363, 39.8188272, 6.6350523, 42.7010011 ] ],
         "storageCrsBbox" : [ [ 47736, 4421022, 797736, 4734022 ] ]
    }
  },
  "crs": ["EPSG:32631", "EPSG:23031", "EPSG:4326"],
  "storageCrs": "EPSG:32631",
  "storageCrsCoordinateEpoch": 2022.3,
  "links": [
    ...,
    {
      "href": "https://data.example.org/map",
      "rel": "https://www.opengis.net/def/rel/ogc/1.0/map",
      "type": "image/png",
      "title": "Map combining collections in the dataset"
    }
  ]
}

20.4.  Dataset maps

21.1.  Overview

The Styles Map requirements class specifies how to get maps from particular resources with a style applied by OGC API — Styles 1.0.

21.2.  Styled resources

Geospatial resources can be modified or complemented by styles creating new endpoints giving access to the modified or complemented resources. The way this is done to a dataset resource or to a collection is specified in the OGC API – Styles candidate Standard (as of December 2023).

Example — Fragment of a collection with a links array with one item of the array pointing to a map.

{
  "id": "buildings",
  "title": "Buildings in the city of Bonn",
  "description": "This collection contains buildings",
  "attribution": "OpenStreetMap",
  "extent": {
    ...
  }
  "links": [
    ...
    {
      "href": "https://data.example.com/collections/buildings/styles/dark/map",
      "rel": "https://www.opengis.net/def/rel/ogc/1.0/map",
      "type": "image/png",
    }
  ]
}

21.3.  Styled Resource Map

Styled resources are defined by the draft OGC API – Styles candidate Standard (as of December 2023). Nevertheless, that draft does not specify how to retrieve a map resource representing a styled resource. This section explains how to do this.

22.1.  Overview

Six requirements classes for map responses of OGC API — Maps implementations supporting various encodings are defined:

• PNG

• JPEG

• JPEG XL

• TIFF

• SVG

• HTML

  NOTE 1:    If maps are provided as tiles, this section should be ignored and the equivalent section in the OGC API – Tiles — Part 1: Core Standard should be used instead.

  NOTE 2:    None of the encodings specified here are mandatory and an implementation of the Maps API Standard may implement none of them but implement other encodings instead.

22.2.  Requirements Class “PNG”

PNG can be used for simple and immediate visualization in a web browser. For this use case, selecting an encoding that can be natively interpreted by the web browser is fundamental. The PNG format is one of the most popular formats. The PNG format is defined by the ISO Information technology Computer graphics and image processing ISO/IEC 15948:2004 Information technology — Computer graphics and image processing — Portable Network Graphics (PNG): Functional specification, also available from the World Wide Web Consortium (W3C) at https://www.w3.org/TR/PNG.

PNG supports lossless data compression. PNG supports palette-based images (with palettes of 24-bit RGB or 32-bit RGBA colors), grayscale images (with or without an alpha channel for transparency), and full-color non-palette-based RGB or RGBA images. The PNG working group designed the format for transferring images on the Internet, not for professional-quality print graphics. Therefore, non-RGB color spaces such as CMYK are not supported.

22.3.  Requirements Class “JPEG”

JPEG can be used for simple and immediate visualization in a web browser. In these circumstances, selecting an encoding that can be natively interpreted by the web browser is fundamental. The JPEG format is another popular format used in web applications. JPEG is defined by the ITU-T Recommendation T.81 and the ISO/IEC 10918-1 Standard.

The JPEG compression algorithm operates at its best on photographs and paintings with smooth variations of tone and color. It is best used for color and grayscale still images, but not for binary images. JPEG is also the most common format used by digital cameras. However, JPEG is not well suited for line drawings and other textual or iconic graphics, where the sharp contrasts between adjacent pixels can cause noticeable artifacts. Such images are better saved in a lossless graphics format such as PNG because JPEG uses a lossy compression method, which reduces image fidelity. As such, it is inappropriate for exact reproduction of imaging data.

22.4.  Requirements Class “JPEG XL”

JPEG XL is a relatively newer image format (compared to PNG and JPEG) with support for both lossy and lossless compression, alpha channels, high bit depths, high image quality, high compression ratio as well as high performance encoding and decoding. Free and open source libraries are available to read and write the format such as libjxl, released under a 3-clause BSD license. Although JPEG XL is not yet widely supported in web browsers at the time of writing this document, this situation is likely to change, and this requirements class is included due to the numerous advantages of JPEG XL over the traditional JPEG and PNG encoding, such as avoiding the need for compromising between high compression ratio, image quality and translucency. JPEG XL is defined by the multi-part ISO standard Information technology JPEG XL — image coding system, including ISO/IEC 18181-1:2024 Part 1: Core coding system and ISO/IEC 18181-2:2024 Part 2: File format.

22.5.  Requirements Class “TIFF”

One use case for maps is to distribute coverage values as regular grids. In these circumstances, selecting an encoding able to store grid values in their original format and eventually compress them using lossless compression is the right solution. The TIFF format is one of the older formats but is still one of the most popular formats to preserve arrays of data values and is defined by the Adobe Systems TIFF v6 specification.

TIFF is a flexible, adaptable file format for handling images and data. The ability to store data in a lossless format makes a TIFF file a useful image archive: Unlike standard JPEG files, a TIFF file using lossless compression such as PackBits or LZW compression.

22.6.  Requirements Class “SVG”

SVG is a commonly used format for representing vector objects on the web. SVG is simple to understand and well supported by tools and software libraries. Modern web browsers can render the SVG format directly and can also react to events generated by the user on the features visualized. That is why it is a good alternative for creating more interactive maps.

22.7.  Requirements Class “HTML”

Returning an HTML page with a full, operational map browser that allows for interactive navigation over the map (e.g., zoom and pan) is convenient for easy exploration of the data or for testing purposes.

23.1.  Overview

The “API Operations” requirements class defines requirements for providing a definition of a Web API implementing the Maps API Standard using an API definition language. This requirements class is intended to be combined with another requirements class specifying requirements for providing an API definition in a particular API definition language and / or version, such as the OpenAPI 3.0 requirements class defined in OGC API — Common — Part 1 :Core, or another eventual requirements class for OpenAPI 3.1.

23.2.  Web API description

The API definition provides a description of the complete list of API resources available at an endpoint. Reading this description, an application would have the full picture of the resources that the API implementation provides, how to retrieve resources, and what responses are expected for successful and unsuccessful requests. Without an API description or documentation, an application would be forced to traverse all links, starting with the landing page, to get an equivalent full list of resources.

The OpenAPI Specification 3.0 (oas30) requirements class from OGC API — Common — Part 1: Core provides many details on general requirements that can be used in conjunction with this requirements class. A later version of OGC API — Common may describe how to declare support for other versions of OpenAPI. This requirements class depends on the OGC API — Common landing page requirements class which provides details on how to request an API definition.

24.1.  Overview

Many current implementations of map clients are done in HTML and JavaScript on HTTPS. A common situation is that a single JavaScript client combines maps from different Web APIs and domains. In this case, Cross-Origin Resource Sharing (CORS) is applied by web browsers preventing access of data from a domain that is different from the Web API, if this is not explicitly allowed by the server headers. The CORS requirements class requires the implementation of CORS support for the Web APIs.

24.2.  CORS for JavaScript clients