Open Geospatial Consortium

Submission Date: <yyyy-mm-dd>

Approval Date:  <yyyy-mm-dd>

Publication Date:  <yyyy-mm-dd>

External identifier of this OGC® document: http://www.opengis.net/doc/IS/ogcapi-features-7/1.0

Internal reference number of this OGC® document:    24-020

Version: 1.0.0-SNAPSHOT

Latest Published Draft: n/a

Category: OGC® Implementation Specification

Editors: Clemens Portele, Panagiotis (Peter) A. Vretanos

OGC API - Features - Part 7: Geometry Simplification

Copyright notice

Copyright © 2024 Open Geospatial Consortium

To obtain additional rights of use, visit http://www.opengeospatial.org/legal/

Warning

This document is not an OGC Standard. This document is distributed for review and comment. This document is subject to change without notice and may not be referred to as an OGC Standard.

Recipients of this document are invited to submit, with their comments, notification of any relevant patent rights of which they are aware and to provide supporting documentation.

Document type:    OGC® Standard

Document subtype:    Interface

Document stage:    Draft

Document language:  English

License Agreement

Permission is hereby granted by the Open Geospatial Consortium, ("Licensor"), free of charge and subject to the terms set forth below, to any person obtaining a copy of this Intellectual Property and any associated documentation, to deal in the Intellectual Property without restriction (except as set forth below), including without limitation the rights to implement, use, copy, modify, merge, publish, distribute, and/or sublicense copies of the Intellectual Property, and to permit persons to whom the Intellectual Property is furnished to do so, provided that all copyright notices on the intellectual property are retained intact and that each person to whom the Intellectual Property is furnished agrees to the terms of this Agreement.

If you modify the Intellectual Property, all copies of the modified Intellectual Property must include, in addition to the above copyright notice, a notice that the Intellectual Property includes modifications that have not been approved or adopted by LICENSOR.

THIS LICENSE IS A COPYRIGHT LICENSE ONLY, AND DOES NOT CONVEY ANY RIGHTS UNDER ANY PATENTS THAT MAY BE IN FORCE ANYWHERE IN THE WORLD.

THE INTELLECTUAL PROPERTY IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT OF THIRD PARTY RIGHTS. THE COPYRIGHT HOLDER OR HOLDERS INCLUDED IN THIS NOTICE DO NOT WARRANT THAT THE FUNCTIONS CONTAINED IN THE INTELLECTUAL PROPERTY WILL MEET YOUR REQUIREMENTS OR THAT THE OPERATION OF THE INTELLECTUAL PROPERTY WILL BE UNINTERRUPTED OR ERROR FREE. ANY USE OF THE INTELLECTUAL PROPERTY SHALL BE MADE ENTIRELY AT THE USER’S OWN RISK. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR ANY CONTRIBUTOR OF INTELLECTUAL PROPERTY RIGHTS TO THE INTELLECTUAL PROPERTY BE LIABLE FOR ANY CLAIM, OR ANY DIRECT, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING FROM ANY ALLEGED INFRINGEMENT OR ANY LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR UNDER ANY OTHER LEGAL THEORY, ARISING OUT OF OR IN CONNECTION WITH THE IMPLEMENTATION, USE, COMMERCIALIZATION OR PERFORMANCE OF THIS INTELLECTUAL PROPERTY.

This license is effective until terminated. You may terminate it at any time by destroying the Intellectual Property together with all copies in any form. The license will also terminate if you fail to comply with any term or condition of this Agreement. Except as provided in the following sentence, no such termination of this license shall require the termination of any third party end-user sublicense to the Intellectual Property which is in force as of the date of notice of such termination. In addition, should the Intellectual Property, or the operation of the Intellectual Property, infringe, or in LICENSOR’s sole opinion be likely to infringe, any patent, copyright, trademark or other right of a third party, you agree that LICENSOR, in its sole discretion, may terminate this license without any compensation or liability to you, your licensees or any other party. You agree upon termination of any kind to destroy or cause to be destroyed the Intellectual Property together with all copies in any form, whether held by you or by any third party.

Except as contained in this notice, the name of LICENSOR or of any other holder of a copyright in all or part of the Intellectual Property shall not be used in advertising or otherwise to promote the sale, use or other dealings in this Intellectual Property without prior written authorization of LICENSOR or such copyright holder. LICENSOR is and shall at all times be the sole entity that may authorize you or any third party to use certification marks, trademarks or other special designations to indicate compliance with any LICENSOR standards or specifications. This Agreement is governed by the laws of the Commonwealth of Massachusetts. The application to this Agreement of the United Nations Convention on Contracts for the International Sale of Goods is hereby expressly excluded. In the event any provision of this Agreement shall be deemed unenforceable, void or invalid, such provision shall be modified so as to make it valid and enforceable, and as so modified the entire Agreement shall remain in full force and effect. No decision, action or inaction by LICENSOR shall be construed to be a waiver of any rights or remedies available to it.

i. Abstract

OGC API standards define modular API building blocks to spatially enable Web APIs in a consistent way. The OpenAPI specification is used to define the API building blocks.

OGC API Features provides API building blocks to create, modify and query features on the Web. OGC API Features is comprised of multiple parts. Each part is a separate standard.

By default, the complete feature is returned in a response. However, the client sometimes needs the geometry only at a certain scale or zoom level for presenting the feature on a map. A capability to restrict the response to the necessary detail can reduce the volume of data to be transmitted.

To address this use case, this Standard specifies how the representation of geometry, for example in a feature, can be simplified using a query parameter.

Caution
 This is a DRAFT version of the 7th part of the OGC API - Features standards.

ii. Keywords

The following are keywords to be used by search engines and document catalogues.

OGC, OGC API, features, returnables, properties, geometry, geometry simplification

iii. Preface

Attention is drawn to the possibility that some of the elements of this document may be the subject of patent rights. The Open Geospatial Consortium Inc. shall not be held responsible for identifying any or all such patent rights.

Recipients of this document are requested to submit, with their comments, notification of any relevant patent claims or other intellectual property rights of which they may be aware that might be infringed by any implementation of the standard set forth in this document, and to provide supporting documentation.

iv. Submitting organizations

The following organizations submitted this document to the Open Geospatial Consortium (OGC):

  • CubeWerx Inc.

  • interactive instruments

v. Submitters

All questions regarding this submission should be directed to the editors or the submitters:

Name

Affiliation

Clemens Portele (editor)

interactive instruments

Panagiotis (Peter) A. Vretanos (editor)

CubeWerx Inc.

1. Scope

This document specifies a query parameter "zoom-level" that can be used to restrict the representation of geometries in a resource so that the coordinates are only provided at a certain level of detail.

2. Conformance

This standard defines two requirements classes:

The standardization target is Web API.

Conformance with this standard shall be checked using all the relevant tests specified in Annex A of this document for each conformance class. 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.

Table 1. Conformance class URIs
Conformance class URI

Geometry Simplification

http://www.opengis.net/spec/ogcapi-features-7/1.0/conf/zoom-level

Geometry Simplification (Features)

http://www.opengis.net/spec/ogcapi-features-7/1.0/conf/zoom-level-features

3. References

The following normative documents contain provisions that, through reference in this text, constitute provisions of this document. For dated references, subsequent amendments to, or revisions of, any of these publications do not apply. For undated references, the latest edition of the normative document referred to applies.

4. Terms, Definitions, Symbols and Abbreviated Terms

4.1. Terms and Definitions

This document used 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 standard 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.

endpoint

a web address (URI) at which access can be gained to a service or resource

OGC Web API

A Web API that implements one or more Conformance Classes from an OGC API Standard (OGC API - Features - Part 1: Core)

resource

entity that might be identified (Dublin Core Metadata Initiative - DCMI Metadata Terms)

Note
 The term "resource", when used in the context of an OGC API standard, should be understood to mean a web resource unless otherwise indicated.
returnable

the name of a property of a web resource that is available in representations of the resource when fetching the resource

web resource

a resource that is identified by a HTTP URI (OGC API - Features - Part 1: Core)

4.2. Abbreviated terms

API

Application Programming Interface

HTTP

Hypertext Transfer Protocol

HTTPS

Hypertext Transfer Protocol Secure

JSON

JavaScript Object Notation

OGC

Open Geospatial Consortium

URI

Uniform Resource Identifier

5. Conventions

5.1. Identifiers

The normative provisions in this standard are denoted by the URI http://www.opengis.net/spec/ogcapi-features-7/1.0.

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

6. Requirements Class "Geometry Simplification"

Requirements Class

http://www.opengis.net/spec/ogcapi-features-7/1.0/req/zoom-level

Target type

Web API

The Requirements Class "Geometry Simplification" specifies the "zoom-level" query parameter.

The query parameter is the zoom level / scale at which the requesting client will render geometries on a map.

The query parameter can be applied to web resources that can be represented as an object with one or more spatial properties or to resources that are collections of such objects; for example, a collection of features or a single feature.

Requirement 1

/req/zoom-level/parameter

A

If a web resource supports a query parameter "zoom-level", the query parameter SHALL be based on the following OpenAPI 3.0 fragment:

name: zoom-level
in: query
required: false
style: form
explode: false
schema:
  type: number
  minimum: 0
Note
 Decimal values are allowed as zoom levels, not just integers.

Requirement 2

/req/zoom-level/response

A

If the query parameter "zoom-level" is provided, geometries in the response SHALL be simplified so that they are suitable for rendering on a map at the zoom level in the popular "WebMercatorQuad" tiling scheme that is commonly used for visualizing geospatial data in maps.

B

The geometry type of the simplified geometry SHALL be consistent with the allowed geometry types for a geometry in the schema of the resource, if one is specified.

The zoom level is a measure of how far the map is zoomed in or out. The map scale is the ratio of the distance on the map to the corresponding distance on the ground. The map scale is reciprocal to the zoom level.

The mapping between zoom levels and map scales at the equator is shown in Table 2. This Standard uses the zoom level instead of the scale, because in web mapping zoom levels are more commonly used than map scales. The WebMercatorQuad tiling scheme assumes that the map is rendered in the Web Mercator projection and uses a tile size of 256x256.

The simplification of geometries is a lossy operation. The simplified geometries are approximations of the original geometries. The simplification will typically reduce the number of vertices in a curve or a surface ring. The degree of simplification of geometries is implementation-dependent.

Table 2. Zoom levels and the equivalent map scale
Zoom Level Map Scale

0

559082264.028717

1

279541132.014358

2

139770566.007179

3

69885283.0035897

4

34942641.5017948

5

17471320.7508974

6

8735660.37544871

7

4367830.18772435

8

2183915.09386217

9

1091957.54693108

10

545978.773465544

11

272989.386732772

12

136494.693366386

13

68247.346683193

14

34123.6733415964

15

17061.8366707982

16

8530.91833539913

17

4265.45916769956

18

2132.72958384978

19

1066.36479192489

20

533.182395962445

21

266.591197981222

22

133.295598990611

23

66.6477994953056

24

33.3238997476528

TODO: add example

7. Requirements Class "Geometry Simplification (Features)"

Requirements Class

http://www.opengis.net/spec/ogcapi-features-7/1.0/req/zoom-level-features

Target type

Web API

Dependency

Requirements Class "Geometry Simplification"

Dependency

OGC API - Features - Part 1: Core, Requirements Class "Core"

The Requirements Class "Geometry Simplification (Features)" binds the query parameter "zoom-level" to the Features and Feature resources. The requirements apply only to collections with no itemType or with a value "feature".

Requirement 3

/req/zoom-level-features/request

A

The HTTP GET operation on the /collections/{collectionId}/items and /collections/{collectionId}/items/{featureId} paths SHALL support the "zoom-level" query parameter as defined in Requirements Class "Geometry Simplification".

8. Security Considerations

See OGC API - Features - Part 1: Core, Clause 11.

Annex A: Abstract Test Suite (Normative)

Note
 Conformance classes and test cases for all requirements classes and requirements will be added once the requirements are stable.

Annex B: Revision History

Date Release Editor Primary clauses modified Description

2024-05-06

1.0.0-SNAPSHOT

C. Portele

all

initial version

Annex C: Bibliography

None