I. Abstract
The OGC API — Maps — Part 1: Core Standard defines a Web API for requesting maps over the Web. A map is a portrayal of geographic information as a digital representation suitable for display on a rendering device (adapted from OGC 06-042/ISO 19128 OpenGIS® Web Map Server (WMS) Implementation Specification). Implementations of the OGC API — Maps Standard are designed for a client to easily:
Request a visual representation of one or more geospatial data layers in different styles;
Select by area, time and resolution of interest;
Change parameters such as the background color and coordinate reference systems.
A server that implements OGC API — Maps provides information about what maps are offered. OGC API — Maps addresses use cases similar to those addressed by the OGC 06-042/ISO 19128 OpenGIS® Web Map Server (WMS) Implementation Specification Standard.
II. Keywords
The following are keywords to be used by search engines and document catalogues.
ogcdoc, OGC document, API, openapi, maps
III. Preface
This document defines the OGC API — Maps — Part 1: Core Standard. Suggested additions, changes and comments on this standard are welcome and encouraged. Such suggestions may be submitted as an issue on the OGC API — Maps GitHub repository.
IV. Security considerations
Part 1 of the OGC API — Maps Standard only defines HTTP GET operations. As such the security considerations are limited to those applicable to a “read only” service. However, implementations of OGC API — Maps have to process resource paths and query parameters in a way that cannot be used by a client to inject malicious queries that makes available unforeseen data or even force the server to perform unwanted or dangerous actions. The following paragraphs enumerate some security considerations.
Due to the flexibility in generating maps, implementations of the OGC API — Maps Standard that are not optimized can easily encounter requests that take some time to resolve. If several of these requests are processed simultaneously, the server can become slow or unresponsive. Servers should take advantage of space partitioning structures that guarantee a deterministic maximum amount of data to process, such as the 2D Tile Matrix Set data structure (used in Cloud Optimized GeoTIFF, OGC API — Tiles, GeoPackage, etc.), which results in applying cartographic generalization for regions covering a larger area. Servers should also set and apply reasonable limits (e.g., maximum width, etc.) to prevent Denial of Service attacks.
Some OGC API — Maps deployments may assign different roles to different users that may result in accessing different collections or geographical areas that can be represented as maps. The access control can be described in the OpenAPI definition as discussed in OGC API — Common (https://docs.ogc.org/is/19-072/19-072.html#rc_oas30-security). Servers should take care that all resources in all representations and ways they can be requested (e.g., adding query parameters) are managed consistently.
Another security consideration is that maps generated by an endpoint of an OGC API — Maps implementation may be positionally incorrect and potentially guide users to wrong locations. One possible way this situation could happen is the manipulation by a malicious actor of a projection library installed on a server deployment.
Using HTTPS queries is preferred to using HTTP. The obvious reason is the map response returned by the endpoint of the OGC API — Maps implementation should be only accessible to the requesting user. Another reason is related to the public accessibility of the request itself. A request to the endpoint can reveal geographical extents that might be associated with private or sensitive information. For instance, users commonly visit “home” or “work” or “target places” (such as holiday destinations or churches). These requests can be used to predict personal or private activities.
V. Submitting Organizations
The following organizations submitted this Document to the Open Geospatial Consortium (OGC):
- Universitat Autònoma de Barcelona (CREAF)
- US Army Geospatial Center
- Ecere Corporation
- Esri
VI. Submitters
All questions regarding this submission should be directed to the editor or the submitters:
| Name | Affiliation |
|---|---|
| Joan Masó (editor) | Universitat Autònoma de Barcelona (CREAF) |
| Jérôme Jacovella-St-Louis (editor) | Ecere Corporation |
| Jeff Harrison | US Army Geospatial Center |
| Satish Sankaran | Esri |
VII. Legacy
The requirements and conformance classes defined in the OGC API — Maps — Part 1: Core Standard are grounded in the work done by many OGC Members in the different versions of the OGC Web Map Service (WMS) Standard. In particular, the work of Jean-François (Jeff) de La Beaujardière was instrumental in the consolidation of WMS. He participated in the original OGC Testbeds that resulted in WMS 1.0, back in April 2000. He became the editor of all subsequent versions, including WMS 1.1, WMS 1.1.1, WMS 1.3, and ISO 19128:2005.
VIII. Acknowledgements
Key work for crafting this OGC Standard was undertaken in the Open-Earth-Monitor Cyberinfrastructure (OEMC) project (https://earthmonitor.org/). The OEMC Project received funding from the European Union’s Horizon Europe research and innovation program under grant agreement number 101059548. Another project that provided key research is the All Data 4 Green Deal — An Integrated, FAIR Approach for the Common European Data Space (AD4GD) project (https://www.ad4gd.eu/). This project was co-funded by the European Union’s Horizon Europe research and innovation program under grant agreement number 101061001 as well as the United Kingdom and Switzerland. Another project that provided key research on applying OGC API Standards in the European digital twin of the ocean is the Integrated DigitaL Framework for Comprehensive Maritime Data and Information Services (ILIAD) project (https://ocean-twin.eu/). The ILIAD project received funding from the European Union’s Horizon Europe research and innovation program under grant agreement number 101037643.
Initial implementations and an Engineering Report constituting the first draft of this Standard were also produced thanks to funding from OGC Testbed 15. The editors also thank Natural Resources Canada for progress on this Standard achieved as part of GeoConnections 2020-2021 funded project number GNS20-21IFP02 (Modular OGC API Workflows).
1. Scope
The OGC API — Maps — Part 1: Core Standard (hereafter termed the Maps API) specifies operations to distribute maps and map tiles in a manner independent of the underlying data store. The Maps API can be described and documented using the OpenAPI specification and specifies resources for discovering and retrieving maps from a Web API.
Specifically, this OGC API — Maps Standard supports the following:
Discovery operations that allow an implementation instance of the Maps API Standard to be interrogated to determine capabilities and to retrieve information about this distribution of maps. This information includes the API definition (if also implementing OGC API — Common — Part 1: Core), as well as metadata about the data layers provided and the Coordinate Reference System(s) supported by the Web API implementation instance.
Retrieval operations that enable client applications to retrieve a map, using a default or pre-defined style, for an arbitrary geospatial resource, a dataset representing the full content available via the Maps API endpoint, or an individual collection of geospatial data representing part of the dataset.
Parameters for specifying the background and transparency of the map.
Parameters for specifying the scale of the map.
A parameter for specifying the pixel size of the device or medium on which the map is intended to be displayed.
Parameters for retrieving only a subset of the map.
A parameter for specifying a particular orientation for the map.
Parameters for specifying a Coordinate Reference System (CRS) for the map by reference or using a projection operation method (as defined by OGC 18-005r4 Abstract Specification Topic 2 Referencing by Coordinates), parameters for that method and a datum.
2. Conformance
Conformance with this standard shall be checked using all the relevant tests specified in Annex A (normative) of this document if the respective conformance URLs listed in Table 1 are present in the conformance response. The framework, concepts, and methodology for testing, and the criteria to be achieved to claim conformance are specified in the OGC Compliance Testing Policies and Procedures and the OGC Compliance Testing web site.
The standardization targets of all conformance classes are “Web APIs”.
The OGC API — Maps — Part 1: Core Standard defines twenty-three (23) conformance classes, each corresponding to one requirements class.
The core conformance class is the only mandatory class. All other conformance classes are optional and depend on the core.
These classes act as building blocks that should be implemented in combination with other more fundamental classes that provide support for documenting and formally describing a Web API (e.g., OpenAPI), listing supported conformance classes and listing available geospatial resources. Possible alternatives for these fundamental classes are OGC API — Common — Part 1: Core, OGC API — Features Part 1: Core or any other non-OGC classes that provide equivalent or alternative functionality.
The OGC API — Maps — Part 1: Core Standard is intended to define a minimal set of functions for a useful API for fine-grained access to retrieve maps. Additional classes may be specified in future parts of the OGC API — Maps series to add more capabilities or as vendor-specific extensions.
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
NOTE 1: Despite the use of …/map/tiles path templates in these examples which may become common in implementations of OGC API — Maps, these exact paths are only examples and are not required by OGC API — Tiles or by this Maps API Standard. Other paths are possible provided they are correctly described in the API description of the Web API and the links between resources.
NOTE 2: The “Custom Projection CRS” requirements class is not included in this sub-section because its primary focus is not defining resources, but the Custom Projection requirements class also specifies a /projectionsAndDatums resource listing values available for the parameters it defines.
2.2. Requirements classes defining parameters
These requirements classes of the Maps API define parameters that can be used together with any map resource.
NOTE 1: In the effort to make OGC API Standards more consistent, some parts of these requirements classes are expected to be imported by a future part of OGC API — Common or be registered in the building blocks registry. A future revision of OGC API — Maps could reference them and ensure consistency with the relevant common requirements.
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
NOTE 2: When implementing both this scaling requirements class and the spatial subsetting requirements class, the width and height can only be used for specifying the scale when a bbox or subset is also used for spatial subsetting, as otherwise they take on a subsetting role. When neither bbox nor subset is used for spatial subsetting, the scale-denominator parameter must be used to specify the scale.
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.
NOTE 3: When implementing both this spatial subsetting requirements class and the scaling requirements class, the width and height can only be used for specifying the scale when a bbox or subset is also used for spatial subsetting, as otherwise they take on a subsetting role. When neither bbox nor subset is used for spatial subsetting, the scale-denominator parameter must be used to specify the scale.
Example subsetting requests using center point and dimensions:
.../map?center=-120,60&width=1024&height=512
.../map?center-crs=[EPSG:3857]¢er=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]
NOTE 4: Every time that a URI to a CRS is required or recommended a CURIE equivalent is also valid. A CURIE {authority}[-{objectType}]:{id} would map to the following OGC URI: https://www.opengis.net/def/{objectType}/{authority}/0/{id}. If -{objectType} is missing, the default object type is crs.
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]
NOTE 5: This “Custom Projection CRS” requirements class also defines a /projectionsAndDatums resource listing values available for the parameters it defines.
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
3. Normative references
The following documents are referred to in the text in such a way that some or all of their content constitutes requirements of this document. For dated references, only the edition cited applies. For undated references, the latest edition of the referenced document (including any amendments) applies.
G. Klyne, C. Newman: IETF RFC 3339, Date and Time on the Internet: Timestamps. RFC Publisher (2002). https://www.rfc-editor.org/info/rfc3339.
Charles Heazel: OGC 19-072, OGC API — Common — Part 1: Core. Open Geospatial Consortium (2023). http://www.opengis.net/doc/is/ogcapi-common-1/1.0.0.
Clemens Portele, Panagiotis (Peter) A. Vretanos, Charles Heazel: OGC 17-069r4, OGC API — Features — Part 1: Core corrigendum. Open Geospatial Consortium (2022). http://www.opengis.net/doc/IS/ogcapi-features-1/1.0.1.
Joan Masó, Jérôme Jacovella-St-Louis: OGC 20-057, OGC API — Tiles — Part 1: Core. Open Geospatial Consortium (2022). http://www.opengis.net/doc/IS/ogcapi-tiles-1/1.0.0.
Joan Masó, Jérôme Jacovella-St-Louis: OGC 17-083r4, OGC Two Dimensional Tile Matrix Set and Tile Set Metadata. Open Geospatial Consortium (2022). http://www.opengis.net/doc/IS/tms/2.0.0.
M. Nottingham: IETF RFC 8288, Web Linking. RFC Publisher (2017). https://www.rfc-editor.org/info/rfc8288.
ISO/IEC: ISO/IEC 18181-1:2024, Information technology — JPEG XL image coding system — Part 1: Core coding system. International Organization for Standardization, International Electrotechnical Commission, Geneva (2024). https://www.iso.org/standard/85066.html.
ISO/IEC: ISO/IEC 18181-2:2024, Information technology — JPEG XL image coding system — Part 2: File format. International Organization for Standardization, International Electrotechnical Commission, Geneva (2024). https://www.iso.org/standard/85253.html.
ISO/IEC: ISO/IEC 10918-1, Information technology — Digital compression and coding of continuous-tone still images: Requirements and guidelines. International Organization for Standardization, International Electrotechnical Commission, Geneva https://www.iso.org/standard/18902.html.
ISO/IEC: ISO/IEC 15948, Information technology — Computer graphics and image processing — Portable Network Graphics (PNG): Functional specification. International Organization for Standardization, International Electrotechnical Commission, Geneva https://www.iso.org/standard/29581.html.
Open API Initiative: OpenAPI Specification 3.0.3, https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md
Adobe development association: TIFF Revision 6.0 Final — June 3, (1992) https://www.itu.int/itudoc/itu-t/com16/tiff-fx/docs/tiff6.pdf
W3C: Scalable Vector Graphics (SVG) v2. W3C Candidate Recommendation — October, (2018) https://www.w3.org/TR/SVG2/
WHATWG: HTML, Living Standard [online, viewed 2020-03-16]. Available at https://html.spec.whatwg.org/
NOTE: OGC API — Features — Part 1: Core has been included as a temporary normative reference. When OGC API — Common — Part 2: Geospatial data is released, the latter should replace OGC API — Features — Part 1: Core as a normative reference in a future version of OGC API — Maps — Part 1: Core.
4. Terms and definitions
This document uses the terms defined in OGC Policy Directive 49, which is based on the ISO/IEC Directives, Part 2, Rules for the structure and drafting of International Standards. In particular, the word “shall” (not “must”) is the verb form used to indicate a requirement to be strictly followed to conform to this document and OGC documents do not use the equivalent phrases in the ISO/IEC Directives, Part 2.
This document also uses terms defined in the OGC Standard for Modular specifications (OGC 08-131r3), also known as the ‘ModSpec’. The definitions of terms such as standard, specification, requirement, and conformance test are provided in the ModSpec.
For the purposes of this document, the following additional terms and definitions apply.
4.1. coordinate reference system
coordinate system that is related to the real world by a datum (source: ISO 19111)
4.2. coordinate system
set of mathematical rules for specifying how coordinates are to be assigned to points (source: ISO 19111)
4.3. data cube (or datacube)
a multi-dimensional (“n-D”) array of values. Sometimes, the term data cube is applied in contexts where these arrays are massively larger than the hosting computer’s main memory; examples include multi-terabyte/petabyte data warehouses and time series of image data.
4.4. geographic information
information concerning phenomena implicitly or explicitly associated with a location relative to the Earth (source: ISO 19101)
4.5. height
vertical elevation of an object in the real world above a reference point (height above the reference ellipsoid for geographic CRS such as [OGC:CRS84h] and [EPSG:4979]).
size, in pixels, of a viewport along its vertical axis
Note 1 to entry: Both the spatial subsetting and scaling requirements classes make use of the height query parameter. In both cases, the parameter refers to the height of the image in pixels, but the effect of specifying a fixed value for the parameter is different in each case (selecting the portion of the map to return in the image vs. resampling the map to the requested image size).
4.6. map
portrayal of geographic information as a digital representation suitable for display on a rendering device (adapted from OGC 06-042)
4.7. map background
areas of the map having no data to represent. They are commonly left transparent or filled with a background color
4.8. portrayal
presentation of information to humans (source: ISO 19117)
4.9. rendering device
medium or apparatus on which the map being retrieved will be displayed, whether temporarily (e.g., computer screen) or permanently (e.g., paper).
4.10. scale
ratio between the size of a map shown in the rendering device (commonly expressed in mm or inches) and the equivalent geographic bounding box of a map in the reality (commonly expressed in meters or miles). Commonly, the ratio is expressed as a fraction, where 1 unit in the rendering device is equivalent to n units in the reality (in the same units of measure). In this case, n is called a scale denominator.
4.11. viewport
portion of a rendering device where information is being visualized
Note 1 to entry: For the purpose of this document, the viewport refers to the portion of the map resource response, such as a digital image, where the actual geospatial content of the map is rendered. It excludes any outside margin portions of the image where layout elements such as titles or a legend may be included, as could be defined by an extension. For a two-dimensional viewport, its dimensions are named horizontal and vertical, corresponding to the width and height of the viewport, respectively.
4.12. width
size, in pixels, of a viewport along its horizontal axis
Note 1 to entry: Both the spatial subsetting and scaling requirements classes make use of the width query parameter. In both cases, the parameter refers to the width of the viewport in pixels, but the effect of specifying a fixed value for the parameter is different in each case (selecting the portion of the map to return in the image vs. resampling the map to the requested image size).
4.13. Web API
An Application Programming Interface (API) using an architectural style that is founded on the technologies of the Web (source: OGC 17-069r3)
Note 1 to entry: See Best Practice 24: Use Web Standards as the foundation of APIs (W3C Data on the Web Best Practices) for more detail.
5. Conventions
This section provides details of conventions used in this document.
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. Overview
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.
NOTE: Geospatial data resources (e.g., collections) replace the concept of layer in WMS and WMTS. The main difference is that layers in WMS and WMTS were not defined by other OGC API Standards and did not support other functionalities.
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)