This GitHub repository contains OGC's multi-part standard for querying and retrieving maps on the web, "OGC API - Maps". The draft specification is available in HTML and PDF.
A Map provides a visual representation of relationships between things within a defined space. OGC API - Maps defines a standardized way to request a map to serve multiple purposes (e.g. displaying maps in web pages, mapping software, etc.). OGC API - Maps defines number of request parameters to control e.g., the dimensions, background, portions of the dataset to be included in the map, coordinate reference system used.
OGC API - Maps is part of the suite of OGC API standards that define modular API building blocks to enable access and use of location (i.e. geospatial) information in a consistent way. Information about other OGC APIs can be found online.
IMPORTANT NOTE: The description in this README.md can be older than the one in the standard draft. In case of discrepancy, the standard draft takes precedence (last update 2022-11-17).
OGC API - Maps specifies building blocks for Web APIs providing maps representing geospatial data. These building blocks can be combined with several origins such as the ones suggested in the Origin Conformance Classes. To build a full URL substitute the "..." for the origin URL (e.g., .../map becomes {datasetRoot}/collections/{collectionId}/map).
Get a map
GET .../map
Requests the default representation of the map. Additional parameters can be specified to offer more control on the map being returned.
Specify dimensions
GET .../map?width=600&height=400
Width and height allow you to define the resolution of the returned map.
Spatial subsetting
GET .../map?bbox-crs=[OGC:CRS84]&bbox=160.6,-55.95,-170,-25.89
Geospatial datasets can cover large areas. The Bounding Box (bbox) option allows you to specify a portion of the data for which you wish to retrieve a map. bbox is defined using the bbox-crs specified in the request (defaulting to CRS84 if not specified).
GET .../map?subset-crs=[OGC:CRS84]&subset=Lat(-55.95:-25.89),Lon(160.6:-170)
As an alternative to bbox, the subset query parameter can be used, with a syntax explicitly stating the axis for each bounding coordinate pairs.
Temporal subsetting
GET .../map?datetime=2020-08-20T14:12:05Z
Maps can be obtained for specific date and time.
GET .../map?subset=datetime("2020-08-20T14:12:05Z")
Date and time can also be specified using the subset query parameter.
Styled maps
GET .../styles/{styleId}/map
(In combination with OGC API - Styles) Requests the map to be returned in a specific style. This allows you to define the appearance of the map to suit your needs.
Alternate map CRS
GET .../map?crs=[EPSG:3395]
Maps use Coordinate Reference Systems (CRS) to define their position within a space (e.g., the Earth's surface). OGC API - Maps allows maps to be requested in any CRS supported by the server, and defaults to the native/storage CRS (not necessarily CRS84). This example will return the map according to a World Mercator Projection CRS.
Putting it all together
Multiple parameters can be combined together for a single request, e.g.:
GET .../styles/{styleId}/map?
width=600&height=400&
bbox-crs=[OGC:CRS84]&bbox=160.6,-55.95,-170,-25.89&
datetime=2020-08-20T14:12:05Z&
crs=[EPSG:3395]
GET .../styles/{styleId}/map?
crs=[EPSG:3395]&
width=600&height=400&
subset-crs=[OGC:CRS84]&
subset=Lat(-55.95:-25.89),Lon(160.6:-170),datetime("2020-08-20T14:12:05Z")
-
Map "Core" specifies a
.../mapsub-resource allowing to retrieve a map from some origin providing geospatial data (see Origin Conformance Classes). -
Map "TileSets" specifies how to retrieve map tilesets (e.g.,
.../map/tiles/{tileMatrixSetId}) metadata and map tiles (e.g.,.../map/tiles/{tileMatrixSetId}/{tileMatrix}/{tileRow}/{tileCol}) based on OGC API - Tiles building blocks.
- Map "Scaling" (
widthandheight) allows to specify a map resolution - Map "Spatial subsetting" (
bbox,bbox-crs-,subsetwithX,Y,E,N,Lat,Lonaxes) andsubset-crs) allows to retrieve a portion of a map - Map "Background" (
bgcolorandtransparent) allows to toggle background transparency and select a background color - Map "Collections Selection" (
collections=) allows to select geospatial data resources to include in the map - Map "Date & Time" (
datetime,subsetwithdatetimeaxis) allows to retrieve a map for a specific date and time - Map "CRS" (
crs) allows to select an output CRS other than the default native/storage CRS - Map "Cartographic Layout" allows enable and customize cartographic layout elements such as the legend, scale, compass
- Dataset Maps (
{datasetRoot}/map) allows to retrieve a map for an OGC API dataset as a whole, in combination with OGC API Common - Part 1: Core - Collection Maps (
{datasetRoot}/collections/{collectionId}/map) allows to retrieve a map for a specific OGC API collection, in combination with OGC API Common - Part 2: Geospatial Data. - "Styled Map" (
({datasetRoot}|{datasetRoot}/collections/{collectionId})/styles/{styleId}/map) allows to retrieve a map for a particular style, in combination with OGC API - Styles
- "OpenAPI definition" specifies additional requirements pertaining to operationIDs to identify Maps building blocks resources
- "PNG" specifies the ability to return maps in the PNG format
- "JPEG" specifies the ability to return maps in the JPEG format
- "TIFF" specifies the ability to return maps in the TIFF format (ideally, GeoTIFF)
- "HTML" specifies the ability to return maps as an HTML document (which might provide an interactive map)
OpenAPI building blocks, as well as a complete example OpenAPI definition of a Web API implementing this standard is available here. The README in that directory contains more information on how these building blocks can be assembled, and how an API description document can be bundled using swagger-cli.
The API definition can also be visualized here with SwaggerUI, including a working implementation which can be experimented with to try out the different end-points and responses.
Several implementations of the draft standard exist:
Implementations of the draft specification / demo services
OGC API - Maps follows on the footsteps of the OGC's Web Map Service (WMS) by enabling client applications to request maps of geospatial information on the web. However, OGC API - Maps is completely different from WMS, as OGC API - Maps focuses on a simple RESTful core specified as reusable OpenAPI components.
This is the CURRENT working version of this initiative. An Old version of the specification was a deliverable in Testbed-15.
The OGC API - Maps, OGC API - Styles, and OGC API - Tiles specifications are closely related and should be considered complementary.
Extensions may be defined in the future to provide additional capabilities:
- #97 Cartographic Layout Due to the complexity and flexibility of defining cartographic layout elements, it might be justified to move those capabilities in a separate extension Part 2 document in order to complete it without delaying Part 1: Core.
- #42 Custom Styles Defining how a client can provide a style with which to render a map (other than by publishing a style through OGC API - Styles)
- #81 GetFeatureInfo OGC API - Maps - Part 1: Core does not include an equivalent of WMS GetFeatureInfo, however the specification specifies how a majority of the use cases for it can be handled by also implementing API building blocks from OGC API - Features or OGC API - Coverages alongside the Maps implementation. The specification also describes how dynamic maps might be better handled by using OGC API - Tiles and vector/coverage tiles for use cases that previously used GetFeatureInfo in WMS. However, an extension for GetFeatureInfo might still be standardized if the need for it is still there.
Join the WMS mailing list.
Most work on the specification takes place in GitHub issues, so browse there to get a good idea of what is happening, as well as past decisions.
The contributor understands that any contributions, if accepted by the OGC Membership (and eventually the ISO/TC 211), shall be incorporated into the relevant OGC standards documents and that all copyright and intellectual property shall be vested to the OGC.
The WMS Standards Working Group (SWG) is the group at OGC that is responsible for the stewardship of the standard being developed in this GitHub repository, but is working to do as much work in public as possible.
Pull Requests from contributors are welcomed. However, please note that by sending a Pull Request or Commit to this GitHub repository, you are agreeing to the terms in the Observer Agreement.