Custom Route Extension API Developer's Guide

Upload an Overlay Map

This resource uploads an overlay map that modifies route-related attributes and geometries in the map. Any subsequent routing calls take the overlay change into consideration. It may take multiple seconds until the overlay changes are effective.

Overlay maps are stored in the Custom Location Extension Service and require unique names. If an overlay map with the same name already exists, it is replaced with the one that you provide.

You can use the Custom Location Extension resources like layers/list.json and layers/delete.json to view or delete the overlay maps.

For small examples, overlays can be submitted in a GET request, but bigger overlays should be submitted via POST request, either as application/x-www-form-urlencoded or as multipart with one part named overlay_spec.

Resource URI

The pattern for requests to the resource is
GET /2/overlays/upload.json

For more information, see Constructing a Request.

Resource Parameters

Parameter Description
map_name mandatory


Overlay map name. Case insensitive. Must start with OVERLAY and contain only characters.

overlay_spec mandatory


JSON structure describing the map changes. See Overlay Description Format.

storage mandatory


Currently only readonly is supported.

callback optional


Specifies the name of a user-defined function used to wrap the JSON response.

max_distance_to_connect optional


Specifies how many meters apart the geoetries of a new link and an existing link can be, to establish connection. Should not exceed a few meters.

max_distance_to_match optional


Specifies how many meters apart the geoetries of two new links can be, to establish a connection. Should not exceed a few meters.

min_match_confidence optional, default 0.6

0.0 ... 1.0

Specify the minimum required road match confidence level. If a match is below this level, the service throws an error.

max_match_search_distance optional, default 100 meter


Search only this number of meters to match the lin geometry points onto existing road geometry. Should not exceed a few meter.

matchMode optional, default 0


0 does sophisticated geometry match. 1 does a quicker check which is usually sufficient if the geometries fit exactly to the existing road network.

Response Format

The response currently contains a list of layers the overlay map consists of. When you submit an overlay request, the response includes a list of the overlay layers in the map. However, the current response is subject to change. For information about possible changes, see the Release Notes for the future releases.