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.

Note:

See Special Case APIs for more information.

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.

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 Req'd
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. The default is [“hour”, “daytype”, “daytypehour”]. Note: An empty array will return all available time series.	ARRAY	“hour”, “daytype”, “daytypehour”	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	-	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	Whether to retain journeys which could have begun chaining prior to the origin. The default is true. If `tripChainWithinOrigin` is set to false, this parameter is automatically set to true regardless of the input value.	BOOLEAN	true or false	N
retainForwardChainingDestination	Whether to retain journeys which could have continued to chain beyond the destination. The default is true. If `tripChainWithinOrigin` is set to false, this parameter is automatically set to true regardless of the input value.	BOOLEAN	true or false	N
retainSubJourneys	Whether to retain sub-journeys which are part of a larger journey when using trip chaining. This parameter is not considered for destinations that are set as passthrough. Defaults to true.	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

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 altitudesupport@geotab.com if this occurs.

Analysis limits

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: 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". DateFromUTC (string) - first UTC date in the analysis date range formatted as "yyyy-mm-dd" (utilized in follow-on API request processing e.g. `getRouteAnalysis`) 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	-
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: “State” — state name “County” — county name “City” — city name “CTR” — census tract description “Segment” — road name, if available “Custom” — custom zone name 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: Percentile (integer): the percentile value. Value (float): the calculated percentile duration at destination value (minutes). Note: 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	-
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. Note: If no trip chaining is applied i.e. `tripChainDuration` is 0, this value will also be 0.	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. Note: If no trip chaining is applied i.e. `tripChainDuration` is 0, this value will also be 0.	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. Note: If no trip chaining is applied i.e. `tripChainDuration` is 0, this value will also be 0.	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: NAICS_Code_1 (integer) — NAICS code 1. JourneyCount (integer) — number of journeys.	ARRAY	-
JourneyCountByVehicleClass	Array of objects representing journey count metrics for each vehicle class. Each object contains: SchemeId (integer) — vehicle class scheme identifier. CategoryIndex (integer) — vehicle class category identifier. VehicleClassIndex (integer) — vehicle class identifier. VehicleClass (string) — vehicle class name. JourneyCount (integer) — number of journeys. ByVocation (array) — an array of objects representing journey count metrics by vehicle class and vocation. Each object contains: VocationId (integer) — unique identifier for the vocation. Vocation (string) — vocation name. JourneyCount (integer) — number of journeys. ByIndustry (array) — an array of objects representing journey count metrics by vehicle class and industry. Each object contains: NAICS_Code_1 (integer) — NAICS code 1. JourneyCount (integer) — number of journeys.	ARRAY	-
JourneyCountByVocation	Array of objects representing journey counts for each vocation. Each object contains: VocationId (integer) — unique identifier for the vocation. Vocation (string) — vocation name. JourneyCount (integer) — number of journeys.	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: Percentile (integer): the percentile value. Value (float): the calculated percentile journey distance value (kilometers or miles). Note: 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	-
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: Percentile (integer): the percentile value. Value (float): the calculated percentile journey duration value (minutes). 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: “State” — state name “County” — county name “City” — city name “CTR” — census tract description “Segment” — road name, if available “Custom” — custom zone name 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	-

Time Series Response Schema

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: 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". DateFromUTC (string) - first UTC date in the analysis date range formatted as "yyyy-mm-dd" (utilized in follow-on API request processing e.g. getRouteAnalysis) 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	“hour”, “daytype”, “daytypehour”
AggregationValue	The associated AggregationUnit value. The value set is based on the AggregationUnit value. Value format based on AggregationUnit: hour - number of the hour based on 24 hour, e.g. 1 or 16 daytype - string for the day type [“Weekend” ,“Weekday”] 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: “State” — state name “County” — county name “City” — city name “CTR” — census tract description “Segment” — road name, if available “Custom” — custom zone name 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: Percentile (integer): the percentile value. Value (float): the calculated percentile duration at destination value (minutes). 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	-
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	-
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. If no trip chaining is applied i.e. tripChainDuration is 0, this value will also be 0.	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. If no trip chaining is applied i.e. tripChainDuration is 0, this value will also be 0.	FLOAT	-
JourneyCount	The total number of journeys between the O/D pair.	INTEGER	-
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	-
JourneyDurationPercentiles	Array of objects representing percentile journey distance values for input percentiles. Each object contains: Percentile (integer): the percentile value. Value (float): the calculated percentile journey distance value (kilometers or miles). 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	-
OriginZoneDescription	Description of the origin zone when available. The is based on the type of zone: “State” — state name “County” — county name “City” — city name “CTR” — census tract description “Segment” — road name, if available “Custom” — custom zone name 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	-
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	-
ZonePairId	Unique identifier representing each O/D pair. IDs are used for follow-on API requests like getRouteAnalysis.	STRING	-

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>"
		}
	]
}

Altitude

Learn Altitude

Support

queryType: getOriginDestinationMatrix*

Parameters

Responses

Analysis limits

Time Series Response Schema

Sample Parameters for the functionParameters Object

On this page