OGC API - Routes - Part 1: Core

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-routes-1/1.0.0-draft.1

Internal reference number of this OGC® document: 21-000

Version: 1.0.0-draft.1

Category: OGC® Implementation Specification

Editor: Clemens Portele

OGC API - Routes - Part 1: Core

Copyright notice

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: if applicable

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.

Table of Contents

1. Scope
2. Conformance
3. References
4. Terms and Definitions
5. Conventions
6. Requirements for Web-based Routing
7. Routing API
8. Media Types
9. Security considerations
Annex A: Abstract Test Suite (Normative)
Annex B: Revision History
Annex C: Bibliography

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.

The OGC API family of standards is organized by resource type.

The OGC API - Routes - Part 1: Core standard specifies the fundamental API building blocks for interacting with the "route" resources. Routing is one of the most widely used geospatial operations in the world today.

This standard uses the Route Exchange Model to represent routes.

For providers of routes, the API building blocks and the Route Exchange Model provide a simple model to publish and offer those routes as resources for use by other systems.

For developers building infrastructures, the API building blocks provide a thin abstraction layer to leverage existing routing engines and algorithms using modern APIs - saving development and deployment time and costs.

For users, applications, and enterprises, the capability to get routes across a common API, regardless of the underlying routing data, engines, or algorithms, represents a significant step forward in geospatial interoperability.

Finally, the OGC recognizes that there are many environments for implementing open routing including on road, off road, air, sea, and many others. In addition, some communities may require specialized parameters in their Routing API.

Accordingly, any routing API will accept two waypoints, the start and end position. APIs are free to find routes within a single or across multiple environments, support additional waypoints between the start and end positions, and be extensible to support parameters required by diverse implementation communities.

ii. Keywords

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

OGC, Routing, Routing API, Route Exchange Model

iii. Preface

The work on this Standard started in the OGC Open Routing Pilot. After the pilot, the work on the specification continued in the OGC Routing Standards Working Group.

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

US Army Geospatial Center (AGC)
Ecere Corporation
interactive instruments GmbH
Skymantics LLC

v. Submitters

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

Name	Affiliation
Clemens Portele (editor)	interactive instruments GmbH
Jeff Harrison	US Army Geospatial Center (AGC)
Amy Youmans	US Army Geospatial Center (AGC)
Jérôme Jacovella-St-Louis	Ecere Corporation
Ignacio Correas	Skymantics LLC

Name

Affiliation

Clemens Portele (editor)

interactive instruments GmbH

Jeff Harrison

US Army Geospatial Center (AGC)

Amy Youmans

US Army Geospatial Center (AGC)

Jérôme Jacovella-St-Louis

Ecere Corporation

Ignacio Correas

Skymantics LLC

1. Scope

The OGC API - Routes - Part 1: Core Standard specifies the behavior of a Web API that allows applications to request routes in a manner independent of the underlying routing data set, routing engine or algorithm.

This standard defines modular API building blocks to:

Compute new routes,
Specify additional, commonly used routing parameters in addition to the start and end point of the route,
Manage routes on the server.

Routes are represented as a feature collection encoded in GeoJSON according to the OGC Route Exchange Model.

In addition, the API supports building blocks that enable clients to interrogate the API and retrieve the API definition, and a list of conformance classes supported by the API.

2. Conformance

The OGC API - Routes - Part 1: Core Standard defines the following eight requirements and conformance classes:

Minimal routing capability:
- Core: Routing based on start/end point.
Additional API capabilities:
- Manage routes: Store, fetch and delete routes stored on the server.
Additional routing parameters:
- Modes: Specify the type of transport when computing the route.
- Intermediate waypoints: Pass through additional points along the route.
- Height restrictions: Consider a specified vehicle height in meters against known height restrictions when computing the route.
- Weight restrictions: Consider a specified vehicle weight in metric tons (tonnes) against known weight restrictions when computing the route.
  
  Note
  A metric ton (tonne) is equivalent to 1,000 kg, which is larger than the U.S. ton.
- Obstacles: Avoid obstacles.
- Temporal constraints: Specify departure/arrival time.

Requirements for a single standardization target types are considered: Web API.

Conformance with this Standard shall be checked using all the relevant tests specified in Annex A (normative) of this document. 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.

In order to conform to this OGC® Standard, a software implementation shall choose to implement:

Any one of the conformance classes specified in Annex A (normative).

Note	All implementations must implement the Core conformance class.

Table 1. Conformance class URIs
Conformance class	URI
Core	`http://www.opengis.net/spec/ogcapi-routes-1/1.0.0-draft.1/conf/core`
Manage routes	`http://www.opengis.net/spec/ogcapi-routes-1/1.0.0-draft.1/conf/manage-routes`
Modes	`http://www.opengis.net/spec/ogcapi-routes-1/1.0.0-draft.1/conf/mode`
Intermediate waypoints	`http://www.opengis.net/spec/ogcapi-routes-1/1.0.0-draft.1/conf/intermediate-waypoints`
Height restrictions	`http://www.opengis.net/spec/ogcapi-routes-1/1.0.0-draft.1/conf/height`
Weight restrictions	`http://www.opengis.net/spec/ogcapi-routes-1/1.0.0-draft.1/conf/weight`
Obstacles	`http://www.opengis.net/spec/ogcapi-routes-1/1.0.0-draft.1/conf/obstacles`
Temporal constraints	`http://www.opengis.net/spec/ogcapi-routes-1/1.0.0-draft.1/conf/time`

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.

Internet Engineering Task Force (IETF). RFC 7946: The GeoJSON Format [online]. Edited by H. Butler, M. Daly, A. Doyle, S. Gillies, S. Hagen, T. Schaub. 2016 [viewed 2020-03-16]. Available at http://tools.ietf.org/rfc/rfc7946.txt
Internet Engineering Task Force (IETF). RFC 8288: Web Linking [online]. Edited by M. Nottingham. 2017 [viewed 2020-03-16]. Available at http://tools.ietf.org/rfc/rfc8288.txt
Open Geospatial Consortium (OGC). OGC 19-072: OGC API - Common - Part 1: Core (DRAFT) [online]. Edited by Ch. Heazel. 2021 [viewed 2021-12-22]. Available at https://docs.ogc.org/DRAFTS/19-072.html
Open Geospatial Consortium (OGC). OGC 21-001: OGC Route Exchange Model (DRAFT) [online]. Edited by C. Portele. 2021 [viewed 2021-12-22]. Available at https://docs.ogc.org/DRAFTS/21-001.html

4. 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.

cost function: a function that maps an event or values of one or more variables into a real number intuitively representing some "cost" associated with the event

EXAMPLE: For routing, typical "costs" that would be incurred are duration (fastest route) or distance (shortest route).

feature: abstraction of real world phenomena [ISO 19101-1:2014]
feature collection: a set of features from a dataset [OGC API - Features - Part 1: Core]
GeoJSON: geospatial data interchange format based on JavaScript Object Notation (JSON) [IETF RFC 7946]
route: sequence of connected segments providing directions to travel between specific waypoints

Note	This definition does not use the definition from ISO 19134:2007 because of use of terms such as "links" and "network".

waypoint: location that plays a role in choosing candidate routes potentially satisfying a routing request [ISO 19133:2005]
Web API: API using an architectural style that is founded on the technologies of the Web [OGC API - Features - Part 1: Core]

5. Conventions

5.1. Identifiers

The normative provisions in this Standard are denoted by the URI

http://www.opengis.net/spec/ogcapi-routes-1/1.0.0-draft.1

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

Note	The URI is temporary during the development of this specification. The final URI in the published standard will be `http://www.opengis.net/spec/ogcapi-routes-1/1.0`.

5.2. Link relations

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

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

describedby: Refers to a resource providing information about the link’s context.
item: The target IRI points to a resource that is a member of the collection represented by the context IRI.
self: Conveys an identifier for the link’s context.
service-desc: Identifies service description for the context that is primarily intended for consumption by machines.
service-doc: Identifies service documentation for the context that is primarily intended for human consumption.

The following link relation types registered by the OGC Naming Authority are used in this document:

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

Each resource representation includes an array of links. Implementations are free to add additional links for all resources provided by the API.

5.3. Use of HTTPS

For simplicity, this document in general 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." In fact, most servers are expected to use HTTPS, not HTTP.

5.4. References to OpenAPI components in normative statements

This document uses OpenAPI 3.0 fragments as examples and to formally state requirements. However, using OpenAPI 3.0 is not required for implementing a server.

In this document, fragments of OpenAPI definitions are shown in YAML (YAML Ain’t Markup Language) since YAML is easier to read than JSON and is typically used in OpenAPI editors. YAML is described by its authors as a human friendly data serialization standard for all programming languages.

Some normative statements (requirements, recommendations and permissions) use a phrase that a component in the API definition of the server must be "based upon" a schema or parameter component in the OGC schema repository.

In the case above, the following changes to the pre-defined OpenAPI component are permitted.

The range of values of a parameter or property may be extended (additional values) or constrained (if a subset of all possible values are applicable to the server). An example for a constrained range of values is to explicitly specify the supported values of a string parameter or property using an enum.
The default value of a parameter may be changed or added unless a requirement explicitly prohibits this.
Additional properties may be added to the schema definition of a Response Object.
Informative text may be changed or added, like comments or description properties.
If the server supports an XML encoding, xml properties may be added to the relevant OpenAPI schema components.

For API definitions that do not conform to the OpenAPI Specification 3.0, the normative statement should be interpreted in the context of the API definition language used.

5.5. Alignment with OGC API - Processes

The computation of a route is a process that operates on geospatial data that typically includes a routing dataset, which is a networked dataset that has a set of connected vertices and edges that have topological properties on which analysis can be done. This standard specifies the OGC API building blocks for Routes as API resources. An alternate implementation option for a Routing API is to implement routing as a process using the building blocks specified in the OGC API - Processes - Part 1: Core Standard. Both building blocks have been aligned so that the same route definition can be sent to both API options. The alignment between OGC API Processes and OGC API Routes is mostly transparent to developers, except for two extensions needed for the Route Definition object that is submitted in a POST request to the Routes resource (path /routes) that would not be necessary for the Routes API:

An extra "inputs" member that contains the route definition object;
Extra "value" members in the waypoints, obstacles and temporal constraints objects.

6. Requirements for Web-based Routing

This section describes the requirements that this standard supports.

The bare minimum requirement for a Routing API is to compute a route based on a start and end point. The resulting route is encoded using the Route Exchange Model (REM).

Besides this basic requirement, additional optional requirements to the API are:

Storage and management of computed routes

Additionally, a Routing API may support the following optional routing parameters:

Capability to add additional intermediate waypoints.
Select a transport mode for the route computation.
Apply a height restriction to the route computation.
Apply a weight restriction to the route computation.
Ability to define obstacles that have to be avoided.
Specify departure or arrival times.

7. Routing API

7.1. Overview

This clause specifies the API building blocks for a Web API for Routing based on the OGC Web API Guidelines, OGC API Common and the OGC Route Exchange Model. The API building blocks are specified in the following requirements/conformance classes:

Minimal routing capability:
- Core: Routing based on start/end point.
Additional API capabilities:
- Manage routes: Store, fetch and delete routes stored on the server.
Additional routing parameters:
- Mode: Specify the type of transport when computing the route.
- Intermediate waypoints: Pass through additional points along the route.
- Height restrictions: Consider a specified vehicle height in meters against known height restrictions when computing the route.
- Weight restrictions: Consider a specified vehicle weight in metric tons (tonnes) against known weight restrictions when computing the route.
- Obstacles: Avoid obstacles.
- Temporal constraints: Specify departure/arrival time.

The API building blocks support the resources and operations listed in Table 1.

Table 2. Overview of resources and applicable HTTP methods and media types
Resource	Path	HTTP method	Request media type	Response media type	Document reference
Landing page	`/`	GET	n/a	`application/json`	API landing page
Conformance declaration	`/conformance`	GET	n/a	`application/json`	Declaration of conformance classes
Routes	`/routes`	POST	`application/json`	`application/geo+json`	Compute a new route
Routes	`/routes`	GET	n/a	`application/json`	Fetch routes
Route	`/routes/{routeId}`	GET	n/a	`application/geo+json`	Fetch a route
Route	`/routes/{routeId}`	DELETE	n/a	n/a	Delete a route
Route definition	`/routes/{routeId} /definition`	GET	n/a	`application/json`	Fetch the definition of a route

The first three operations are available in the 'Core' requirements class. All routing APIs implementing this Standard will support them. The other four operations are implemented by routing APIs implementing the 'Manage routes' requirements class.

7.2. Requirements Class "Core"

Requirements Class

http://www.opengis.net/spec/ogcapi-routes-1/1.0.0-draft.1/req/core

Target type

Web API

Dependency

OGC API - Common - Part 1: Core, Requirements Classes "Core", "Landing Page", "JSON"

Indirect Dependency

GeoJSON

Indirect Dependency

OGC Route Exchange Model, Requirements Class "Route Exchange Model"

Indirect Dependency

Web Linking

7.2.1. OGC API - Common - Part 1: Core

At the time of writing, OGC API - Common - Part 1: Core has been voted on, but is not yet published. The requirements classes "Core", "Landing Page" and "JSON" have to be supported. This includes support for the resources Landing Page, Conformance Declaration and API Definition. Support for the "HTML" and "OpenAPI 3.0" requirements classes is recommended.

Note	Version 1.0 of this Standard will either reference a published version of the OGC API - Common - Part 1: Standard or directly include the relevant provisions from the requirements classes "Core", "Landing Page" and "JSON".

7.2.2. API landing page

Requirement 1

/req/core/landing-page-link

The content of the landing page response SHALL include a link to the Routes resource at path /routes (link relation type http://www.opengis.net/def/rel/ogc/1.0/routes).

The following is an example of a landing page of a routing API that implements this Standard.

Example 1. Landing page

{
  "links": [
    {
      "href": "https://example.org/api/routing/v1",
      "rel": "self",
      "type": "application/json",
      "title": "This document"
    },
    {
      "href": "https://example.org/api/routing/v1/api",
      "rel": "service-desc",
      "type": "application/vnd.oai.openapi+json;version=3.0",
      "title": "The API definition in OpenAPI JSON"
    },
    {
      "href": "https://example.org/api/routing/v1/api.html",
      "rel": "service-doc",
      "type": "text/html",
      "title": "The API documentation in HTML"
    },
    {
      "href": "https://example.org/api/routing/v1/conformance",
      "rel": "http://www.opengis.net/def/rel/ogc/1.0/conformance",
      "type": "application/json",
      "title": "The list of conformance classes implemented by this API"
    },
    {
      "href": "https://example.org/api/routing/v1/routes",
      "rel": "http://www.opengis.net/def/rel/ogc/1.0/routes",
      "type": "application/json",
      "title": "Compute routes"
    }
  ]
}

7.2.3. Declaration of conformance classes

The following is an example of the conformance declaration of a routing API that implements all requirements classes specified in this Standard.

Requirements classes can support options and parsing the API definition may be unnecessarily costly for clients to determine the options. The conformance declaration, therefore, is extended to support stating the options of a conformance class in a properties member where the conformance class URI is the key for the options of that conformance class.

Example 2. Conformance declaration

{
  "conformsTo": [
    "http://www.opengis.net/spec/ogcapi-routes-1/1.0.0-draft.1/conf/core",
    "http://www.opengis.net/spec/ogcapi-routes-1/1.0.0-draft.1/conf/mode",
    "http://www.opengis.net/spec/ogcapi-routes-1/1.0.0-draft.1/conf/intermediate-waypoints",
    "http://www.opengis.net/spec/ogcapi-routes-1/1.0.0-draft.1/conf/height",
    "http://www.opengis.net/spec/ogcapi-routes-1/1.0.0-draft.1/conf/weight",
    "http://www.opengis.net/spec/ogcapi-routes-1/1.0.0-draft.1/conf/obstacles",
    "http://www.opengis.net/spec/ogcapi-routes-1/1.0.0-draft.1/conf/time",
    "http://www.opengis.net/spec/ogcapi-routes-1/1.0.0-draft.1/conf/manage-routes"
  ],
  "properties": {
    "http://www.opengis.net/spec/ogcapi-routes-1/1.0.0-draft.1/conf/core": {
      "preferences": [
        "fastest",
        "shortest"
      ]
    },
    "http://www.opengis.net/spec/ogcapi-routes-1/1.0.0-draft.1/conf/mode": {
      "modes": [
        "motor-vehicle",
        "bicycle",
        "pedestrian"
      ]
    }
  }
}

7.2.4. Geometries

All implementations of this Standard will support geometries encoded as GeoJSON. This includes the waypoints in the route definition and the geometries of all features in the route exchange model (overview, start, end, segments).

All geometries use coordinates based on the World Geodetic System 1984 (WGS 84) datum, i.e., the coordinate reference system (CRS) used by Global Positioning System (GPS). In GeoJSON, a coordinate is an array of numbers. The first two elements are longitude and latitude, or easting and northing, precisely in that order and specified in decimal numbers. Ellipsoidal height may be included as an optional third element.

Support for additional encodings or additional CRSs may be specified in future extensions.

7.2.5. Routes

Compute a new route

This operation creates a new route. The payload of the request specifies the definition of the new route.

The core requirements class supports a minimum route definition by using two waypoints: The start and end point of the route.

In addition, clients can select a cost function, as the routing preference. The API declares the cost functions that it supports in the Conformance Declaration resource and in the API definition.

An optional name for the route can be provided. The name can be used as the title in links to the route and the name is also included in the route itself.

Requirement 2

/req/core/compute-route-op

The server SHALL support the HTTP POST operation at the path /routes.

The server SHALL accept a route definition in the content of the request based upon the following OpenAPI 3.0 schema:

type: object
required:
  - inputs
properties:
  inputs:
    type: object
    required:
      - waypoints
    properties:
      name:
        type: string
      waypoints:
        type: object
        required:
          - value
        properties:
          value:
            type: object
            required:
              - type
              - coordinates
            properties:
              type:
                type: string
                enum:
                  - MultiPoint
              coordinates:
                type: array
                minItems: 2
                maxItems: 2
                items:
                  title: Points along the route
                  type: array
                  minItems: 2
                  items:
                    type: number
      preference:
        type: string

Additional members in the route definition can be ignored.

Note

The content model of the route definition object has been designed so that it can also be the content of a process execution request according to the OGC API - Processes - Part 1: Core Standard. The motivation for this is the following: The computation of a route is a process that operates on geospatial data that typically includes a routing dataset, which is a networked dataset that has a set of connected vertices and edges that have topological properties on which analysis can be done. This standard specifies the OGC API building blocks for Routes as API resources. An alternate implementation option for a routing API could be to implement routing as a Process resource using the building blocks specified in the OGC API - Processes - Part 1: Core Standard. The current design allows that the same request can be sent to both API options to compute a new route. The decision to align the payload with OGC API Processes adds additional members "inputs" and "value" that would otherwise be unnecessary.

Requirement 3

/req/core/conformance-values

The content of the conformance declaration response at path /conformance SHALL list all values that the preference parameter supports, based upon the following OpenAPI 3.0 schema:

type: object
required:
  - properties
properties:
  properties:
    type: object
    required:
      - http://www.opengis.net/spec/ogcapi-routes-1/1.0.0-draft.1/conf/core
    properties:
      http://www.opengis.net/spec/ogcapi-routes-1/1.0.0-draft.1/conf/core:
        type: object
        required:
          - preferences
        properties:
          preferences:
            type: array
            items:
              minItems: 1
              type: string

See Conformance declaration for an example.

Note

The plan is to register well-known cost functions with the OGC that are recommended for use, where applicable. Once a register has been established, this Standard will be updated. Until then, use fastest for cost functions that optimize duration and shortest for cost functions that optimize distance.

The property "preference" in a route definition is a client hint and the server determines how to consider the preference in the computation of the route. If no preference is specified in the route definition the first value listed in the array is considered the default cost function.

Requirement 4

/req/core/compute-route-success

A successful, synchronous execution of the operation SHALL be reported as a response with a HTTP status code 200.

By default the response content SHALL conform to the requirements class "Route Exchange Model".

Note	This requirements class provides no mechanism to change the default, and future extensions could return another route representation, such as an OGC GeoPackage.

Recommendation 1

/rec/core/compute-route-success

If the request included an Accept-Language header, the server SHOULD try to honor the request and otherwise fall back to an available language.

The response SHOULD include a Content-Language header with the language used for instructions and names, in particular road/street names, if the language of the text values is known and the same language is used for all text fields in the route.

This requirements class only specifies requirements for the synchronous execution of a routing request. Requirements for the asynchronous execution can be added in a future extension to this Standard.

Requirement 5

/req/core/error

If the request does not conform to the requirements /req/core/compute-route-op and /req/core/conformance-values (e.g., the route definition is not schema valid, the waypoints coordinates are invalid, or the preference value is invalid) a response with status code 400 SHALL be returned.

If the request is valid, but the server is not able to process the request (e.g., the server has insufficient route network data for the request), a response with status code 422 SHALL be returned.

Example 3. Route definition

The following is an example request for the fastest route from Reagan National Airport to the U.S. Capitol building in Washington, D.C.

{
  "inputs": {
    "name": "Reagan Airport to Capitol",
    "waypoints": {
      "value": {
        "type": "MultiPoint",
        "coordinates": [
          [
            -77.037722,
            38.851444
          ],
          [
            -77.009003,
            38.889931
          ]
        ]
      }
    },
    "preference": "fastest"
  }
}

Example 4. The route response:

{
  "type": "FeatureCollection",
  "name": "Reagan Airport to Capitol",
  "features": [
    {
      "type": "Feature",
      "id": 1,
      "geometry": {
        "type": "LineString",
        "coordinates": [
          [
            -77.037722,
            38.851444
          ],
          ...,
          [
            -77.012520,
            38.889780
          ]
        ]
      },
      "properties": {
        "featureType": "route overview",
        "length_m": 8213,
        "duration_s": 483
      }
    },
    {
      "type": "Feature",
      "id": 2,
      "geometry": {
        "type": "Point",
        "coordinates": [
          -77.037722,
          38.851444
        ]
      },
      "properties": {
        "featureType": "start"
      }
    },
    {
      "type": "Feature",
      "id": 3,
      "geometry": {
        "type": "Point",
        "coordinates": [
          -77.041674,
          38.871088
        ]
      },
      "properties": {
        "featureType": "segment",
        "length_m": 3314,
        "duration_s": 213,
        "instruction": "turn right",
        "roadName": "George Washington Memorial Pkwy",
        "maxHeight": 4.5,
        "speedLimit": 55,
        "speedLimitUnit": "mph"
      }
    },
    ...,
    {
      "type": "Feature",
      "id": 17,
      "geometry": {
        "type": "Point",
        "coordinates": [
          -77.012520,
          38.889780
        ]
      },
      "properties": {
        "featureType": "segment",
        "length_m": 517,
        "duration_s": 73,
        "roadName": "First Street",
        "speedLimit": 35,
        "speedLimitUnit": "mph"
      }
    },
    {
      "type": "Feature",
      "id": 18,
      "geometry": {
        "type": "Point",
        "coordinates": [
          -77.012520,
          38.889780
        ]
      },
      "properties": {
        "featureType": "end"
      }
    }
  ]
}

7.3. Requirements Class "Manage routes"

Requirements Class

http://www.opengis.net/spec/ogcapi-routes-1/1.0.0-draft.1/req/manage-routes

Target type

Web API

Dependency

Requirements Class "Core"

7.3.1. Routes

Requirement 6

/req/manage-routes/routes-success

The response to a successful execution of the operation to compute a route SHALL include a header Location with the URI of the new route that is a direct sub-resource of /routes.

Example 5. New route request

In the response to a synchronous request to compute a route, the server returns the route in the payload, but also the URI of the new route such as: (https://example.org/api/routing/v1/routes/hdg6g). The following illustrates the HTTP request sent to the API and the HTTP response returned by the API:

POST /api/routing/v1/routes HTTP/1.1
Host: example.org
Content-Type: application/json

{ ... the route definition ... }

HTTP/1.1 200 OK
Date: Tue, 22 Dec 2021 16:42:23 GMT
Location: https://example.org/api/routing/v1/routes/hdg6g
Content-Type: application/geo+json

{ ... the route ... }

Permission 1

/per/manage-routes/purge-routes

Routing APIs may automatically purge routes stored on the server.

Typically, routes will be removed after a reasonable time, for example, a few hours after the route was last accessed.

Fetch routes

This operation returns a list of routes that are currently available.

Requirement 7

/req/manage-routes/get-routes-op

The server SHALL support the HTTP GET operation at the path /routes.

Requirement 8

/req/manage-routes/get-routes-success

A successful execution of the operation SHALL be reported as a response with a HTTP status code 200.

The content of that response SHALL be based upon the following OpenAPI 3.0 schema:

type: object
properties:
  links:
    type: array
    items:
      type: object
      required:
        - rel
        - href
      properties:
        href:
          type: string
        rel:
          type: string
        type:
          type: string
        hreflang:
          type: string
        title:
          type: string

The links SHALL include a link (link relation item) to a route currently on the server.

If a route has a name, the name SHALL be used in the link title.

Access to this resource will typically require authentication. The server will only include links to routes that the client is authorized to access.

Example 6. The Routes resource: The Server Response with available routes

{
  "links": [
    {
      "href": "https://example.org/api/routing/v1/routes",
      "rel": "self",
      "type": "application/json",
      "title": "This document"
    },
    {
      "href": "https://example.org/api/routing/v1/routes/5hsb32",
      "rel": "item",
      "type": "application/geo+json",
      "title": "Lincoln Memorial to hotel"
    },
    {
      "href": "https://example.org/api/routing/v1/routes/9fg3dh",
      "rel": "item",
      "type": "application/geo+json",
      "title": "Lafayette Square to Zoo"
    },
    {
      "href": "https://example.org/api/routing/v1/routes/j6gdg3",
      "rel": "item",
      "type": "application/geo+json",
      "title": "DCA to hotel"
    }
  ]
}

7.3.2. Route

Fetch a route

This operation returns the route with id routeId. The route content is described by the "Route Exchange Model".

Requirement 9

/req/manage-routes/get-route-op

The server SHALL support the HTTP GET operation at the path /routes/{routeId} for each route referenced from the Routes resource at /routes.

Requirement 10

/req/manage-routes/get-route-success

The response to the request SHALL conform to the requirement /req/core/compute-route-success.

See The route response: for an example of a route.

Delete a route

This operation deletes a route with identifier routeId. If the route is still in processing, the routing process is canceled.

Requirement 11

/req/manage-routes/delete-route-op

The server SHALL support the HTTP DELETE operation at the path /routes/{routeId} for each route referenced from the Routes resource at /routes.

Requirement 12

/req/manage-routes/delete-route-success

A successful execution of the operation SHALL be reported as a response with a HTTP status code 200 or 204.

If the operation is not executed immediately, but is added to a processing queue, the response SHALL have a HTTP status code 202.

After the execution of the request, the route will no longer be included in the Routes resource (path /routes) and a GET request to /routes/{routeId} will return a response with a HTTP status code 404.

7.3.3. Route definition

Fetch the definition of a route

This operation returns the input parameters used to create the route with id routeId.

Requirement 13

/req/manage-routes/route-definition-op

The server SHALL support the HTTP GET operation at the path /routes/{routeId}/definition for each route referenced from the Routes resource at /routes.

Requirement 14

/req/manage-routes/route-definition-success

A successful execution of the operation SHALL be reported as a response with a HTTP status code 200.

The content of that response SHALL be identical to the content of the POST request to /routes when the route was created.

7.4. Requirements Class "Intermediate waypoints"

The client can specify additional waypoints along the route between the start location and the end location to consider when computing the route.

Requirements Class

http://www.opengis.net/spec/ogcapi-routes-1/1.0.0-draft.1/req/intermediate-waypoints

Target type

Web API

Dependency

Requirements Class "Core"

Requirement 15

/req/intermediate-waypoints/input

The server SHALL support at least five points in the member with the name "waypoints" in the route definition in a HTTP POST request to the path /routes (i.e. maxItems may be removed from the schema definition or increased to a value larger than '4').

Requirement 16

/req/intermediate-waypoints/success

The computed route SHALL pass through all waypoints in the order in which they have been provided. "Pass through" means that the route overview line string geometry passes through the position or a position on the route network that is close to the waypoint.

7.5. Requirements Class "Modes"

Mode is a restriction based on the type of transport desired when computing the route. For instance, "On Road", "Off Road". The API declares the modes that it supports.

Requirements Class

http://www.opengis.net/spec/ogcapi-routes-1/1.0.0-draft.1/req/mode

Target type

Web API

Dependency

Requirements Class "Core"

Requirement 17

/req/mode/input

The server SHALL support a member at the JSON Pointer /inputs/mode in the route definition in a HTTP POST request to the path /routes based on the following schema:

type: string

Example 7. Route definition with a mode

The following is an example request for the fastest bicycle route from Reagan National Airport to the U.S. Capitol building in Washington, D.C.

{
  "inputs": {
    "name": "Reagan Airport to Capitol",
    "waypoints": {
      "value": {
        "type": "MultiPoint",
        "coordinates": [
          [
            -77.037722,
            38.851444
          ],
          [
            -77.009003,
            38.889931
          ]
        ]
      }
    },
    "preference": "fastest",
    "mode": "cycling"
  }
}

Requirement 18

/req/mode/conformance-values

The content of the conformance declaration response at path /conformance SHALL list all values that the mode parameter supports, based upon the following OpenAPI 3.0 schema:

type: object
required:
  - properties
properties:
  properties:
    type: object
    required:
      - http://www.opengis.net/spec/ogcapi-routes-1/1.0.0-draft.1/conf/mode
    properties:
      http://www.opengis.net/spec/ogcapi-routes-1/1.0.0-draft.1/conf/mode:
        type: object
        required:
          - modes
        properties:
          modes:
            type: array
            items:
              minItems: 1
              type: string

See Conformance declaration for an example.

Note	The plan is to register well-known modes with the OGC Naming Authority that are recommended for use, where applicable.

The mode is a client hint and it is the decision of the server how to consider the selected mode in the computation of the route. If no mode is specified in the route definition then the first value listed in the array is considered to be the default mode.

7.6. Requirements Class "Height restrictions"

This requirement enables the API request to consider a specified vehicle height, in meters, against known height restrictions when computing the route.

Requirements Class

http://www.opengis.net/spec/ogcapi-routes-1/1.0.0-draft.1/req/height

Target type

Web API

Dependency

Requirements Class "Core"

Requirement 19

/req/height/input

The server SHALL support a member at the JSON Pointer /inputs/height in the route definition in a HTTP POST request to the path /routes based on the following schema:

type: number
minimum: 0

Example 8. Route definition with a height restriction

The following is an example request for the fastest route with a vehicle with a height of four meters from Reagan National Airport to the U.S. Capitol building in Washington, D.C.

{
  "inputs": {
    "name": "Reagan Airport to Capitol",
    "waypoints": {
      "value": {
        "type": "MultiPoint",
        "coordinates": [
          [
            -77.037722,
            38.851444
          ],
          [
            -77.009003,
            38.889931
          ]
        ]
      }
    },
    "preference": "fastest",
    "height": 4.0
  }
}

Requirement 20

/req/height/success

The computed route SHALL be passable by vehicles with a height up to the value of "height" in meters.

7.7. Requirements Class "Weight restrictions"

This requirement enables the API request to specify a vehicle weight in metric tons (tonnes) against known weight restrictions when computing the route.

Requirements Class

http://www.opengis.net/spec/ogcapi-routes-1/1.0.0-draft.1/req/weight

Target type

Web API

Dependency

Requirements Class "Core"

Requirement 21

/req/weight/input

The server SHALL support a member at the JSON Pointer /inputs/weight in the route definition in a HTTP POST request to the path /routes based on the following schema:

type: number
minimum: 0

Example 9. Route definition with a weight restriction

The following is an example request for the fastest route with a vehicle with a weight of 8.5 metric tons from Reagan National Airport to the U.S. Capitol building in Washington, D.C.

{
  "inputs": {
    "name": "Reagan Airport to Capitol",
    "waypoints": {
      "value": {
        "type": "MultiPoint",
        "coordinates": [
          [
            -77.037722,
            38.851444
          ],
          [
            -77.009003,
            38.889931
          ]
        ]
      }
    },
    "preference": "fastest",
    "weight": 8.5
  }
}

Requirement 22

/req/weight/success

The computed route SHALL be passable by vehicles with a weight up to the value of "weight" in metric tons (tonnes).

7.8. Requirements Class "Obstacles"

This requirement enables the API request to specify one or more polygons describing areas the route should avoid.

Requirements Class

http://www.opengis.net/spec/ogcapi-routes-1/1.0.0-draft.1/req/obstacles

Target type

Web API

Dependency

Requirements Class "Core"

Requirement 23

/req/obstacles/input

The server SHALL support a member at the JSON Pointer /inputs/obstacles in the route definition in a HTTP POST request to the path /routes based on the following schema (a GeoJSON MultiPolygon, wrapped into a "value" member):

type: object
required:
  - value
properties:
  value:
    type: object
    required:
      - type
      - coordinates
    properties:
      type:
        type: string
        enum:
          - MultiPolygon
      coordinates:
        type: array
        items:
          type: array
          items:
            type: array
            minItems: 4
            items:
              type: array
              minItems: 2
              items:
                type: number

Example 10. Route definition with an obstacle that should be avoided

The following is an example request for the fastest route from Reagan National Airport to the U.S. Capitol building in Washington, D.C, that avoids an rectangular area that includes parts of Georgetown

{
  "inputs": {
    "name": "Reagan Airport to Capitol",
    "waypoints": {
      "value": {
        "type": "MultiPoint",
        "coordinates": [
          [
            -77.037722,
            38.851444
          ],
          [
            -77.009003,
            38.889931
          ]
        ]
      }
    },
    "preference": "fastest",
    "obstacles": {
      "value": {
        "type": "MultiPolygon",
        "coordinates": [
          [
            [
              [
                -77.073211,
                38.9023888
              ],
              [
                -77.049522,
                38.9023888
              ],
              [
                -77.049522,
                38.9104038
              ],
              [
                -77.073211,
                38.9104038
              ],
              [
                -77.073211,
                38.9023888
              ]
            ]
          ]
        ]
      }
    }
  }
}

Requirement 24

/req/obstacles/success

The computed route SHALL not pass through the polygons identified as obstacles.

7.9. Requirements Class "Temporal constraints"

This requirement enable the API request to specify the time of departure or arrival. The default value is an immediate departure.

Requirements Class

http://www.opengis.net/spec/ogcapi-routes-1/1.0.0-draft.1/req/time

Target type

Web API

Dependency

Requirements Class "Core"

Requirement 25

/req/time/input

The server SHALL support a member at the JSON Pointer /inputs/when in the route definition in a HTTP POST request to the path /routes based on the following schema (an time constraint object, wrapped into a "value" member):

type: object
required:
  - value
properties:
  value:
    type: object
    required:
      - timestamp
    properties:
      timestamp:
        type: string
        format: date-time
      type:
        type: string
        default: departure
        enum:
          - departure
          - arrival

The timestamp value SHALL be a date-time string value according to RFC 3339, 5.6 in UTC (time zone "Z").

Example 11. Route definition with a desired arrival time

The following is an example request for the fastest route from Reagan National Airport to the U.S. Capitol building in Washington, D.C, that arrives at 6pm local time on February 24th, 2022.

{
  "inputs": {
    "name": "Reagan Airport to Capitol",
    "waypoints": {
      "value": {
        "type": "MultiPoint",
        "coordinates": [
          [
            -77.037722,
            38.851444
          ],
          [
            -77.009003,
            38.889931
          ]
        ]
      }
    },
    "preference": "fastest",
    "when": {
      "value": {
        "timestamp": "2022-02-24T13:00:00Z",
        "type": "arrival"
      }
    }
  }
}

Requirement 26

/req/time/success

All temporal information in the route SHALL be based on the values in the "when" member (the time of departure or arrival, the default value is an immediate departure).

The start and end of the route SHALL include the timestamp property.

The route overview and the segments SHALL include the duration_s properties.

Recommendation 2

/rec/time/success

The route SHOULD consider the expected traffic situation at the time specified in the "when" member.

8. Media Types

For the media types of routes according to the Route Exchange Model, see [REM].

For all other resources, application/json applies for JSON documents and text/html for HTML documents.

9. Security considerations

The general Security Considerations for Web APIs are also applicable to the Routing API. For example, see the Security Considerations section in OGC API - Features - Part 1: Core.

The following is a list of topics to be considered by implementers of the OGC Routing API:

Fetching the list of routes (GET /routes) returns information about all routes on the server. In any operational, public deployment every user should probably only see their routes plus routes that others have shared with the user.
The same applies to access to each route (GET /route/{routeId}) and their definition (GET /route/{routeId}/definition) as well as to the capability to cancel or delete a route (DELETE /route/{routeId}).

That is, any deployment that is not restricted to a closed group of users will typically require user accounts, access control to the API operations and a capability for sharing routes with the public or other users.

Annex A: Abstract Test Suite (Normative)

This test suite uses the Given-When-Then notation to specify the tests.

Given input to all tests is a Routing API with its landing page at {apiURI} and optional authentication credentials.

A.1. Conformance Class "Core"

Conformance Class

http://www.opengis.net/spec/ogcapi-routes-1/1.0.0-draft.1/conf/core

Target type

Web API

Requirements class

Requirements Class "Core"

Dependency

OGC API - Common - Part 1: Core, Conformance Class "JSON"

Indirect dependency

OGC Route Exchange Model, Conformance Class "Route Exchange Model"

Note	The Conformance Class "JSON" in Common Core has a dependency to the Conformance Classes "Core" and "Landing Page"; that is, testing against "JSON" will automatically test against the dependencies.

A.1.1. Conformance Test 1

Test id:

/conf/core/landing-page-link

Requirements:

/req/core/landing-page-link A

Test purpose:

Check that the link to the Routes resource exists

Test method:

Given:

When:

the request for the API landing page is executed
- method: GET
- path: {apiURI}
- header: Accept: application/json
- authentication, if authentication credentials are provided

Then:

assert successful execution (status code is "200", Content-Type header is "application/json");
assert that a non-negative integer n exists where /links/n/rel is "http://www.opengis.net/def/rel/ogc/1.0/routes" and where /links/n/href is (after normalization) the URI {apiURI}/routes.

A.1.2. Conformance Test 2

Test id:

/conf/core/preferences

Requirements:

/req/core/conformance-values A

Test purpose:

Check that the preference values are stated in the conformance declaration

Test method:

Given:

When:

the request for the API conformance declaration is executed
- method: GET
- path: {apiURI}/conformance
- header: Accept: application/json
- authentication, if authentication credentials are provided

Then:

assert successful execution (status code is "200", Content-Type header is "application/json");
assert that /properties/http:~1~1www.opengis.net~1spec~1ogcapi-routes-1~11.0.0-draft.1~1conf~1core/preferences is a string array with at least one element.

A.1.3. Conformance Test 3

Test id:

/conf/core/compute-route-success

Requirements:

/req/core/compute-route-op A/B, /req/core/compute-route-success A/B

Test purpose:

Check that routes can be computed

Test method:

Given:

a list of five positions (each a JSON array with longitude/latitude) that can be used as waypoints ({pos1} to {pos5})
a tolerance value

When:

a request for a route computation is executed for each ordered pair {posi}/{posj} from { {pos1}, {pos2}, {pos3}, {pos4}, {pos5} }
- method: POST
- path: {apiURI}/routes
- header: Content-Type: application/json, Accept: application/geo+json
- authentication, if authentication credentials are provided
- content: { "inputs": { "waypoints": { "value": { "type": "MultiPoint", "coordinates": [ {posi}, {posj} ] } } } }

Then:

assert successful execution (status code is "200", Content-Type header is "application/geo+json");
assert that the response content conforms to conformance class "Route Exchange Model";
assert that the distance between the start of the route and {posi} is less than the tolerance value;
assert that the distance between the end of the route and {posj} is less than the tolerance value.

A.1.4. Conformance Test 4

Test id:

/conf/core/compute-route-error-400

Requirements:

/req/core/compute-route-op A/B, /req/core/compute-route-error A

Test purpose:

Check that invalid requests return a 400

Test method:

Given:

When:

a request for a route computation is executed
- method: POST
- path: {apiURI}/routes
- header: Content-Type: application/json, Accept: application/geo+json
- authentication, if authentication credentials are provided
- content: { "foo": "bar" }

Then:

assert a bad request response (status code is "400").

A.1.5. Conformance Test 5

Test id:

/conf/core/compute-route-error-422

Requirements:

/req/core/compute-route-op A/B, /req/core/compute-route-error B

Test purpose:

Check that invalid requests return a 422

Test method:

Given:

a list of two positions (each a JSON array with longitude/latitude) that can be used as waypoints ({pos1} and {pos2})
a list of two positions (each a JSON array with longitude/latitude) that cannot be used as waypoints ({posA} and {posB})

When:

a request for a route computation is executed for each ordered pair {posi}/{posj} where one position is from { {pos1}, {pos2} } and the other position is from { {posA}, {posB} }
- method: POST
- path: {apiURI}/routes
- header: Content-Type: application/json, Accept: application/geo+json
- authentication, if authentication credentials are provided
- content: { "inputs": { "waypoints": { "value": { "type": "MultiPoint", "coordinates": [ {posi}, {posj} ] } } } }

Then:

assert an unprocessable entity response (status code is "422").

A.1.6. Conformance Test 6

Test id:

/conf/core/compute-route-preference-success

Requirements:

/req/core/compute-route-op A/B, /req/core/compute-route-success A/B, /req/core/conformance-values A

Test purpose:

Check that routes can be computed for all preference values

Test method:

Given:

test /conf/core/preferences has been passed
a list of five positions (each a JSON array with longitude/latitude) that can be used as waypoints ({pos1} to {pos5})
a tolerance value

When:

a request for a route computation is executed for each ordered pair {posi}/{posj} from { {pos1}, {pos2}, {pos3}, {pos4}, {pos5} } and for each value {pref} from the string array /properties/http:~1~1www.opengis.net~1spec~1ogcapi-routes-1~11.0.0-draft.1~1conf~1core/preferences in the Conformance Declaration
- method: POST
- path: {apiURI}/routes
- header: Content-Type: application/json, Accept: application/geo+json
- authentication, if authentication credentials are provided
- content: { "name": "foo bar", "inputs": { "waypoints": { "value": { "type": "MultiPoint", "coordinates": [ {posi}, {posj} ] } }, "preference": {pref} } }

Then:

assert successful execution (status code is "200", Content-Type header is "application/geo+json");
assert that the response content conforms to conformance class "Route Exchange Model";
assert that the value of /name in the response content is "foo bar";
assert that the distance between the start of the route and {posi} is less than the tolerance value;
assert that the distance between the end of the route and {posj} is less than the tolerance value.

A.1.7. Conformance Test 7

Test id:

/conf/core/compute-route-preference-error-400

Requirements:

/req/core/compute-route-op A/B, /req/core/compute-route-error A

Test purpose:

Check that invalid preference values return a 400

Test method:

Given:

a list of two positions (each a JSON array with longitude/latitude) that can be used as waypoints ({pos1} and {pos2})

When:

a request for a route computation is executed
- method: POST
- path: {apiURI}/routes
- header: Content-Type: application/json, Accept: application/geo+json
- authentication, if authentication credentials are provided
- content: { "inputs": { "waypoints": { "value": { "type": "MultiPoint", "coordinates": [ {pos1}, {pos2} ] } }, "preference": "foo___bar" } }

Then:

assert a bad request response (status code is "400").

A.2. Conformance Class "Intermediate waypoints"

Conformance Class

http://www.opengis.net/spec/ogcapi-routes-1/1.0.0-draft.1/conf/intermediate-waypoints

Target type

Web API

Requirements class

Requirements Class "Intermediate waypoints"

Dependency

Conformance Class "Core"

A.2.1. Conformance Test 8

Test id:

/conf/intermediate-waypoints/compute-route-success

Requirements:

/req/intermediate-waypoints/input A, /req/intermediate-waypoints/success A

Test purpose:

Check that routes with intermediate waypoints can be computed

Test method:

Given:

a list of five positions (each a JSON array with longitude/latitude) that can be used as waypoints ({pos1} to {pos5})
a tolerance value

When:

a request for a route computation is executed for each ordered tuple {posi}/{posj}/{posk}/{posl}/{posm} from { {pos1}, {pos2}, {pos3}, {pos4}, {pos5} }
- method: POST
- path: {apiURI}/routes
- header: Content-Type: application/json, Accept: application/geo+json
- authentication, if authentication credentials are provided
- content: { "inputs": { "waypoints": { "value": { "type": "MultiPoint", "coordinates": [ {posi}, {posj}, {posk}, {posl}, {posm} ] } } } }

Then:

assert successful execution (status code is "200", Content-Type header is "application/geo+json");
assert that the response content conforms to conformance class "Route Exchange Model";
assert that the distance between the start of the route and {posi} is less than the tolerance value;
assert that the distance between the route path and {posj} is less than the tolerance value,
assert that the distance between the route path and {posk} is less than the tolerance value,
assert that the distance between the route path and {posl} is less than the tolerance value,
assert that the distance between the end of the route and {posm} is less than the tolerance value.

A.3. Conformance Class "Modes"

Conformance Class

http://www.opengis.net/spec/ogcapi-routes-1/1.0.0-draft.1/conf/mode

Target type

Web API

Requirements class

Requirements Class "Modes"

Dependency

Conformance Class "Core"

A.3.1. Conformance Test 9

Test id:

/conf/mode/modes

Requirements:

/req/mode/conformance-values A

Test purpose:

Check that the mode values are stated in the conformance declaration

Test method:

Given:

When:

the request for the API conformance declaration is executed
- method: GET
- path: {apiURI}/conformance
- header: Accept: application/json
- authentication, if authentication credentials are provided

Then:

assert successful execution (status code is "200", Content-Type header is "application/json");
assert that /properties/http:~1~1www.opengis.net~1spec~1ogcapi-routes-1~11.0.0-draft.1~1conf~1mode/modes is a string array with at least one element.

A.3.2. Conformance Test 10

Test id:

/conf/core/compute-route-mode

Requirements:

/req/mode/input A, /req/mode/conformance-values A

Test purpose:

Check that routes can be computed for all modes

Test method:

Given:

test /conf/mode/modes has been passed
a list of five positions (each a JSON array with longitude/latitude) that can be used as waypoints ({pos1} to {pos5})
a tolerance value

When:

a request for a route computation is executed for each ordered pair {posi}/{posj} from { {pos1}, {pos2}, {pos3}, {pos4}, {pos5} } and for each value {mode} from the string array /properties/http:~1~1www.opengis.net~1spec~1ogcapi-routes-1~11.0.0-draft.1~1conf~1mode/modes in the Conformance Declaration
- method: POST
- path: {apiURI}/routes
- header: Content-Type: application/json, Accept: application/geo+json
- authentication, if authentication credentials are provided
- content: { "inputs": { "waypoints": { "value": { "type": "MultiPoint", "coordinates": [ {posi}, {posj} ] } }, "mode": {mode} } }

Then:

assert successful execution (status code is "200", Content-Type header is "application/geo+json");
assert that the response content conforms to conformance class "Route Exchange Model";
assert that the distance between the start of the route and {posi} is less than the tolerance value;
assert that the distance between the end of the route and {posj} is less than the tolerance value.

A.4. Conformance Class "Height restrictions"

Conformance Class

http://www.opengis.net/spec/ogcapi-routes-1/1.0.0-draft.1/conf/height

Target type

Web API

Requirements class

Requirements Class "Height restrictions"

Dependency

Conformance Class "Core"

A.4.1. Conformance Test 11

Test id:

/conf/height/compute-route-success

Requirements:

/req/height/input A, /req/height/success A

Test purpose:

Check that routes with height restrictions can be computed

Test method:

Given:

a list of three positions (each a JSON array with longitude/latitude) that can be used as waypoints ({pos1} to {pos3})
an optional list of vehicle heights, default is: 2, 3, 5
a tolerance value

When:

a request for a route computation is executed for each ordered pair {posi}/{posj} from { {pos1}, {pos2}, {pos3} } and for each {height} from the list of vehicle heights
- method: POST
- path: {apiURI}/routes
- header: Content-Type: application/json, Accept: application/geo+json
- authentication, if authentication credentials are provided
- content: { "inputs": { "waypoints": { "value": { "type": "MultiPoint", "coordinates": [ {posi}, {posj} ] } } }, "height": {height} }

Then:

assert successful execution (status code is "200", Content-Type header is "application/geo+json");
assert that the response content conforms to conformance class "Route Exchange Model";
assert that the distance between the start of the route and {posi} is less than the tolerance value;
assert that the distance between the end of the route and {posj} is less than the tolerance value;
assert that the route overview has no property maxHeight_m or a value that is greater than or equal to {height}.

A.5. Conformance Class "Weight restrictions"

Conformance Class

http://www.opengis.net/spec/ogcapi-routes-1/1.0.0-draft.1/conf/weight

Target type

Web API

Requirements class

Requirements Class "Weight restrictions"

Dependency

Conformance Class "Core"

A.5.1. Conformance Test 12

Test id:

/conf/weight/compute-route-success

Requirements:

/req/weight/input A, /req/weight/success A

Test purpose:

Check that routes with weight restrictions can be computed

Test method:

Given:

a list of three positions (each a JSON array with longitude/latitude) that can be used as waypoints ({pos1} to {pos3})
an optional list of vehicle weights in metric tons, default is: 3, 5, 10
a tolerance value

When:

a request for a route computation is executed for each ordered pair {posi}/{posj} from { {pos1}, {pos2}, {pos3} } and for each {weight} from the list of vehicle weights
- method: POST
- path: {apiURI}/routes
- header: Content-Type: application/json, Accept: application/geo+json
- authentication, if authentication credentials are provided
- content: { "inputs": { "waypoints": { "value": { "type": "MultiPoint", "coordinates": [ {posi}, {posj} ] } } }, "weight": {weight} }

Then:

assert successful execution (status code is "200", Content-Type header is "application/geo+json");
assert that the response content conforms to conformance class "Route Exchange Model";
assert that the distance between the start of the route and {posi} is less than the tolerance value;
assert that the distance between the end of the route and {posj} is less than the tolerance value;
assert that the route overview has no property maxWeight_t or a value that is greater than or equal to {weight}.

A.6. Conformance Class "Obstacles"

Conformance Class

http://www.opengis.net/spec/ogcapi-routes-1/1.0.0-draft.1/conf/obstacles

Target type

Web API

Requirements class

Requirements Class "Obstacles"

Dependency

Conformance Class "Core"

A.6.1. Conformance Test 13

Test id:

/conf/obstacles/compute-route-success

Requirements:

/req/obstacles/input A, /req/obstacles/success A

Test purpose:

Check that routes can be computed avoiding obstacles

Test method:

Given:

a list of five positions (each a JSON array with longitude/latitude) that can be used as waypoints ({pos1} to {pos5})
a tolerance value

When:

a request for a route computation is executed for each ordered pair {posi}/{posj} from { {pos1}, {pos2}, {pos3} }
- method: POST
- path: {apiURI}/routes
- header: Content-Type: application/json, Accept: application/geo+json
- authentication, if authentication credentials are provided
- content: { "inputs": { "waypoints": { "value": { "type": "MultiPoint", "coordinates": [ {posi}, {posj} ] } } }, "obstacles": { "type": "MultiPolygon", "coordinates": [[[ [{lonm},{latm}], [{lonn},{latm}], [{lonn},{latn}], {[{lonm},{latn}], [{lonm},{latm}] ]]] } } with
  - {lonm} and {lonn} as longitudes somewhere between the longitudes of {posi} and {posj}; {lonm} < {lonn}
  - {latm} and {latn} as latitudes somewhere between the latitudes of {posi} and {posj}; {latm} < {latn}

Then:

assert successful execution (status code is "200", Content-Type header is "application/geo+json");
assert that the response content conforms to conformance class "Route Exchange Model";
assert that the distance between the start of the route and {posi} is less than the tolerance value;
assert that the distance between the end of the route and {posj} is less than the tolerance value;
assert that the route path does not intersect the obstacle geometry.

A.7. Conformance Class "Temporal constraints"

Conformance Class

http://www.opengis.net/spec/ogcapi-routes-1/1.0.0-draft.1/conf/time

Target type

Web API

Requirements class

Requirements Class "Temporal constraints"

Dependency

Conformance Class "Core"

A.7.1. Conformance Test 14

Test id:

/conf/time/compute-route-success-default

Requirements:

/req/time/input A/B, /req/time/success A/B/C

Test purpose:

Check that routes with the default time constraints can be computed

Test method:

Given:

a list of three positions (each a JSON array with longitude/latitude) that can be used as waypoints ({pos1} to {pos3})
a tolerance value

When:

a request for a route computation is executed for each ordered pair {posi}/{posj} from { {pos1}, {pos2}, {pos3} }
- method: POST
- path: {apiURI}/routes
- header: Content-Type: application/json, Accept: application/geo+json
- authentication, if authentication credentials are provided
- content: { "inputs": { "waypoints": { "value": { "type": "MultiPoint", "coordinates": [ {posi}, {posj} ] } } } }

Then:

assert successful execution (status code is "200", Content-Type header is "application/geo+json");
assert that the response content conforms to conformance class "Route Exchange Model";
assert that the distance between the start of the route and {posi} is less than the tolerance value;
assert that the distance between the end of the route and {posj} is less than the tolerance value;
assert that the start feature has a timestamp property that is the same as the time when the request was submitted - within the specified tolerance;
assert that the difference between the end and start feature timestamp properties is the same as the duration_s property of the route overview - within the specified tolerance;

A.7.2. Conformance Test 15

Test id:

/conf/time/compute-route-success

Requirements:

/req/time/input A/B, /req/time/success A/B/C

Test purpose:

Check that routes with time constraints can be computed

Test method:

Given:

a list of three positions (each a JSON array with longitude/latitude) that can be used as waypoints ({pos1} to {pos3})
a tolerance value

When:

a request for a route computation is executed for each ordered pair {posi}/{posj} from { {pos1}, {pos2}, {pos3} } and for {type} from the list: "departure", "arrival".
- method: POST
- path: {apiURI}/routes
- header: Content-Type: application/json, Accept: application/geo+json
- authentication, if authentication credentials are provided
- content: { "inputs": { "waypoints": { "value": { "type": "MultiPoint", "coordinates": [ {posi}, {posj} ] } } }, "when": { "value": { "timestamp": {timestamp}, "type": {type} } } } with
  - {timestamp} as a RFC 3339 date-time value in UTC ("Z") in 24 hours

Then:

assert successful execution (status code is "200", Content-Type header is "application/geo+json");
assert that the response content conforms to conformance class "Route Exchange Model";
assert that the distance between the start of the route and {posi} is less than the tolerance value;
assert that the distance between the end of the route and {posj} is less than the tolerance value;
assert that, if {type} is "departure", the start feature has a timestamp property that is the same as {timestamp} - within the specified tolerance;
assert that, if {type} is "arrival", the end feature has a timestamp property that is the same as {timestamp} - within the specified tolerance;
assert that the difference between the end and start feature timestamp properties that is the same as the duration_s property of the route overview - within the specified tolerance;

A.7.3. Conformance Test 16

Test id:

/conf/time/compute-route-success-400-error

Requirements:

/req/time/input A/B

Test purpose:

Check that routes with invalid time constraints are rejected

Test method:

Given:

a list of two positions (each a JSON array with longitude/latitude) that can be used as waypoints ({pos1} and {pos2})
a tolerance value

When:

requests for a route computation are executed with {timestamp} as an invalid value: without time zone, with a timezone that is not "Z", and a date.
- method: POST
- path: {apiURI}/routes
- header: Content-Type: application/json, Accept: application/geo+json
- authentication, if authentication credentials are provided
- content: { "inputs": { "waypoints": { "value": { "type": "MultiPoint", "coordinates": [ {pos1}, {pos2} ] } } }, "when": { "value": { "timestamp": {timestamp} } } }

Then:

assert a bad request response (status code is "400").

A.8. Conformance Class "Manage routes"

Conformance Class

http://www.opengis.net/spec/ogcapi-routes-1/1.0.0-draft.1/conf/manage-routes

Target type

Web API

Requirements class

Requirements Class "Manage routes"

Dependency

Conformance Class "Core"

A.8.1. Conformance Test 17

Test id:

/conf/manage-routes/routes-success-1

Requirements:

/req/manage-routes/routes-success A

Test purpose:

Check that a link to the stored route is returned (part 1)

Test method:

Given:

a list of two positions (each a JSON array with longitude/latitude) that can be used as waypoints ({pos1} and {pos2})

When:

a request for a route computation is executed
- method: POST
- path: {apiURI}/routes
- header: Content-Type: application/json, Accept: application/geo+json
- authentication, if authentication credentials are provided
- content: { "name": "foo bar", "inputs": { "waypoints": { "value": { "type": "MultiPoint", "coordinates": [ {pos1}, {pos2} ] } } } }

Then:

assert successful execution (status code is "200", Content-Type header is "application/geo+json");
assert that response includes a header Location;
assert the the Location header refers to URI that matches the template {apiURI}/routes/{routeId}.

A.8.2. Conformance Test 18

Test id:

/conf/manage-routes/routes-success-2

Requirements:

/req/manage-routes/routes-success A

Test purpose:

Check that a link to the stored route is returned (part 2)

Test method:

Given:

test /conf/manage-routes/routes-success-1 has just been passed
{routeId} is the route identifier of a stored route based on the Location header value from the test /conf/manage-routes/routes-success-1
{routeContent} is the content of the response from the test /conf/manage-routes/routes-success-1

When:

a request to fetch the stored route is executed
- method: GET
- path: {apiURI}/routes/{routeId}
- header: Accept: application/geo+json
- authentication, if authentication credentials are provided

Then:

assert successful execution (status code is "200", Content-Type header is "application/geo+json");
assert that the response content conforms to conformance class "Route Exchange Model";
assert that response content is identical to {routeContent}.

A.8.3. Conformance Test 19

Test id:

/conf/manage-routes/get-routes-success

Requirements:

/req/manage-routes/get-routes-op A, /req/manage-routes/get-routes-success A/B/C/D

Test purpose:

Check that routes can be fetched

Test method:

Given:

test /conf/manage-routes/routes-success-1 has just been passed
{routeId} is the route identifier of a stored route based on the Location header value from the test /conf/manage-routes/routes-success-1

When:

a request to fetch the list of routes is executed
- method: GET
- path: {apiURI}/routes
- header: Accept: application/json
- authentication, if authentication credentials are provided

Then:

assert successful execution (status code is "200", Content-Type header is "application/json");
assert that the response content validates against the schema in /req/manage-routes/get-routes-success B;
assert that a non-negative integer n exists where /links/n/rel is "item", where /links/n/href is (after URI normalization) equal to {apiURI}/routes/{routeId} and where links/n/title includes the sub-string "foo bar".

A.8.4. Conformance Test 20

Test id:

/conf/manage-routes/get-route-success

Requirements:

/req/manage-routes/get-route-op A, /req/manage-routes/get-route-success A

Test purpose:

Check that routes can be fetched

Test method:

Given:

test /conf/manage-routes/get-routes-success has just been passed
{routeIds} is an array of route identifiers from the test /conf/manage-routes/get-routes-success (derived from the /links/i/href values for all non-integer i where /links/i/rel is "item")

When:

requests to fetch a route are executed with each {routeId} from {routeIds}
- method: GET
- path: {apiURI}/routes/{routeId}
- header: Accept: application/geo+json
- authentication, if authentication credentials are provided

Then:

assert successful execution (status code is "200", Content-Type header is "application/geo+json");
assert that the response content conforms to conformance class "Route Exchange Model".

A.8.5. Conformance Test 21

Test id:

/conf/manage-routes/get-route-definition-success

Requirements:

/req/manage-routes/get-route-definition-op A, /req/manage-routes/get-route-definition-success A/B

Test purpose:

Check that route definitions can be fetched

Test method:

Given:

tests /conf/manage-routes/routes-success-1 and /conf/manage-routes/get-routes-success have just been passed
{routeIds} is an array of route identifiers from the test /conf/manage-routes/get-routes-success (derived from the /links/i/href values for all non-integer i where /links/i/rel is "item")
{routeIdCreated} is the route identifier of a stored route based on the Location header value from the test /conf/manage-routes/routes-success-1
{routeDefinitionCreated} is the request content of the test /conf/manage-routes/routes-success-1

When:

requests to fetch a route are executed with each {routeId} from {routeIds}
- method: GET
- path: {apiURI}/routes/{routeId}/definition
- header: Accept: application/json
- authentication, if authentication credentials are provided

Then:

assert successful execution (status code is "200", Content-Type header is "application/json");
if {routeId} is equal to {routeIdCreated}, assert that the response content is identical to {routeDefinitionCreated};
assert that the response content validates against the following OpenAPI 3.0 schema:

type: object
required:
  - inputs
properties:
  inputs:
    type: object
    required:
      - waypoints
    properties:
      name:
        type: string
      waypoints:
        type: object
        required:
          - value
        properties:
          value:
            type: object
            required:
              - type
              - coordinates
            properties:
              type:
                type: string
                enum:
                  - MultiPoint
              coordinates:
                type: array
                minItems: 2
                items:
                  title: Points along the route
                  type: array
                  minItems: 2
                  maxItems: 3
                  items:
                    type: number
      preference:
        type: string
      mode:
        type: string
      height:
        type: number
        minimum: 0
      weight:
        type: number
        minimum: 0
      obstacles:
        type: object
        required:
          - value
        properties:
          value:
            type: object
            required:
              - type
              - coordinates
            properties:
              type:
                type: string
                enum:
                  - MultiPolygon
              coordinates:
                type: array
                items:
                  type: array
                  items:
                    type: array
                    minItems: 4
                    items:
                      type: array
                      minItems: 2
                      maxItems: 3
                      items:
                        type: number
      when:
        type: object
        required:
          - value
        properties:
          value:
            type: object
            required:
              - timestamp
            properties:
              timestamp:
                type: string
                format: date-time
              type:
                type: string
                default: departure
                enum:
                  - departure
                  - arrival

A.8.6. Conformance Test 22

Test id:

/conf/manage-routes/delete-route-success-1

Requirements:

/req/manage-routes/delete-route-op A, /req/manage-routes/delete-route-success A/B

Test purpose:

Check that a route can be deleted

Test method:

Given:

test /conf/manage-routes/routes-success-1 has just been passed
{routeId} is the route identifier of a stored route based on the Location header value from the test /conf/manage-routes/routes-success-1

When:

a request to delete a route
- method: DELETE
- path: {apiURI}/routes/{routeId}
- authentication, if authentication credentials are provided

Then:

assert response (status code is "200", "204" or "202").

A.8.7. Conformance Test 23

Test id:

/conf/manage-routes/delete-route-success-2

Requirements:

/req/manage-routes/delete-route-success A

Test purpose:

Check that a route has been deleted

Test method:

Given:

test /conf/manage-routes/delete-route-success-1 has just been passed
{routeId} is the route identifier of the deleted route in test /conf/manage-routes/delete-route-success-1

When:

a request to fetch all routes
- method: GET
- path: {apiURI}/routes
- header: Accept: application/json
- authentication, if authentication credentials are provided

Then:

assert successful execution (status code is "200", Content-Type header is "application/json");
assert that no non-negative integer n exists where /links/n/rel is "item", where /links/n/href is (after URI normalization) equal to {apiURI}/routes/{routeId}.

Annex B: Revision History

Date

Release

Editor

Primary clauses modified

Description

2021-01-12

1.0.0-SNAPSHOT

C. Portele

all

initial version, based on Open Routing Pilot results

2021-04-23

1.0.0-SNAPSHOT

C. Portele

all

Support for RFC 7240 ("Prefer" header), OGC API - Common - Part 1: Core, editorial updates

2021-12-23

1.0.0-SNAPSHOT

C. Portele

all

updates, based on SWG decisions on open issues; test suite added

2022-03-24

1.0.0-draft.1

A. Youmans, C. Portele

all

include edits by Carl Reed and address comments; version for public comments

Annex C: Bibliography

OpenAPI Initiative (OAI). OpenAPI Specification 3.0 [online]. 2020 [viewed 2020-03-16]. The latest patch version at the time of publication of this standard was 3.0.3, available at http://spec.openapis.org/oas/v3.0.3
Open Geospatial Consortium (OGC). OGC APIs - Building Blocks for Location [online, viewed 2021-12-22]. Available at https://ogcapi.ogc.org/
Open Geospatial Consortium (OGC). OGC® Routing Pilot ER [online, viewed 2021-12-22]. Available at https://docs.ogc.org/per/19-041r3.html
Open Geospatial Consortium (OGC). WPS Routing API ER [online, viewed 2021-12-22]. Available at https://docs.ogc.org/per/19-040.html
Open Geospatial Consortium (OGC). OGC Web API Guidelines [online, viewed 2021-12-22]. Available at https://github.com/opengeospatial/OGC-Web-API-Guidelines