Region

Each routing matrix request requires the parameter regionDefinition. This parameter defines the region in which the matrix will be calculated. The region definition can either be specified by the user or automatically derived by the service.

The regionDefinition parameter has the special variant world which is used to enable calculation of matrices with routes of arbitrary length. It can be used in one of these two cases:

• In combination with a specified profile. The routing matrix is then calculated based on predefined options and free-flow speed traffic. For more information, see Profiles.
• Without specifying a profile, for matrices with a maximum size of 15x100 or 100x1. The matrix can be calculated with custom options and dynamic traffic.

From now on in this section, we assume that the variant of the region definition is not world.

Each origin and destination should be inside the region. Only data within the region is used to calculate the result. This has several implications.

First, an origin or destination outside of the specified region will either:

• Be matched to the boundary of the region if it is close enough, or
• Produce an error code in the error matrix indicating that it could not be matched

Therefore, you must make sure that all origins and destinations are inside the region.

Another consideration is that if an origin or destination is inside the region but too close to the boundary, the service may compute a suboptimal route. For example, sometimes it is faster to drive in a different direction from a destination in order to take a faster route using a highway. If the region is too tight around such origins the highway might be cut-off.

To avoid this problem, you should specify a region with a reasonable margin around all coordinates. The size of the margin depends on the characteristics of the road network. In cities, a margin of several kilometers might be enough. However, in rural areas a bigger margin is needed because of long detours.

Supported regions

The Matrix Routing service supports three types of regions, with a maximum diameter of 400 kilometers.

Circle

A circle region is specified by its center and its radius in meters in the following form:

{
    "type": "circle",
    "center": {"lat": 0.0, "lng": 0.0},
    "radius": 10000  // 10 km
}

Bounding box

An axis-aligned bounding is specified by its extent from east to west and from north to south. An inverted extent (north/south or west/east swapped) is invalid. The diameter of a bounding box is computed as the haversine distance of the corners lying on one of the diagonals.

{
    "type": "boundingBox",
    "west": 0,
    "east": 2,
    "north": 10,
    "south": 0,
}

A bounding box spreading over the 0th or 180th meridian is valid.

Polygon

A polygon is specified by a list of its vertices, where two consecutive elements, and the last and the first element of the list, are considered as connected. The service supports a polygon with a maximum of 100 vertices. A polygon does not have to be convex. However, it must not be self-intersecting. The diameter of the polygon is the maximum of the haversine distance between any two vertices. Following this definition, a polygon can be always replaced by a circle with the same radius and a corresponding center.

Specifying a polygon can be useful because:

• Sometimes it is easier to describe a shape as a polygon than computing a circle around points
• A smaller region means less computational time for the service, so a polygon region can be used to speed up the calculation.

{
    "type": "polygon",
    "outer": [
        {"lat": 0.0, "lng": 0.0},
        {"lat": 1.0, "lng": 0.0},
        {"lat": 1.0, "lng": 1.0},
        {"lat": 0.0, "lng": 1.0}
    ]
}

AutoCircle

AutoCircle is a special variant of regionDefinition, which indicates that the service should automatically derive a circle containing the provided origins and destinations with a margin. Requesting an autoCircle does not guarantee that the resulting circle is of valid size, for example if the requested margin is too large. On the other hand, the margin needs to be large enough to allow for a successful matrix calculation, as explained above. You may choose not to specify a margin, so that the service uses a default value (10 km), reasonable for routes inside a city.

{
    "type": "autoCircle",
    "margin": 1000
}

The derived circle appears in the MatrixResponse as a RegionDefinition of type Circle.