diff --git a/API-strategie-modules/geospatial/config.js b/API-strategie-modules/geospatial/config.js index 5a735c41..783ea9ed 100644 --- a/API-strategie-modules/geospatial/config.js +++ b/API-strategie-modules/geospatial/config.js @@ -37,13 +37,14 @@ function custGHPG(respecConfig) var respecConfig = { //specStatus: "GN-CV", + //specStatus: "GN-VV", specStatus: "GN-WV", specType: "HR", pubDomain: "api", - //publishDate: "2022-09-30", - previousPublishDate: "2022-09-30", - previousMaturity: "GN-CV", - edDraftURI: "https://geonovum.github.io/KP-APIs/API-strategie-mod-geo/", + //publishDate: "2023-04-14", + previousPublishDate: "2023-04-14", + previousMaturity: "GN-VV", + edDraftURI: "https://geonovum.github.io/KP-APIs/API-strategie-modules/geospatial/", editors: [ { diff --git a/API-strategie-modules/geospatial/snapshot.html b/API-strategie-modules/geospatial/snapshot.html index b5cfed11..5919517e 100644 --- a/API-strategie-modules/geospatial/snapshot.html +++ b/API-strategie-modules/geospatial/snapshot.html @@ -1,4 +1,32 @@ -
-The API strategy consists of a core — a generic set of rules for all government APIs — and various modules that only pertain to a specific application. See API Strategie for a list of all parts of the API Strategy.
This document describes the Geospatial module, containing rules for geospatial content and functions in APIs.
The API strategy consists of a core — a generic set of rules for all government APIs — and various modules that only pertain to a specific application. See API Strategie for a list of all parts of the API Strategy.
This document describes the Geospatial module, containing rules for geospatial content and functions in APIs.
This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current Geonovum publications and the latest revision of this document can be found via https://www.geonovum.nl/geo-standaarden/alle-standaarden(in Dutch).
- Dit is een werkversie die op elk moment kan worden gewijzigd, verwijderd of vervangen door andere documenten. Het is geen door de werkgroep goedgekeurde consultatieversie. + Dit is een definitief concept van de nieuwe versie van de handreiking. Wijzigingen naar aanleiding van consultaties zijn doorgevoerd. -
In dit document zijn wijzigingen naar aanleiding van een deel van de consultatiereacties doorgevoerd. Nog niet alle consultatiereacties zijn verwerkt.Geospatial data is more specific in that it is explicitly located relative to the Earth.
Geospatial data is 'special' data in the sense that it typically indicates the location of things using geometry. This geometry allows geospatial functions such as 'find only the things located within this area' but also requires specific ways of handling. There are international regulations and standards for geospatial data that need to be taken into account in certain cases.
The Geospatial Module provides rules for the structuring of geospatial payloads and for functions in APIs to handle geospatial data.
In the geospatial module the abbreviation RD is used. RD refers to the "Stelsel van de Rijksdriehoeksmeting", this is the equivalent of EPSG code 28992 and EPSG name Amersfoort / RD New.
+The Geospatial Module provides rules for the structuring of geospatial payloads and for functions in APIs to handle geospatial data.
Providing requested resources is the essence of any API. This also applies to REST APIs that handle geospatial data. There are, however, some specific aspects when dealing with geospatial data in REST APIs. The most important aspects are described in this chapter:
When requesting information, for example about cadastral parcels, users do not necessarily require the geometry, even if they used a spatial filter. A name or parcel ID may be sufficient.
[rfc7946] describes the GeoJSON format, including a convention for describing 2D geometric objects in CRS84. In the Geospatial module of the API strategy we adopt the GeoJSON conventions for describing geometry objects. The convention is extended to allow alternative projections.
API-GEO-1: Support GeoJSON for geospatial APIs
-For representing 2D geometric information in an API, preferably use the convention for describing geometry as defined in the GeoJSON format [rfc7946]. Support GeoJSON as described in OGC API Features Requirements class 8.3 [ogcapi-features-1]. -
-application/geo+json
. This must be answered with a 200-response.A Coordinate Reference System (CRS) or Spatial Reference System (SRS) is a framework to measure locations on the earth surface as coordinates. Geometries consist of coordinates. To be able to measure the geometry's coordinates on the earth surface a CRS is required in conjunction with the coordinates.
CRSs are uniquely identified by means of a Spatial Reference System Identifier (SRID). -SRIDs may refer to different standards, for example EPSG Geodetic Parameter Dataset or Open Geospatial Consortium (OGC).
For a detailed description of CRSs see [hr-crs].
A client shall be able to determine a list of CRSs supported by an API.
API-GEO-5: Provide a list of all CRSs that are supported by the API
- // GET /api/v1/collections:
-CRSs may be grouped into ensemble CRSs, e.g. ETRS89 (EPSG:4258). The CRSs that are part of an ensemble CRS are called ensemble member CRSs or member CRSs that realize a ensemble CRS, e.g ETRF2000 (EPSG:9067) is a member of and realizes the ETRS89 (EPSG:4258) ensemble. When exchanging geometry an ensemble member CRS shall be used instead of an ensemble CRS when known and if accurate data is required. When transforming geometry from one CRS to another, use an ensemble member CRS (instead of an ensemble CRS) as input and output of coordinate transformation, when known and if accurate data is required.
For a detailed description of CRSs see [hr-crs].
A client shall be able to determine a list of CRSs supported by an API.
CRS-LIST: Provide a list of all CRSs that are supported by the API
+If a REST API shall comply to the OGC API Features specification then the API must provide an endpoint to determine a list of supported CRSs.
+ // GET /api/v1/collections:
+ /collections
endpoint./collections
endpoint of the API.collections
object with the crs
property.crs
property contains an array with CRS references in the form of URIs.epsg:CommonMetadata
element (xmlns:epsg="urn:x-ogp:spec:schema-xsd:EPSG:1.0:dataset
).If a REST API does not have to comply to the OGC API Features specification, e.g. when the API is used for administrative purposes, then the API shall also provide an endpoint to determine the supported CRSs.
+ // GET /api/v1/crss:
+ /crss
endpoint of the API.crs
property.crs
property contains an array with CRS references in the form of URIs.epsg:CommonMetadata
element (xmlns:epsg="urn:x-ogp:spec:schema-xsd:EPSG:1.0:dataset
).According to OGC API Features - part 1 - 7.13. Feature collections an OGC API Features API shall provide a GET operation on the /collections
endpoint which returns a collections object.
OGC API Features - part 2 - Coordinate Reference Systems by Reference [ogcapi-features-2] describes how to support different CRSs in your geospatial API. According to OGC API Features - part 2 - 6.2 Discovery and in particular Global list of CRS identifiers, a collections object provided by the API's /collections
endpoint may contain a global list of supported CRSs by means of the crs
property. This global CRS list applies to all feature collections delivered by the API, unless otherwise stated at a feature collection.
Each feature collection mentioned within the collections
list may also contain a crs
property if the set of supported CRSs differs from the global CRS list.
-If a feature collection supports exactly the same CRSs as mentioned in the global CRS list, then the crs
property may be omitted.
If a feature collection supports additional CRSs compared to the global CRS list in the collections object, then a reference to the global CRS list #/crs
may be added in the feature collection object and the URIs of the additional CRSs are added to the CRS list in the crs
property of the feature collection.
If a feature collection supports a different set of CRSs than the set defined in the global CRS list, then a reference to the global CRS list is omitted and only the URIs of the supported CRSs are added to the CRS list in the crs
property of the feature collection.
For clients, it may be helpful to know the CRS identifier that may be used to retrieve features from that collection without the need to apply a CRS transformation.
API-GEO-6: Make known in which CRS the geospatial data is stored.
-crs
property may be omitted.If a feature collection supports additional CRSs compared to the global CRS list in the collections object, then a reference to the global CRS list #/crs
may be added in the feature collection object and the URIs of the additional CRSs are added to the CRS list in the crs
property of the feature collection.
If a feature collection supports a different set of CRSs than the set defined in the global CRS list, then a reference to the global CRS list is omitted and only the URIs of the supported CRSs are added to the CRS list in the crs
property of the feature collection.
For clients, it may be helpful to know the CRS identifier that may be used to retrieve features from that collection without the need to apply a CRS transformation. If all features in a feature collection are stored using a particular CRS, the property storageCRS
shall be used to specify this CRS, in accordance with OGC API Features - part 2 - 6.2.2 Storage CRS. The value of this property shall be one of the CRSs supported by the API and advertised in the CRS list as stated in requirement 4 of OGC API Features - part 2 - 6.2.2 Storage CRS. If relevant, the epoch should also be specified, using the storageCRSCoordinateEpoch
property. For an explanation of the use of epochs with CRS, see the CRS Guidelines [hr-crs].
STORAGE-CRS: Make known in which CRS the geospatial data is stored by specifying the property storageCrs
in the collection object.
The value of this property shall be one of the CRSs the API supports.
+/collections
endpoint./collections
endpoint of the API.storageCRS
property.storageCRS
property is one of the URIs from the list of supported CRSs.If all features in a feature collection are stored using a particular CRS, the property storageCRS
shall be used to specify this CRS, in accordance with OGC API Features - part 2 - 6.2.2 Storage CRS. The value of this property shall be one of the CRSs supported by the API and advertised in the CRS list as stated in requirement 4 of OGC API Features - part 2 - 6.2.2 Storage CRS. If relevant, the epoch should also be specified, using the storageCRSCoordinateEpoch
property. For an explanation of the use of epochs with CRS, see the CRS Guidelines [hr-crs].
The default CRS for GeoJSON and for OGC API Features is WGS 84 with coordinate order longitude-latitude, also referred to as "CRS84". This refers to an ensemble of global CRSs that can be applied world-wide. Due to the datum and the tectonic displacements it is not accurate enough for local coordinate reference systems like ETRS89 (EPSG:4258, European), or RD (EPSG:28992, Dutch). For more information about coordinate reference systems, read the Geonovum guidelines on CRS [hr-crs].
Since most client-side mapping libraries use WGS 84 longitude-latitude (CRS84), the W3C/OGC Spatial Data on the Web working group recommends to use this as the default coordinate reference system. The API strategy caters for this supporting not only ETRS89 and RD, but also CRS84.
The default CRS, i.e. the CRS which is assumed when not specified by either the API or the client, is CRS84, in line with GeoJSON and OGC API Features.
API-GEO-7: Use CRS84 as the default coordinate reference system (CRS). Support CRS84 in line with OGC API Features Requirement 10. +
The default CRS for GeoJSON and for OGC API Features is CRS84 (OGC:CRS84), this is WGS 84 with coordinate order longitude-latitude. This refers to an ensemble of global CRSs that can be applied world-wide. For accurate applications the use of the CRS84 ensemble is not suitable. For more information about coordinate reference systems, read the Geonovum guidelines on CRS [hr-crs].
Since most client-side mapping libraries use WGS 84 longitude-latitude (CRS84), the W3C/OGC Spatial Data on the Web working group recommends to use this as the default coordinate reference system. The API strategy caters for this supporting not only ETRS89 and RD, but also CRS84.
The default CRS, i.e. the CRS which is assumed when not specified by either the API or the client, is CRS84, in line with GeoJSON and OGC API Features.
DEFAULT-CRS: Use CRS84 as the default coordinate reference system (CRS). Support CRS84 in line with OGC API Features Requirement 10.
The implication of this is, that if no CRS is explicitly included in the request, CRS84 is assumed. This rule also applies if the request uses POST.
-Content-Crs
header with the URI for CRS84 or CRS84h.In addition, support for ETRS89 and/or RD is required.
API-GEO-8: Use ETRS89 and/or RD when required, as these are the preferred coordinate reference systems (CRS) for Dutch geospatial data. Follow the Dutch Guideline for the use of CRSs [hr-crs].
-General usage of the European ETRS89 coordinate reference system (CRS) or RD/NAP is preferred, but is not the default CRS. Hence, one of these CRSs has to be explicitly included in each request when one of these CRSs is desired in the response or used in a request.
-In addition, support for ETRS89 and/or RD is required.
PREFERRED-CRS: Use ETRS89 and/or RD when required, as these are the preferred coordinate reference systems (CRS) for Dutch geospatial data. Follow the Dutch Guideline for the use of CRSs [hr-crs].
+General usage of the European ETRS89 coordinate reference system (CRS) or RDNAP is preferred, but is not the default CRS. Hence, one of these CRSs has to be explicitly included in each request when one of these CRSs is desired in the response or used in a request.
+Content-Crs
header with the URI for the requested CRS.The guiding principles for CRS support:
195427.520, 311611.840
). The X and Y coordinates are decimal numbers. The number of decimals in the fractional part may vary depending on the required accuracy. For an accuracy of 1 mm, 3 decimal places in the fractional part are sufficient. See Nauwkeurigheid van coördinaten in [hr-crs].API-GEO-9: When the API provides data in an ensemble CRS like WGS 84 or ETRS89 while it is known to what ensemble member CRS the data actually refers, this ensemble member should also be one of the CRSs supported by the API and advertised in the CRS list. E.g. when 2D data is transformed from RD with RDNAPTRANS not only EPSG:4258 should be supported but also EPSG::9067.
-/collections
endpoint.div class="rule" id="ensemble-member-crs">
ENSEMBLE-MEMBER-CRS: When the API provides data in an ensemble CRS like WGS 84 or ETRS89 while it is known to what ensemble member CRS the data actually refers, this ensemble member should also be one of the CRSs supported by the API and advertised in the CRS list.
For example when 2D data is transformed from RD with RDNAPTRANS not only ETRS89 (EPSG:4258) should be supported but also ETRF2000 (EPSG::9067).
/collections
endpoint.collections
object with the crs
property.crs
property contains an array with CRS references in the form of URIs.crs
property contains a URL for a ensemble CRS like ETRS89 (EPSG:4258), it also contains a URL for a ensemble member CRS like ETRF2000 (EPSG:9067).The CRS can be specified for request and response individually using parameters or headers.
API-GEO-10: Support passing the coordinate reference system (CRS) of the geometry in the request as a query parameter
+The CRS can be specified for request and response individually using parameters or headers.
BBOX-CRS-QUERY-PARAMETER: Support passing the coordinate reference system (CRS) of the bounding box in the request as a query parameter
Support the OGC API Features part 2 bbox-crs
parameter in conformance to the standard.
If a bounding box or geospatial filter is sent to the server without these parameters, the default CRS, CRS84, is assumed as specified in API-GEO-7.
+If a bounding box is sent to the server without these parameters, the default CRS, CRS84, is assumed as specified in DEFAULT-CRS.
If an invalid value, i.e. a CRS which is not in the list of supported CRSs, is given for one of these parameters, the server responds with an HTTP status code `400`.
-Additionally, if other types of geospatial filters are supported in the API besides bbox
:
-
bbox
parameter AND the bbox-crs
parameter.Content-Crs
HTTP header with the URI of the requested CRS identifier.FILTER-CRS-QUERY-PARAMETER: Support passing the coordinate reference system (CRS) of the geospatial filter in the request as a query parameter
Support the OGC API Features part 3 filter-crs
parameter in conformance to the standard.
If a geospatial filter is sent to the server without these parameters, the default CRS, CRS84, is assumed as specified in DEFAULT-CRS.
+If an invalid value, i.e. a CRS which is not in the list of supported CRSs, is given for one of these parameters, the server responds with an HTTP status code `400`.
+bbox
parameter AND the bbox-crs
parameter.filter-crs
parameter.bbox-crs
parameter.Content-Crs
HTTP header with the URI of the requested CRS identifier.Perform the same test for the filter-crs
parameter, if the server supports other types of geospatial filters.
In an API that supports the creation of items, POST requests with geospatial content in the body may be sent by a client to the server. In that case, it is necessary to indicate the CRS used, unless CRS84, the default CRS, is used.
API-GEO-11: When HTTP POST requests are supported, pass the coordinate reference system (CRS) of geometry in the request body as a header
+In an API that supports the creation and/or updating of items, POST, PUT or PATCH requests with geospatial content in the body may be sent by a client to the server. In that case, it is necessary to indicate the CRS used, unless CRS84 (OGC:CRS84), the default CRS, is used.
CONTENT-CRS-REQUEST-HEADER: When HTTP POST, PUT and/or PATCH requests are supported, pass the coordinate reference system (CRS) of geometry in the request body as a header
Support the OGC API Features part 4 Content-Crs
header in conformance to the standard.
Alternatively, if the feature representation supports expressing CRS information for each feature / geometry, the information can also be included in the feature representation. If no CRS is asserted, the default CRS, CRS84, is assumed, as stated in API-GEO-7.
-
In a request (i.e. when creating an item on the server):
+Alternatively, if the feature representation supports expressing CRS information for each feature / geometry, the information can also be included in the feature representation. If no CRS is asserted, the default CRS, CRS84, is assumed, as stated in DEFAULT-CRS.
+
In a request (i.e. when creating or updating an item on the server):
Content-Crs
header with the value of the CRS identifier for the spatial data in the body.201
in case a new item was created, or with status code 200
.API-GEO-12: Support passing the desired coordinate reference system (CRS) of the geometry in the response as a query parameter
+Repeat with a similar test voor PUT and/or PATCH if the server supports these.
+CRS-QUERY-PARAMETER: Support passing the desired coordinate reference system (CRS) of the geometry in the response as a query parameter
Support the OGC API Features part 2 crs
parameter in conformance to the standard.
crs
parameter.200
, and includes a Content-Crs
http header with the value of the requested CRS identifier.API-GEO-13: Assert the coordinate reference system (CRS) used in the response using a header
+CONTENT-CRS-RESPONSE-HEADER: Assert the coordinate reference system (CRS) used in the response using a header
Support the OGC API Features part 2 Content-Crs
header in conformance to the standard.
crs
parameter.Content-Crs
header with the value of the requested CRS identifier.Content-Crs
header with the URI of the requested CRS identifier if explicitly requested, or with the value http://www.opengis.net/def/crs/OGC/1.3/CRS84
if no CRS was explicitly requested.The API should be able to handle the following scenarios based on the rules stated above:
Geometry filter in request, geometry in response | The client indicates the CRS of the geometry filter in the request using bbox-crs or filter-crs as in the previous scenario, and requests a specific CRS for the geometries in the response using the crs parameter. The server indicates the geometry CRS in response using the Content-Crs header. |
-
Use the following URIs to specify the CRS:
Below is a list of the most commonly used CRSs in the Netherlands:
Name | +Code | +Type | Dimension | Scope | URI | @@ -972,76 +1496,102 @@|||
---|---|---|---|---|---|---|---|---|
Amersfoort / RD New | +28992 | +easting, northing (x, y) | 2D | Dutch | http://www.opengis.net/def/crs/EPSG/9.9.1/28992 | |||
Amersfoort / RD New + NAP height | +7415 | +easting, northing, height (x, y, h) | 3D | Dutch | http://www.opengis.net/def/crs/EPSG/9.9.1/7415 | |||
ETRS89 | +4258 | +latitude, longitude (φ, λ) | 2D | European | http://www.opengis.net/def/crs/EPSG/9.9.1/4258 | |||
ETRS89 | +4937 | +latitude, longitude, height (φ, λ, h) | 3D | European | http://www.opengis.net/def/crs/EPSG/9.9.1/4937 | |||
ETRF2000 - LatLon | +ETRF2000 | +7931 | +latitude, longitude, height (φ, λ, h) | +3D | +European | +http://www.opengis.net/def/crs/EPSG/9.9.1/7931 | +||
ETRF2000 | +9067 | +latitude, longitude (φ, λ) | 2D | European | http://www.opengis.net/def/crs/EPSG/9.9.1/9067 | |||
ETRF2000 - XYZ | +ITRF2014 | +7912 | +latitude, longitude, height (φ, λ, h) | 3D | -European | -http://www.opengis.net/def/crs/EPSG/9.9.1/7930 | +Global | +http://www.opengis.net/def/crs/EPSG/9.9.1/7912 |
ITRF2014 - LatLon | +ITRF2014 | +9000 | +latitude, longitude (φ, λ) | 2D | Global | http://www.opengis.net/def/crs/EPSG/9.9.1/9000 | ||
ITRF2014 - LatLonEHt | -3D | -Global | -http://www.opengis.net/def/crs/EPSG/9.9.1/7912 | -|||||
WGS 84 longitude-latitude | +CRS84 | +longitude, latitude (φ, λ) | 2D | Global | http://www.opengis.net/def/crs/OGC/1.3/CRS84 | |||
WGS 84 longitude-latitude-height | +CRS84h | +longitude, latitude, height (φ, λ, h) | 3D | Global | http://www.opengis.net/def/crs/OGC/0/CRS84h | |||
WGS 84 / Pseudo-Mercator | +3857 | +easting, northing (x, y) | 2D | Global | http://www.opengis.net/def/crs/EPSG/9.9.1/3857 |
In addition, the Geonovum CRS guidelines [hr-crs] describe how ETRS89 can be treated as equal to CRS84 under certain circumstances.
+For a more extensive overview of CRSs see: https://docs.geostandaarden.nl/crs/crs/#bijlage-a-crs-overzicht-tabel. +Note that the URI of each CRS contains a version number and that new versions may be released in future. +Before using a URI verify if newer versions are available and use the latest version.
In addition, the Geonovum CRS guidelines [hr-crs] describe how ETRS89 can be treated as equal to CRS84 (OGC:CRS84)under certain circumstances.
[JSON-FG] is a proposed standard extension of GeoJSON that adds CRS support.
-If the requested CRS is not the same as the storage CRS, a coordinate transformation is needed. Performance is increased when the dataset is transformed in multiple CRSs and stored in advance, and not transformed at the moment the request has arrived. In case of a transformation between RD and ETRS89, it is required that this transformation uses the latest version of the procedure of RDNAPTRANS™. This is certified software to transform between these coordinate reference systems.
If the requested CRS is not the same as the storage CRS, a coordinate transformation is needed. Performance is increased when the dataset is transformed in multiple CRSs and stored in advance, and not transformed at the moment the request has arrived. In case of a transformation between RD and ETRS89, it is required that this transformation uses the latest version of the procedure of RDNAPTRANS™.
INSPIRE is a European directive that forces data providers of geospatial datasets that belong to one of the 34 INSPIRE themes to publish the metadata, a viewservice and a download service. These services can also be APIs.
For the OGC-API Features, a special working group has worked on a document that proposes a technical approach for implementing the requirements set out in the INSPIRE Implementing Rules for Network Services [IRs for NS] based on the newly adopted OGC API - Features standard.
The extra requirements stated in this document concern:
These requirements should be met when an API serves features for an INSPIRE dataset.
An older method of specifying CRS in the headers of requests is described in this appendix. It was part of the first version of the "Geospatial Extension" which was never ratified. APIs that already support this old header method can add support for the current parameter method (see CRS negotiation) while still supporting the header method for a certain period. Supporting both the new method (using parameters) and the old (using headers) is trivial.
If a client specifies CRS using a parameter AND in the header, the parameter takes precedence and the CRS in the header is ignored.
What follows is the original description of the rule in the old Geospatial Extension.
Rule: Pass the coordinate reference system (CRS) of the request and the response in the headers
The coordinate reference system (CRS) for both the request and the response are passed as part of the request headers and response headers. In case this header is missing, send the HTTP status code 412 Precondition Failed
.
The following headers are purely meant for negotiation between the client and the server. Depending on the application, the request not only contains geometries but also specific meta data, e.g. the original realization including the collection date.
Request and response may be based on another coordinate reference system. This applies the HTTP-mechanism for content negotiation. The CRS of the geometry in the request (request body) is specified using the header Content-Crs
.
HTTP header | @@ -1107,7 +1683,7 @@EPSG:28992 | RD, Dutch |
---|
Rule: Use content negotiation to serve different CRSs
The CRS for the geometry in the response body is defined using the Accept-Crs
header. In case the API does not support the requested CRS, send the HTTP status code 406 Not Acceptable
.
Deprecated rule (was: API-41): Use content negotiation to serve different CRSs
The CRS for the geometry in the response body is defined using the Accept-Crs
header. In case the API does not support the requested CRS, send the HTTP status code 406 Not Acceptable
.