TomTom LogoDocs
Products
Resources
Pricing
Sign in
O/D Analysis

Analysis result

Service version: 1Last edit: 2026.08.05Beta
Try 30 Days Free

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.

This page describes an analysis created with "analysisVersion": 2. The 1 in the request URL is the version of the service and it does not change. The version of the analysis is chosen at creation time, see Analysis Creation.

This page describes the result files of a Selected Link analysis, their structure, their formats, and how to filter them by path hash. The request that returns the analysis preview and the response envelope that carries the result URLs are described on Analysis Preview.

Result structure

A result file describes one direction of traffic for one date range and one time range.

Field

Description

nodeFormat
array (of strings)

Self describing list of the values carried by every node, in the order in which they appear. Included in the JSON response only.

nodes
array

An array of nodes connected with the selected link.

metadata
object

Parameters used by the analysis, together with the result direction. Included in the JSON response and as metadata.xml in the shapefile archive.

metadata.resultType
string

Direction of the result. One of INCOMING, OUTGOING or INSIDE.

metadata.enhancedMetrics
array (of strings)

Enhanced metrics the analysis was created with, omitted when the analysis was created without them.

The nodes form a tree. A node whose parentId is null is a root of the tree, the place where the analyzed traffic enters or leaves the link; every other node is a continuation of the path of its parent. The roots together account for the whole traffic of the selected link, so a LineString link, which has a single root, reports close to 100% on it.

Node fields

Field names differ between formats, so each row below lists all of them.

Field

Description

id
integer

Id of the node. CSV column Id, shapefile attribute id, protobuf field id.

parentId
integer

Id of the parent node, null for the selected link of the analysis. CSV column Parent id (empty for the selected link), shapefile attribute parent_id, protobuf field parent_id.

percentage
number

Share of the traffic of the selected link that this node carries, in percent. CSV column Percentage, shapefile attribute percentage, protobuf field percentage.


It is the mean of a Beta distribution fitted to the observed trips, rounded to four decimal places, so a single root node reports slightly below 100. See Confidence Intervals Methodology for how that distribution is derived. The value is null when the interval cannot be computed, which happens when no trips were counted on the selected link.

marginOfError
number

Distance from percentage to the furthest end of its 95% confidence interval, in percentage points, so the plausible range of a node is percentage plus or minus marginOfError. CSV column MarginOfError, shapefile attribute marg_error, protobuf field marginOfError.


The interval is not symmetric around percentage, so that range covers the interval rather than reproducing it, and is wider than it on one side. The confidence level is fixed at 95% and cannot be changed per request.

frc
integer

Functional Road Class. CSV column FRC, shapefile attribute frc, protobuf field frc.

geometry
array

Geometry of the node as an array of [lon, lat] pairs in WGS84. CSV column WKT holds the same geometry as a WKT LineString, the shapefile carries it as the feature geometry, and the protobuf field is geo.

processingFailures
number

Trips dropped by processing on this node, as a percentage of the traffic of the selected link. Despite the name used in nodeFormat, the value is a percentage and not a count. CSV column ProcessingFailuresPercent, shapefile attribute proc_fail, protobuf field processingFailuresPercent.

privacyTrims
number

Trips trimmed for privacy reasons on this node, as a percentage of the traffic of the selected link. Despite the name used in nodeFormat, the value is a percentage and not a count. CSV column PrivacyTrimsPercent, shapefile attribute priv_trims, protobuf field privacyTrimsPercent.

avgTravelTimeInSec
integer

Average travel time from link to selected node, in seconds. Filled in only when the analysis was created with enhancedMetrics: ["TRAVEL_TIME_AND_DISTANCE"], otherwise null. CSV column AvgTravelTimeInSec, shapefile attribute avg_time_s, protobuf field avgTravelTimeInSeconds.

travelDistanceInMeters
integer

Average traveled distance from link to node, in meters. Filled in only when the analysis was created with enhancedMetrics: ["TRAVEL_TIME_AND_DISTANCE"], otherwise null. CSV column TravelDistanceInMeters, shapefile attribute distance_m, protobuf field distanceInMeters.

volume
integer

Estimated absolute traffic volume on the node. The value is not a vehicle count: it is estimated by a model trained on data from road traffic counters, for a period that has already passed. Filled in only when the analysis was created with enhancedMetrics: ["VOLUME"], otherwise null. CSV column Volume, shapefile attribute volume, protobuf field volume.


The traffic volume is estimated for the road segment the selected link is matched to and is then distributed down the tree in proportion to the traffic of each branch, so a node other than the selected link reports a share of that segment estimate rather than a figure derived for the node itself. It is null for every node when the map carries no traffic volume data for that segment.

roadName
string

Name of the last road segment of the node. When the map has no name for it, the value is Segment N. CSV column RoadName, shapefile attribute road_name, protobuf field roadName.

The protobuf result carries two more fields that no other format has:

  • fullPathHash - identifier of the whole path from the selected link to this node. It is the input of Filtering results by path hash.
  • timeRangeIndex - filled in only in the response of that endpoint.

JSON response example

The example was created with both enhanced metrics enabled. Replace {map_version} with the map version of your analysis.

get
Response body - JSON
{
  "metadata": {
    "resultType": "INCOMING",
    "dateRange": { "startDate": "2026-01-01", "endDate": "2026-03-31", "exclusions": [] },
    "timeRange": { "startTime": "07:00", "endTime": "09:00" },
    "timeZone": "Europe/Amsterdam",
    "geometry": "LINESTRING (4.89 52.37, 4.9 52.38)",
    "bufferRadiusInMeters": 10000,
    "mapType": "ORBIS",
    "mapVersion": "{map_version}",
    "dataSources": "ALL",
    "enhancedMetrics": ["VOLUME", "TRAVEL_TIME_AND_DISTANCE"]
  },
  "nodeFormat": ["id", "parentId", "percentage", "marginOfError", "frc", "geometry", "processingFailures", "privacyTrims", "avgTravelTimeInSec", "travelDistanceInMeters", "volume", "roadName"],
  "nodes": [
    [0, null, 99.9847, 0.0512, 3, [[21.00866, 52.23521], [21.00838, 52.23515]], 0.0, 0.0, 41, 620, 2941, "Aleje Jerozolimskie"],
    [1, 0, 1.4832, 0.2913, 5, [[21.00838, 52.23515], [21.00835, 52.23522]], 0.0, 0.34, 12, 180, 44, "Segment 7"],
    [2, 0, 97.8901, 0.3204, 3, [[21.00838, 52.23515], [21.0082, 52.23512]], 0.07, 0.0, 35, 540, 2877, "Aleje Jerozolimskie"]
  ]
}

Without enhancedMetrics the positions of avgTravelTimeInSec, travelDistanceInMeters and volume are null.

CSV response example

get
Response body - CSV
Id;Parent id;Percentage;MarginOfError;FRC;WKT;ProcessingFailuresPercent;PrivacyTrimsPercent;AvgTravelTimeInSec;TravelDistanceInMeters;Volume;RoadName
0;;99.9847;0.0512;3;LINESTRING (21.00866 52.23521, 21.00838 52.23515);0.0;0.0;41;620;2941;Aleje Jerozolimskie
1;0;1.4832;0.2913;5;LINESTRING (21.00838 52.23515, 21.00835 52.23522);0.0;0.34;12;180;44;Segment 7
2;0;97.8901;0.3204;3;LINESTRING (21.00838 52.23515, 21.0082 52.23512);0.07;0.0;35;540;2877;Aleje Jerozolimskie

The result contains nodes stored as separate rows in CSV format separated by a ; symbol.

If Parent id is empty, this means the given row is the selected link of the analysis. Columns that are not filled in, for example the enhanced metric columns of an analysis created without them, are empty. The CSV result carries no metadata.

Protobuf response example

For more information about the format you can check Protocol Buffers.

The following schema is required to deserialize the results:

Protobuf schema format
syntax = "proto3";


message Point {
    double lon = 1;
    double lat = 2;
}


message Node {
    optional uint32 parent_id = 1;
    uint32 id = 2;
    repeated Point geo = 3;
    optional uint32 frc = 4;
    double processingFailuresPercent = 5;
    double privacyTrimsPercent = 6;
    optional double percentage = 7;
    optional double marginOfError = 8;
    optional uint32 avgTravelTimeInSeconds = 9;
    optional uint32 distanceInMeters = 10;
    optional uint32 volume = 11;
    string roadName = 12;
    optional string fullPathHash = 13;
    optional uint32 timeRangeIndex = 14;
}


message Result {
    repeated Node nodes = 1;
}

The protobuf result carries no metadata.

Shapefile response

The shapefile result is returned as a ZIP archive containing:

  • <analysisId>.shp, <analysisId>.shx, <analysisId>.dbf, <analysisId>.prj - standard ESRI Shapefile components. Coordinate reference system: WGS84 (EPSG:4326).
  • <analysisId>.fix - spatial index.
  • metadata.xml - analysis metadata (see fields below).

Each feature is a LineString representing one node of the result, with the following attributes:

Attribute

Description

the_geom
LineString

Geometry of the node in WGS84.

frc
integer

Functional Road Class.

id
integer

Id of the node.

parent_id
integer

Parent id of the node. null for the selected link of the analysis.

proc_fail
number

Processing failures, as a percentage of the traffic of the selected link.

priv_trims
number

Privacy trims, as a percentage of the traffic of the selected link.

percentage
number

Share of the traffic of the selected link that the node carries, in percent.

marg_error
number

Distance from percentage to the furthest end of its 95% confidence interval, in percentage points.

avg_time_s
number

Average travel time from link to selected node, in seconds. null without the TRAVEL_TIME_AND_DISTANCE enhanced metric.

distance_m
number

Average traveled distance from link to node, in meters. null without the TRAVEL_TIME_AND_DISTANCE enhanced metric.

volume
integer

Estimated absolute traffic volume. null without the VOLUME enhanced metric.

road_name
string

Name of the last road segment of the node.

Shapefile metadata

The metadata.xml file inside the shapefile archive contains the same fields as the JSON metadata object, serialized as XML under a <selectedLinkMetadata> root element.

metadata.xml example
<?xml version="1.0" encoding="UTF-8"?>
<selectedLinkMetadata>
  <resultType>INCOMING</resultType>
  <dateRange>
    <startDate>2026-01-01</startDate>
    <endDate>2026-03-31</endDate>
  </dateRange>
  <timeRange>
    <startTime>07:00</startTime>
    <endTime>09:00</endTime>
  </timeRange>
  <timeZone>Europe/Amsterdam</timeZone>
  <geometry>LINESTRING (4.89 52.37, 4.9 52.38)</geometry>
  <bufferRadiusInMeters>10000</bufferRadiusInMeters>
  <mapType>ORBIS</mapType>
  <mapVersion>{map_version}</mapVersion>
  <dataSources>ALL</dataSources>
  <regionEntrancesFrcs>0,1,2</regionEntrancesFrcs>
  <enhancedMetrics>VOLUME,TRAVEL_TIME_AND_DISTANCE</enhancedMetrics>
</selectedLinkMetadata>

Note: in XML, regionEntrancesFrcs and enhancedMetrics are single elements holding comma-separated values; in JSON they are arrays.

Filtering results by path hash

A version 2 analysis lets you follow one path instead of downloading a whole result. Take the fullPathHash of a node from a protobuf result and ask for that path alone. The endpoint aggregates over all time ranges of the given date range, so the response holds one node per time range, each with its timeRangeIndex.

fullPathHash is reported in the protobuf format only.

get
URL request format
https://api.tomtom.com/origindestination/1/analysis/selected-link/{id}/result/{pathHash}?dateRange={dateRange}&type={type}&key={Your_API_Key}
get
URL request example
https://api.tomtom.com/origindestination/1/analysis/selected-link/512/result/9f2a1c7d8e4b6a05c3d9f1e2b7a48c60?dateRange=0&type=INCOMING&key={Your_API_Key}

Parameter

Description

pathHash
string

fullPathHash of a node, taken from a protobuf result of the same analysis.

dateRange
integer

Index of the date range, counted from 0 in the order of timeDefinition.dateRanges.

type
string

Direction of the result. One of INCOMING, OUTGOING or INSIDE.

format
string

Optional. Only PROTOBUF is supported.


Default value: PROTOBUF

The endpoint requires an analysis created with "analysisVersion": 2.

The response uses a third protobuf schema:

Protobuf schema format
syntax = "proto3";


message Node {
    optional string fullPathHash = 1;
    optional uint32 timeRangeIndex = 2;
    optional double percentage = 3;
    optional double marginOfError = 4;
    optional uint32 avgTravelTimeInSeconds = 5;
    optional uint32 distanceInMeters = 6;
    optional uint32 volume = 7;
}


message Result {
    repeated Node nodes = 1;
}