Closed OD API

The getZoneClosedOriginDestinationMatrix queryType generates a list of origin and destination pairs that contain various journey metrics for the origin and destination combo.

Parameters

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

ParameterDescriptionTypeDefined Value SetValue Required
queryTypeMust equal getZoneClosedOriginDestinationMatrix.STRINGgetZoneClosedOriginDestinationMatrixY
aggregationUnits

The 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 — breakdown by hour from 0 to 23.
  • dayofweek — breakdown by day-of-week.
  • daytype — 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 — breakdown by day type ("Weekend", "Weekday") and hour from 0 to 23.
ARRAY"hour", "dayofweek", "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
connectorAndConditionTrue if the vehicle must pass through all connectors for a given journey, false if it must pass at least one connector. Default is false.BOOLEANTrue or falseN
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".
Note: Analysis outputs will be aggregated and returned over all date ranges combined unless you input true for isTrendAnalysis, which returns results per date range. A maximum of 4 date ranges may be provided.
ARRAY-Y
daysOfWeekAn 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. Pass the jobId value from this API call as the analysisJobId parameter and "getZoneClosedOriginDestinationMatrixTimeSeries" as the analysisType parameter value.
BOOLEANtrue or falseY
isMetricTrue if you want the data returned to be metric, false if you want imperial.BOOLEANTrue or falseY
isTrendAnalysis

Pass true if you want your results grouped based on the dateRanges parameter. For example, 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.

Note: When set to true, this will be applied to both the main output and the time series output.
BOOLEANtrue or falseN
NAICSAn 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].

Note: Percentiles are calculated for journey distance, journey duration, and duration at destination.
ARRAY[1, 5, 10, 15, 20, 30, 40, 50, 60, 70, 80, 85, 90, 95, 99]N
tripChainCriteria

An object that defines the trip chaining criteria to be applied for an analysis. Pass null if you wish to run without trip chaining. The object contains:

  • MaxStopDuration (integer) — amount of time (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.
  • ShortJourneyDistanceThreshold (float) — journey distance (kilometers or miles) used as the threshold distance for excluding short journeys. Any journey whose distance (after trip chaining is applied) is shorter than the threshold (inclusive) will be excluded from the analysis.

Default value is an empty object (no trip chaining).

Note: If you pass an empty object, no trip chaining will be applied.
OBJECTmaxStopDuration — [0, 15, 30, 60, 120, 480, 720]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 the Vehicle Types and Weight Class tables. If a vehicle type does not have any weight classes listed, pass "*". To get all vehicle classes returned, pass an empty array.

ARRAYFor Vehicle Type: "Truck", "Passenger", "MPV", "Bus", "Other". To get all vehicle types, pass an empty array.N
vehicleClassSchemeIdDetermines for which vehicle classification scheme you will receive data. See the Vehicle Class Schemas for a list of options. The default value is 2.INTEGER[1:5]N
vocationsAn array of integers representing vocation IDs for vocations of interest. Can pass specific IDs or an empty array to return data for all vocations.ARRAYSee Vocations 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 — "Custom", "State", "County", "City", "TAZ", "ZIP", "CTR", or "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 or standard zone ID (such as county ID, city ID, etc.).
  • 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 — "Custom", "State", "County", "City", "TAZ", "ZIP", "CTR", or "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 or standard zone ID (such as county ID, city ID, etc.).
  • 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 — "Custom", "State", "County", "City", "TAZ", "ZIP", "CTR", or "FSA".

See Zones for details on how to structure the zone inputs for each zone type.

N

Responses

CodeTypeDescription
200JSONThe requested data.
401JSONOccurs for various unauthorized tasks, such as not providing credentials in your parameters.
500JSONOccurs if an internal server error occurs. Contact Altitude Support if this occurs.

Primary Response Schema

AttributeDescriptionData TypeDefined 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".
ARRAY-
AnalysisJobIdAnalysis job identifier for the O/D pair. This is required for follow-on API requests, for example getRouteAnalysis.STRING-
DailyJourneyCountAvgThe average daily number of journeys between the O/D pair.FLOAT-
DestinationZoneDescription

Description of the destination zone when available, based on the type of zone:

  • "State" — state name
  • "County" — county name
  • "City" — city name
  • "CTR" — census tract description
  • "Custom" — custom zone name

For all other zones, this attribute is null.

STRING-
Destination_ISO_3166_2Unique ISO 3166-2 identifier representing the state/provincial code of the Destination.STRING-
DestinationZoneTypeZone type of the Destination.STRING-
DestinationZoneIdA unique identifier for the Destination zone.STRING-
DurationAtDestinationAvgThe average stop duration at the destination before the next journey (minutes).FLOAT-
DurationAtDestinationMedThe 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-
DurationAtDestinationStdevThe standard deviation of the stop duration at the destination before the next journey (minutes).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., maxStopDuration 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., maxStopDuration 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., maxStopDuration is 0), this value will also be 0.
FLOAT-
JourneyCountThe total number of journeys between the O/D pair.INTEGER-
JourneyMetricsByFuelType

Array of objects representing journey count metrics for each fuel type. Each object contains:

  • FuelType (string) — fuel type.
  • JourneyCount (integer) — number of journeys.
  • JourneyDistanceAvg (float) — average distance traveled between an O/D pair (kilometers or miles).
  • JourneyDistanceMed (float) — median distance traveled between an O/D pair (kilometers or miles).
  • JourneyDurationAvg (float) — average journey duration between the O/D pair (minutes).
  • JourneyDurationMed (float) — median journey duration between the O/D pair (minutes).
  • InterTripStopDurationAvg (float) — average of the total stop duration that occurs during the journey (minutes).
  • InterTripStopDurationMed (float) — median of the total stop duration that occurs during the journey (minutes).
  • DurationAtDestinationAvg (float) — average stop duration at the destination (minutes).
  • DurationAtDestinationMed (float) — median stop duration at the destination (minutes).
ARRAY-
JourneyMetricsByIndustry

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.
  • JourneyDistanceAvg (float) — average distance traveled between an O/D pair (kilometers or miles).
  • JourneyDistanceMed (float) — median distance traveled between an O/D pair (kilometers or miles).
  • JourneyDurationAvg (float) — average journey duration between the O/D pair (minutes).
  • JourneyDurationMed (float) — median journey duration between the O/D pair (minutes).
  • InterTripStopDurationAvg (float) — average of the total stop duration that occurs during the journey (minutes).
  • InterTripStopDurationMed (float) — median of the total stop duration that occurs during the journey (minutes).
  • DurationAtDestinationAvg (float) — average stop duration at the destination (minutes).
  • DurationAtDestinationMed (float) — median stop duration at the destination (minutes).
ARRAY-
JourneyMetricsByVehicleClass

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.
  • JourneyDistanceAvg (float) — average distance traveled between an O/D pair (kilometers or miles).
  • JourneyDistanceMed (float) — median distance traveled between an O/D pair (kilometers or miles).
  • JourneyDurationAvg (float) — average journey duration between the O/D pair (minutes).
  • JourneyDurationMed (float) — median journey duration between the O/D pair (minutes).
  • InterTripStopDurationAvg (float) — average of the total stop duration that occurs during the journey (minutes).
  • InterTripStopDurationMed (float) — median of the total stop duration that occurs during the journey (minutes).
  • DurationAtDestinationAvg (float) — average stop duration at the destination (minutes).
  • DurationAtDestinationMed (float) — median stop duration at the destination (minutes).
ARRAY-
JourneyMetricsByVehicleClassVocation

Array of objects representing journey count metrics for each vehicle class/vocation combination. 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.
  • VocationId (integer) — unique identifier for the vocation.
  • Vocation (string) — vocation name.
  • JourneyCount (integer) — number of journeys.
  • JourneyDistanceAvg (float) — average distance traveled between an O/D pair (kilometers or miles).
  • JourneyDistanceMed (float) — median distance traveled between an O/D pair (kilometers or miles).
  • JourneyDurationAvg (float) — average journey duration between the O/D pair (minutes).
  • JourneyDurationMed (float) — median journey duration between the O/D pair (minutes).
  • InterTripStopDurationAvg (float) — average of the total stop duration that occurs during the journey (minutes).
  • InterTripStopDurationMed (float) — median of the total stop duration that occurs during the journey (minutes).
  • DurationAtDestinationAvg (float) — average stop duration at the destination (minutes).
  • DurationAtDestinationMed (float) — median stop duration at the destination (minutes).
ARRAY-
JourneyMetricsByVehicleClassIndustry

Array of objects representing journey count metrics for each vehicle class/industry combination. 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.
  • NAICS_Code_1 (integer) — NAICS code 1.
  • JourneyCount (integer) — number of journeys.
  • JourneyDistanceAvg (float) — average distance traveled between an O/D pair (kilometers or miles).
  • JourneyDistanceMed (float) — median distance traveled between an O/D pair (kilometers or miles).
  • JourneyDurationAvg (float) — average journey duration between the O/D pair (minutes).
  • JourneyDurationMed (float) — median journey duration between the O/D pair (minutes).
  • InterTripStopDurationAvg (float) — average of the total stop duration that occurs during the journey (minutes).
  • InterTripStopDurationMed (float) — median of the total stop duration that occurs during the journey (minutes).
  • DurationAtDestinationAvg (float) — average stop duration at the destination (minutes).
  • DurationAtDestinationMed (float) — median stop duration at the destination (minutes).
ARRAY-
JourneyMetricsByVocation

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.
  • JourneyDistanceAvg (float) — average distance traveled between an O/D pair (kilometers or miles).
  • JourneyDistanceMed (float) — median distance traveled between an O/D pair (kilometers or miles).
  • JourneyDurationAvg (float) — average journey duration between the O/D pair (minutes).
  • JourneyDurationMed (float) — median journey duration between the O/D pair (minutes).
  • InterTripStopDurationAvg (float) — average of the total stop duration that occurs during the journey (minutes).
  • InterTripStopDurationMed (float) — median of the total stop duration that occurs during the journey (minutes).
  • DurationAtDestinationAvg (float) — average stop duration at the destination (minutes).
  • DurationAtDestinationMed (float) — median stop duration at the destination (minutes).
ARRAY-
JourneyDistanceAvgThe average distance traveled between an O/D pair (kilometers or miles).FLOAT-
JourneyDistanceMedThe median distance traveled between an O/D pair (kilometers or miles).FLOAT-
JourneyDistancePercentile

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-
JourneyDistanceStdevThe standard deviation of the distance traveled between the O/D pair (kilometers or miles).FLOAT-
JourneyDurationAvgThe average journey duration (minutes) between the O/D pair (in minutes).FLOAT-
JourneyDurationMedThe 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).
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-
JourneyDurationStdevThe standard deviation of the journey duration (minutes) between the O/D pair (in minutes).FLOAT-
JourneyTripCountAvg

The average number of trips per journey.

Note: If no trip chaining is applied (i.e., maxStopDuration is 0), this value will also be 1.
FLOAT-
JourneyTripCountMed

The median number of trips per journey.

Note: If no trip chaining is applied (i.e., maxStopDuration is 0), this value will also be 1.
FLOAT-
JourneyTripCountStdevThe standard deviation of the number of trips per journey.FLOAT-
OriginZoneDescription

Description of the origin zone when available, based on the type of zone:

  • "State" — state name
  • "County" — county name
  • "City" — city name
  • "CTR" — census tract description
  • "Custom" — custom zone name

For all other zones, this attribute is null.

STRING-
Origin_ISO_3166_2Unique ISO 3166-2 identifier representing the state/provincial code of the Origin.STRING-
OriginZoneTypeZone type of the Origin.STRING-
OriginZoneIdA unique identifier for the Origin zone.STRING-
ZonePairIdUnique identifier representing each O/D pair. IDs are used for follow-on API requests like getRouteAnalysis.STRING-

Sample Parameters

Sample parameters that should go inside your 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": true,
    "isMetric": true,
    "NAICS": [],
    "percentiles": [5, 15, 85, 95],
    "queryType": "getZoneClosedOriginDestinationMatrix",
    "tripChainCriteria": {
        "maxStopDuration": 30,
        "shortJourneyDistanceThreshold": 2
    },
    "vehicleClasses": [],
    "vehicleClassSchemeId": 2,
    "vocations": [],
    "zoneConnectors": [],
    "zoneDestinations": [
        {
            "ZoneId": "<ZoneId>",
            "ISO_3166_2": "<ISO_3166_2>",
            "ZoneType": "<ZoneType>"
        }
    ],
    "zoneOrigins": [
        {
            "ZoneId": "<ZoneId>",
            "ISO_3166_2": "<ISO_3166_2>",
            "ZoneType": "<ZoneType>"
        }
    ]
}

Time Series Response Schema

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

The time series breakdown results can be retrieved using the getSavedResults API. Pass the jobId value from the original API call as the analysisJobId parameter and "getZoneClosedOriginDestinationMatrixTimeSeries" as the analysisType parameter value.

AttributeDescriptionData TypeDefined 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".
ARRAY-
AggregationUnitThe time-based unit by which to aggregate data.STRING"hour", "dayofweek", "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 format, for example 1 or 16.
  • dayofweek — numeric value for day of week where Sunday is 1 and Saturday is 7.
  • daytype — string for the day type ["Weekend", "Weekday"].
  • daytypehour — string for day type and hour consolidated, for example "Weekday_22".
STRING-
DestinationZoneDescription

Description of the destination zone when available, based on the type of zone:

  • "State" — state name
  • "County" — county name
  • "City" — city name
  • "CTR" — census tract description
  • "Custom" — custom zone name

For all other zones, this attribute is null.

STRING-
Destination_ISO_3166_2Unique ISO 3166-2 identifier representing the state/provincial code of the Destination.STRING-
DestinationZoneTypeZone type of the Destination.STRING-
DestinationZoneIdA unique identifier for the Destination zone.STRING-
DurationAtDestinationAvgThe average stop duration at the destination before the next journey (minutes).FLOAT-
DurationAtDestinationMedThe median stop duration at the destination before the next journey (minutes).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., maxStopDuration 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., maxStopDuration is 0), this value will also be 0.
FLOAT-
JourneyCountThe total number of journeys between the O/D pair.INTEGER-
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.
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-
JourneyDistanceAvgThe average distance traveled between an O/D pair (kilometers or miles).FLOAT-
JourneyDistanceMedThe median distance traveled between an O/D pair (kilometers or miles).FLOAT-
JourneyDurationAvgThe average journey duration (minutes) between the O/D pair (in minutes).FLOAT-
JourneyDurationMedThe median journey duration (minutes) between the O/D pair (in minutes).FLOAT-
OriginZoneDescription

Description of the origin zone when available, based on the type of zone:

  • "State" — state name
  • "County" — county name
  • "City" — city name
  • "CTR" — census tract description
  • "Custom" — custom zone name

For all other zones, this attribute is null.

STRING-
Origin_ISO_3166_2Unique ISO 3166-2 identifier representing the state/provincial code of the Origin.STRING-
OriginZoneTypeZone type of the Origin.STRING-
OriginZoneIdA unique identifier for the Origin zone.STRING-
ZonePairIdUnique identifier representing each O/D pair. IDs are used for follow-on API requests like getRouteAnalysis.STRING-
Previous
Next