queryType: getOriginDestinationMatrix*

The getOriginDestinationMatrix queryType is passed to the API to generate a list of origin and destination pairs that contain various journey metrics for the origin and destination combo.

The getOriginDestinationMatrix queryType is passed to the API to generate a list of origin and destination pairs that contain various journey metrics for the origin and destination combo. At least one origin and one destination must be passed to the API, and you can mix origin and destination types (custom zone origin with a standard zone destination, for example).

Note: This API is subject to tighter rate limit restrictions.

Tip: New purpose-built O/D APIs are available for more targeted analysis. See Closed O/D and Segment Flow API comparison for details.

Parameters

These parameters should be passed to the functionParameters object regardless of which method you choose to make an API request.


Parameter	Description	Type	Defined Value Set	Value Required
queryType	Must equal `getOriginDestinationMatrix`.	STRING	`getOriginDestinationMatrix`	Y
aggregationUnits	Array of requested time series aggregation units to be included in time series breakdowns. This attribute determines which time series breakdowns are generated if `generateTimeSeries` is set to true. Supported values (not case-sensitive) are: hour - for a breakdown by hour from 0 to 23. daytype - for a breakdown by day-of-week, where “Weekend” = [1,7] or Saturday through Sunday, and “Weekday” = [2,3,4,5,6] or Monday through Friday. daytypehour - for a breakdown by day type (“Weekend”, “Weekday”) and hour from 0 to 23.	ARRAY	“hour”, “daytype”, “daytypehour”	N
customAggregationValues	Array of objects representing custom hourly range buckets for time series breakdowns. The custom aggregation values have the `AggregationUnit` “Custom” and each object creates an additional time series breakdown if `generateTimeSeries` is set to true. These breakdowns are in addition to any selected in `aggregationUnits`. Each object contains: `AggregationValue` (string) — reference label for the custom aggregation bucket. `HourStart` (integer) — first hour in the bucket hourly range. `HourEnd` (integer) — last hour in the bucket hourly range. Note: An empty array will result in no additional time series breakdowns. Note: If both `aggregationUnits` and `customAggregationValues` are input, both resultant time series aggregations will be produced.	ARRAY	-	N
componentTimeRange	An object representing the analysis time range. Each object contains: TimeFrom (string) - start of the time range formatted as "hh:mm:ss.ms" string. TimeTo (string) - end of the time range formatted as "hh:mm:ss.ms" string. The default is “00:00:00” to “23:59:59.999”. Component (string) - one of "Start" (journey must start in this time range), "End" (journey must end in this time range) or "Both" (journey should start or end in this time range).	OBJECT	-	Y
connectorAndCondition	True if the vehicle must pass through all connectors for a given journey, false if it must pass at least one connector. Default to false.	BOOLEAN	True or false	N
dateRanges	An array of objects representing the date ranges of interest. Each object contains: DateFrom (string) - first date in the analysis date range, formatted as "yyyy-mm-dd". DateTo (string) - last date in the analysis date range, formatted as "yyyy-mm-dd". Analysis outputs will be aggregated and returned over all date ranges combined unless you input true for `isTrendAnalysis`where we will return results per date range.	ARRAY	Maximum of 4 date ranges.	Y
daysOfWeek	Array of integers representing each week day. Can send an empty array to return all days.	ARRAY	[1,7] (1 = Sunday, 2 = Monday, etc.)	N
generateTimeSeries	An indicator of whether to generate a time series breakdown (true) or not (false) as a child analysis. Time series will be generated for each time aggregation in aggregationUnits. Note: The time series breakdown results can be retrieved using the `getSavedResults` API. See How to Retrieve Time Series Results .	BOOLEAN	True or False	Y
isMetric	True if you want the data returned to be metric, false if you want imperial.	BOOLEAN	True or false	Y
isTrendAnalysis	Pass true if you want your results grouped based on the `dateRanges` parameter, i.e., if you pass 4 date ranges and this is set to true, you will get 4 sets of results, one for each date range. The default is false.	BOOLEAN	true or false	N
NAICS	An array of integers representing industry IDs. Can pass an empty array to return data for all industries. To get a list of available industries, use the `getIndustries` API.	INTEGER	-	N
percentiles	Array of integers representing the percentiles for which you would like data. The default if not provided is [15,85]. Percentiles are calculated for journey distance, journey duration and duration at destination.	ARRAY	[0, 99]	N
retainBackwardChainingOrigin	When trip chaining is enabled, a journey may be identified as part of a chain that started before the vehicle entered the origin zone. When set to `true` (default), these journeys are included in the OD matrix counts. When set to `false`, journeys where the vehicle's stop at the origin was shorter than the trip chaining threshold — indicating the origin was a mid-chain stop rather than a true starting point — are excluded from the results. If `tripChainWithinOrigin` is set to `false`, this parameter is automatically set to `true` regardless of the input value.	BOOLEAN	true or false	N
retainForwardChainingDestination	When trip chaining is enabled, a journey may be identified as part of a chain that continues after the vehicle leaves the destination zone. When set to `true` (default), these journeys are included in the OD matrix counts. When set to `false`, journeys where the vehicle's stop at the destination was shorter than the trip chaining threshold, indicating the destination was a mid-chain stop rather than a true final destination, are excluded from the results. If `tripChainWithinDestination` is set to `false`, this parameter is automatically set to `true` regardless of the input value.	BOOLEAN	true or false	N
retainSubJourneys	When trip chaining combines multiple stops into a single origin-to-destination journey, intermediate stops along the way are called sub-journeys. When set to `true` (default), each intermediate stop is also counted as a separate journey in the OD matrix, in addition to the full chained journey. When set to `false`, only the final chained journey (from the true origin to the true destination) is counted, and intermediate stops are not represented in the matrix. This parameter does not apply to destinations marked as passthrough.	BOOLEAN	true or false	N
tripChainDuration	The amount of time in minutes that a vehicle is allowed to stop and still be counted as part of the original journey. To view statistics related to stop durations, use the `getStaticStopDurationData` API. Default value is 0.	INTEGER	-	N
tripChainWithinDestination	Whether trip chaining occurs in the destination. The default is false. If this value is set to false, journeys' end at the first trip that enters the destination. If this value is set to true, the journey will continue to chain based on the `tripChainDuration` to the last trip that stops within the destination.	BOOLEAN	true or false	N
tripChainWithinOrigin	Whether trip chaining occurs in the origin. If this value is set to false, journeys start at the last trip to start and exit from the origin. The default is false. If this value is set to false, journeys start at the last trip to start and exit from the origin. If this value is set to true, the journey starts at the first trip to start within the origin within the context of `thetripChainDuration`.	BOOLEAN	true or false	N
vehicleClasses	An array of vehicle class objects where each object contains `VehicleType` and `WeightClass`. To get the list of possible vehicle types and weight classes, refer to Vehicle types and Weight class tables. If a vehicle type does not have any weight classes listed, just pass "*". More information on vehicle classes can be found at AFDC Vehicle Categories. To get all vehicle classes returned, pass an empty array.	ARRAY	See the Vehicle types and Weight class tables. For Vehicle Type: "Truck", "Passenger", "MPV", "Bus", "Other". More information at AFDC Vehicle Categories. To get all vehicle types, pass an empty array.	N
vehicleClassSchemeId	Determines which vehicle classification scheme you will receive data for. See the Vehicle class schemas for a list of options. The default value is 2.	INTEGER	[1,4]	N
vocations	An array of integers representing vocation IDs for vocations of interest. Can pass specific IDs or an empty array to return data for all vocations.	ARRAY	See Vocation descriptions for a list of vocation ids and their mapping information	N
zoneConnectors	An array of objects representing the zones that a journey should pass through (subject to the `connectorAndCondition` parameter) to be included in this analysis. Each object contains: `ZoneId` (string) – A custom zone ID, standard zone ID (such as county ID, city ID, etc.) or a segment ID. `ISO_3166_2` (string) – The ISO code of the standard zone. Does not apply to custom zones or segments and can be set to null. `ZoneType` (string) – the type of zone.	ARRAY	ZoneType - “Segment” “Custom” “State” “County” “City” “TAZ” “ZIP” “CTR” “FSA”. See Zones for details on how to structure the zone inputs for each zone type.	N
zoneDestinations	An array of objects representing the destination zones. Each object contains: `ZoneId` (string) – A custom zone ID, standard zone ID (such as county ID, city ID, etc.) or a segment ID. `ISO_3166_2` (string) – The ISO code of the standard zone. Does not apply to custom zones or segments and can be set to null. `ZoneType` (string) – the type of zone. `PassThrough` (string) - a string with "true", "false", or "only" options. "only" will exclude journeys that stopped within the destination and only consider those which stopped outside the zone and passed through it. "true" will include journeys that stopped or passed through the zone. "false" will include only journeys that stopped within the zone.	ARRAY	ZoneType - “Segment” “Custom” “State” “County” “City” “TAZ” “ZIP” “CTR” “FSA”. See Zones for details on how to structure the zone inputs for each zone type.	N
zoneNotConnectors	An array of objects representing the zones that a journey should NOT pass through to be included in this analysis. Each object contains: `ZoneId` (string) – A custom zone ID, standard zone ID (such as county ID, city ID, etc.) or a segment ID. `ISO_3166_2` (string) – The ISO code of the standard zone. Does not apply to custom zones or segments and can be set to null. `ZoneType` (string) – the type of zone.	ARRAY	ZoneType - “Segment” “Custom” “State” “County” “City” “TAZ” “ZIP” “CTR” “FSA”. See Zones for details on how to structure the zone inputs for each zone type.	N
zoneOrigins	An array of objects representing the origin zones. Each object contains: `ZoneId` (string) – A custom zone ID, standard zone ID (such as county ID, city ID, etc.) or a segment ID. `ISO_3166_2` (string) – The ISO code of the standard zone. Does not apply to custom zones or segments and can be set to null. `ZoneType` (string) – the type of zone. `PassThrough` (string) - a string with "true", "false", or "only" options. "only" will exclude journeys that started within origin and only consider those which started outside the zone and passed through it. "true" will include journeys that started or passed through the zone. "false" will include only journeys that started within the zone.	ARRAY	ZoneType - “Segment” “Custom” “State” “County” “City” “TAZ” “ZIP” “CTR” “FSA”. See Zones for details on how to structure the zone inputs for each zone type.	N

Note:

Both the UI and API defaults effectively result in no trip chaining. The API defaults retainBackwardChainingOrigin, retainForwardChainingDestination, and retainSubJourneys to true, but also defaults tripChainDuration to 0, which means trip chaining never activates regardless of the retain parameter values. The Altitude UI always explicitly sends false for all three retain parameters. In both cases, the retain parameters only take effect once tripChainDuration is greater than 0.

Depending on the number of days included in the analysis, the number of allowed O/D pairs changes. See the table to understand the limits.

Note: An analysis cannot include more than 366 days or more than 3500 Os, Ds, or Cs


Days	API Maximum O/D pairs	UI Maximum Number of Zones (Os, Ds, or Cs)
Up to 31 days	1,000,000 pairs	600 zones
32 to 93 days	100,000 pairs	300 zones
94 to 366 days	10,000 pairs	100 zones. Maximum date range of 1 year

Response Schema


Attribute	Description	Data Type	Defined Value Set
AggregationDateRanges	Array of objects representing the date ranges utilized for the aggregated metrics. Each object contains:	ARRAY	-
DailyJourneyCountAvg	The average daily number of journeys between the O/D pair.	FLOAT	-
DestinationZoneDescription	Description of the origin zone when available. The is based on the type of zone: For all other zones, this attribute is null.	STRING	-
Destination_ISO_3166_2	Unique ISO 3166-2 identifier representing the state/provincial code of the Destination.	STRING	-
DestinationPassThrough	Indicates the passthrough value applied to the destination.	STRING	“true”, “false” or “only”
DestinationZoneType	Zone type of the Destination.	STRING	-
DestinationZoneId	A unique identifier for the Destination zone.	STRING	-
DurationAtDestinationAvg	The average stop duration at the destination before the next journey (minutes).	FLOAT	-
DurationAtDestinationMed	The median stop duration at the destination before the next journey (minutes).	FLOAT	-
DurationAtDestinationPercentiles	Array of objects representing percentile duration at destination values for input percentiles. Each object contains:	ARRAY	-
DurationAtDestinationStdev	The standard deviation of the stop duration at the destination before the next journey (minutes).	FLOAT	-
IdleDurationAvg	The average of the total mid-journey idle duration (minutes). The mid-journey idle duration is calculated as a sum of the mid-trip idle duration of all trips that comprise the journey.	FLOAT	-
IdleDurationMed	The median of the total mid-journey idle duration (minutes). The mid-journey idle duration is calculated as a sum of the mid-trip idle duration of all trips that comprise the journey.	FLOAT	-
IdleDurationStdev	The standard deviation of the total mid-journey idle duration (minutes). The mid-journey idle duration is calculated as a sum of the mid-trip idle duration of all trips that comprise the journey.	FLOAT	-
InterTripStopDurationAvg	The average of the total stop duration that occurs during the journey. The stop duration during a journey is calculated as the sum of all stop durations between trips that comprise a journey.	FLOAT	-
InterTripStopDurationMed	The median of the total stop duration that occurs during the journey. The stop duration during a journey is calculated as the sum of all stop durations between trips that comprise a journey.	FLOAT	-
InterTripStopDurationStdev	The standard deviation of the total stop duration that occurs during the journey. The stop duration during a journey is calculated as the sum of all stop durations between trips that comprise a journey.	FLOAT	-
AnalysisJobId	Job key for the O/D analysis. The job key is required for follow-up API requests, e.g. getRouteAnalysis.	STRING	-
JourneyCount	The total number of journeys between the O/D pair.	INTEGER	-
JourneyCountByIndustry	Array of objects representing journey count metrics for each NAICS code 1. Each object contains:	ARRAY	-
JourneyCountByVehicleClass	Array of objects representing journey count metrics for each vehicle class. Each object contains:	ARRAY	-
JourneyCountByVocation	Array of objects representing journey counts for each vocation. Each object contains:	ARRAY	-
JourneyDistanceAvg	The average distance traveled between an O/D pair (kilometers or miles).	FLOAT	-
JourneyDistanceMed	The median distance traveled between an O/D pair (kilometers or miles).	FLOAT	-
JourneyDistancePercentiles	Array of objects representing percentile journey distance values for input percentiles. Each object contains:	ARRAY	-
JourneyDistanceStdev	The standard deviation of the distance traveled between the O/D pair (kilometers or miles).	FLOAT	-
JourneyDurationAvg	The average journey duration (minutes) between the O/D pair (in minutes).	FLOAT	-
JourneyDurationMed	The median journey duration (minutes) between the O/D pair (in minutes).	FLOAT	-
JourneyDurationPercentiles	Array of objects representing percentile journey duration values for input percentiles. Each object contains: If no percentiles are input, the 15th and 85th percentiles are provided by default. Percentiles will only be provided if there are sufficient records to calculate the requested percentiles.	ARRAY	-
JourneyDurationStdev	The standard deviation of the journey duration (minutes) between the O/D pair (in minutes).	FLOAT	-
JourneyTripCountAvg	The average number of trips per journey. If no trip chaining is applied i.e. `tripChainDuration` is 0, this value will also be 1.	FLOAT	-
JourneyTripCountMed	The median number of trips per journey. If no trip chaining is applied i.e. tripChainDuration is 0, this value will also be 1.	FLOAT	-
JourneyTripCountStdev	The standard deviation of the number of trips per journey.	FLOAT	-
OriginZoneDescription	Description of the origin zone when available. The is based on the type of zone: For all other zones, this attribute is null.	STRING	-
Origin_ISO_3166_2	Unique ISO 3166-2 identifier representing the state/provincial code of the Origin.	STRING	-
OriginPassThrough	Indicates the passthrough value applied to the origin.	STRING	“true”, “false” or “only”
OriginZoneType	Zone type of the Origin.	STRING	-
OriginZoneId	A unique identifier for the Origin zone.	STRING	-
RunningSpeedAvg	The average running speed (km/h or mph) for journeys. Running speed is calculated using only the time a vehicle is moving (excluding any time stopped).	FLOAT	-
RunningSpeedMed	The median running speed (km/h or mph) for journeys. Running speed is calculated using only the time a vehicle is moving (excluding any time stopped).	FLOAT	-
RunningSpeedStdev	The standard deviation of running speed (km/h or mph) for journeys. Running speed is calculated using only the time a vehicle is moving (excluding any time stopped).	FLOAT	-
TravelSpeedAvg	The average travel speed (km/h or mph) for journeys. Travel speed is calculated as the total distance divided by the journey duration.	FLOAT	-
TravelSpeedMed	The median travel speed (km/h or mph) for journeys. Travel speed is calculated as the total distance divided by the journey duration.	FLOAT	-
TravelSpeedStdev	The standard deviation of travel speed (km/h or mph) for journeys. Travel speed is calculated as the total distance divided by the journey duration.	FLOAT	-
ZonePairId	Unique identifier representing each O/D pair. IDs are used for follow-on API requests like getRouteAnalysis.	STRING	-

This breakdown result is only created if generateTimeSeries value is set to true.

The time series breakdown results can be retrieved using the getSavedResults API.


AggregationDateRanges	Array of objects representing the date ranges utilized for the aggregated metrics. Each object contains: DateToUTC (string) - last UTC date in the analysis date range formatted as "yyyy-mm-dd" (utilized in follow-on API request processing e.g. getRouteAnalysis)	ARRAY
AggregationUnit	The time based unit by which to aggregate data.	STRING
AggregationValue	The associated AggregationUnit value. The value set is based on the AggregationUnit value. Value format based on AggregationUnit: daytypehour - string for day type and hour consolidated e.g. “Weekday_22”	STRING
DestinationZoneDescription	Description of the origin zone when available. The is based on the type of zone: For all other zones, this attribute is null.	STRING

{
       "aggregationUnits": [].	
       "componentTimeRange": {
		"TimeFrom": "00:00:00",
		"TimeTo": "23:59:59",
		"Component": "Start"
	},
	"dateRanges": [
		{
			"DateFrom": "<YYYY-MM-DD>",
			"DateTo": "<YYYY-MM-DD>"
		}
	],
	"daysOfWeek": [],
       "generateTimeSeries": false,	
       "isMetric": true,
"NAICS": [],	
"percentiles": [5,15,85,95],
	"queryType": "getOriginDestinationMatrix",
	"tripChainDuration": 0,
	"vehicleClasses": [],
	"vehicleClassSchemeId": 2,
	"vocations": [],
	"zoneConnectors": [],
	"zoneDestinations": [
		{
			"ZoneId": "<ZoneId>",
			"ISO_3166_2": "<ISO_3166_2>",
			"ZoneType": "<ZoneType>",
			"PassThrough": "<PassThrough>"
		}
	],
	"zoneNotConnectors": [],
	"zoneOrigins": [
		{
			"ZoneId": "<ZoneId>",
			"ISO_3166_2": "<ISO_3166_2>",
			"ZoneType": "<ZoneCategory>",
			"PassThrough": "<PassThrough>"
		}
	]
}

{
       "aggregationUnits": [].	
       "componentTimeRange": {
		"TimeFrom": "00:00:00",
		"TimeTo": "23:59:59",
		"Component": "Start"
	},
	"dateRanges": [
		{
			"DateFrom": "<YYYY-MM-DD>",
			"DateTo": "<YYYY-MM-DD>"
		}
	],
	"daysOfWeek": [],
       "generateTimeSeries": false,	
       "isMetric": true,
"NAICS": [],	
"percentiles": [5,15,85,95],
	"queryType": "getOriginDestinationMatrix",
	"tripChainDuration": 0,
	"vehicleClasses": [],
	"vehicleClassSchemeId": 2,
	"vocations": [],
	"zoneConnectors": [],
	"zoneDestinations": [
		{
			"ZoneId": "<ZoneId>",
			"ISO_3166_2": "<ISO_3166_2>",
			"ZoneType": "<ZoneType>",
			"PassThrough": "<PassThrough>"
		}
	],
	"zoneNotConnectors": [],
	"zoneOrigins": [
		{
			"ZoneId": "<ZoneId>",
			"ISO_3166_2": "<ISO_3166_2>",
			"ZoneType": "<ZoneCategory>",
			"PassThrough": "<PassThrough>"
		}
	]
}

{
       "aggregationUnits": [].	
       "componentTimeRange": {
		"TimeFrom": "00:00:00",
		"TimeTo": "23:59:59",
		"Component": "Start"
	},
	"dateRanges": [
		{
			"DateFrom": "<YYYY-MM-DD>",
			"DateTo": "<YYYY-MM-DD>"
		}
	],
	"daysOfWeek": [],
       "generateTimeSeries": false,	
       "isMetric": true,
"NAICS": [],	
"percentiles": [5,15,85,95],
	"queryType": "getOriginDestinationMatrix",
	"tripChainDuration": 0,
	"vehicleClasses": [],
	"vehicleClassSchemeId": 2,
	"vocations": [],
	"zoneConnectors": [],
	"zoneDestinations": [
		{
			"ZoneId": "<ZoneId>",
			"ISO_3166_2": "<ISO_3166_2>",
			"ZoneType": "<ZoneType>",
			"PassThrough": "<PassThrough>"
		}
	],
	"zoneNotConnectors": [],
	"zoneOrigins": [
		{
			"ZoneId": "<ZoneId>",
			"ISO_3166_2": "<ISO_3166_2>",
			"ZoneType": "<ZoneCategory>",
			"PassThrough": "<PassThrough>"
		}
	]
}

[/concept/conbody/section/codeblock {""}) { "aggregationUnits": []. "componentTimeRange": { "TimeFrom": "00:00:00", "TimeTo": "23:59:59", "Component": "Start" }, "dateRanges": [ { "DateFrom": "<YYYY-MM-DD>", "DateTo": "<YYYY-MM-DD>" } ], "daysOfWeek": [], "generateTimeSeries": false, "isMetric": true, "NAICS": [], "percentiles": [5,15,85,95], "queryType": "getOriginDestinationMatrix", "tripChainDuration": 0, "vehicleClasses": [], "vehicleClassSchemeId": 2, "vocations": [], "zoneConnectors": [], "zoneDestinations": [ { "ZoneId": "<ZoneId>", "ISO_3166_2": "<ISO_3166_2>", "ZoneType": "<ZoneType>", "PassThrough": "<PassThrough>" } ], "zoneNotConnectors": [], "zoneOrigins": [ { "ZoneId": "<ZoneId>", "ISO_3166_2": "<ISO_3166_2>", "ZoneType": "<ZoneCategory>", "PassThrough": "<PassThrough>" } ] } (codeblock]

Responses


Code	Type	Description
200	JSON	The requested data.
401	JSON	Occurs for various unauthorized tasks, such as not providing credentials in your parameters.
500	JSON	Occurs if an internal server error occurs. Contact Altitude Support if this occurs.

Sample Parameters for the functionParameters Object

{
       "aggregationUnits": [].	
       "componentTimeRange": {
		"TimeFrom": "00:00:00",
		"TimeTo": "23:59:59",
		"Component": "Start"
	},
	"dateRanges": [
		{
			"DateFrom": "<YYYY-MM-DD>",
			"DateTo": "<YYYY-MM-DD>"
		}
	],
	"daysOfWeek": [],
       "generateTimeSeries": false,	
       "isMetric": true,
"NAICS": [],	
"percentiles": [5,15,85,95],
	"queryType": "getOriginDestinationMatrix",
	"tripChainDuration": 0,
	"vehicleClasses": [],
	"vehicleClassSchemeId": 2,
	"vocations": [],
	"zoneConnectors": [],
	"zoneDestinations": [
		{
			"ZoneId": "<ZoneId>",
			"ISO_3166_2": "<ISO_3166_2>",
			"ZoneType": "<ZoneType>",
			"PassThrough": "<PassThrough>"
		}
	],
	"zoneNotConnectors": [],
	"zoneOrigins": [
		{
			"ZoneId": "<ZoneId>",
			"ISO_3166_2": "<ISO_3166_2>",
			"ZoneType": "<ZoneCategory>",
			"PassThrough": "<PassThrough>"
		}
	]
}