Flow Matrix Analysis

Important Note
Explore ready-to-use traffic reports and data visualizations immediately by signing up for a 30-day free trial on the MOVE Portal. Once registered, you’ll receive an API key to start using the Traffic Analytics APIs right away. Alternatively, you may contact our Sales team for a tailored solution.

Introduction

The Flow Matrix API calculates statistics of origin and destination between all defined regions. It provides all via waypoints for all origin and destination pairs. Each region in the input is treated as origin, destination, and a “Via” region at the same time. This is a simplified result you get for 3 defined regions A, B and C.

Analysis version and service version are two different things. The 1 in the request URL is the version of the service and it does not change. The version of the analysis is the analysisVersion field in the body of the creation request. To create a version 2 analysis, send "analysisVersion": 2; if you omit the field, the service creates a version 1 analysis, which is documented at Flow Matrix Analysis (version 1).

Normalized probe counts

A version 2 analysis reports normalized probe counts, the normalization introduced in O/D Analysis V2. The normalization is proportional scaling, so every value is a share of one result rather than a number of trips. Every trips value and every histogram value is the trip count of one cell divided by all trips counted for one result and multiplied by a fixed scale of 100, where one result is a single combination of a date range and a time range. A trip counts once towards that total even when it appears in several rows of the matrix.

Two consequences follow:

The origin-destination view - the one you get when you do not restrict vias - sums to about 100 across all its cells.
A via-restricted view is a drill-down. Its cells are normalized against the same total, so a single via view sums to less than 100, and the sum over all via views exceeds 100, because a trip that passed through three regions is present in three of them.

Normalized values of two different results (a different date range or a different time range) have different denominators and must not be added together.

Migrating a dashboard or a report to version 2 These values are shares of one result, so they are not directly comparable with the trip counts reported by version 1. The denominator is not part of the result, so a normalized value cannot be converted back to an absolute count. A dashboard or a report built on absolute counts needs its calculations changed, not rescaled.

Output example covering no via restrictions

_	A	B	C
A	28.5	3.0	3.0
B	5.5	23.0	3.0
C	3.0	11.0	20.0

All nine cells add up to 100: every counted trip is in exactly one of them.

Output example covering via restrictions

via B	A	B	C
A	2.5	3.0	0.0
B	5.5	23.0	3.0
C	0.0	11.0	5.0

Every trip that starts or ends in B also passes through B, so the middle row and the middle column are the same as in the previous table. The A to A cell dropped from 28.5 to 2.5: only that part of the A to A traffic went through B.

Similarly you get results for via A and via C. This API is asynchronous.

Using this API

There are some important notes about using this API:

The latitude and longitude coordinates are in EPSG4326 / WGS84 format for both input and output. Other coordinate systems are not supported.
The size of an analysis is bounded by the limits granted to your contract. The standard grant is 20000 km^2 of total region area, 600 regions, 4 date ranges and 24 time ranges; your key may have different values.
Regions that declare a narrowed regionRoles set - one or two of ORIGIN, DESTINATION and VIA, see Regions definition format - count towards a higher region ceiling, so an analysis built only from such regions may hold up to three times more of them.
As the service is asynchronous it can take a while before results are available, depending on how busy the service is.
- Do not repost your request multiple times if you do not get feedback within seconds.
- We will ensure that the results are delivered.
Results can be downloaded once the analysis reaches the ACCEPTED status.