Start corridor OD matrix job

Creates a job to generate a corridor/segment flow analysis. Counts vehicles traversing an ordered sequence of road segments in each direction and produces journey metrics per O/D pair and direction.

Altitude Help Center — Corridor/Segment Flow API

Request Body

Analysis parameters.

application/json: object

Name	Type	Input Shape	Values	Description	Value Required
`aggregationUnits`	array<string>	-	hour, dayofweek, daytype, daytypehour	Time-series dimensions to generate when generateTimeSeries is true. Valid values: hour, dayofweek, daytype, daytypehour. An empty array generates all four.	N
`componentTimeRange`	object	component: string; timeFrom: string; timeTo: string	-	Time-of-day window and journey endpoint constraint applied to the analysis.	Y
`connectorAndCondition`	boolean	-	-	When true, journeys must pass through all connectors; when false (default), passing through at least one is sufficient.	N
`connectorIds`	array<string>	-	-	Encoded zone IDs that journeys must pass through. Provide either connectorIds or connectors, not both.	N
`connectors`	array<object>	code: string; iso_3166_2: string; type: string	-	Zone objects that journeys must pass through (subject to connectorAndCondition). Provide either connectors or connectorIds, not both.	N
`customAggregationValues`	array<object>	aggregationValue: string; hourEnd: integer (int64); hourStart: integer (int64)	-	Custom hourly range buckets appended to the time-series output in addition to any aggregationUnits selections.	N
`dateRanges`	array<DateRangeDto>	dateFrom: string; dateTo: string	-	Date ranges to include in the analysis. Maximum 4 non-overlapping ranges, each up to 365 days. Results are aggregated across all ranges unless isTrendAnalysis is true.	Y
`daysOfWeek`	array<DayOfWeek>	-	1, 2, 3, 4, 5, 6, 7	Days of the week to include (1=Sunday … 7=Saturday). An empty array includes all days.	N
`destinationIds`	array<string>	-	-	Encoded destination zone IDs. IDs use passThrough=false. Provide either destinationIds or destinations, not both.	N
`destinations`	array<object>	code: string; iso_3166_2: string; passThrough: string (values: false, true, only); type: string	-	Destination zone objects for the analysis. passThrough is optional and accepts 'false', 'true', or 'only'; omitted values default to 'false'. Provide either destinations or destinationIds, not both.	N
`generateTimeSeries`	boolean	-	-	When true, a time-series breakdown child analysis is generated for each aggregation unit. Results are retrievable via GET /api/v2/origin-destination/corridor-matrix/{id}/time-series once the job is complete.	Y
`industries`	array<IndustryGroup>	-	agriculture, mining, utilities, construction, manufacturing, wholesale, retail, transportation_and_warehousing, information_and_cultural, finance_and_insurance, real_estate, science_and_technology, management, administrative_and_support, education, health_care, arts_and_entertainment, accommodation_and_food, public_administration, other_services, unclassified	Named industry IDs from GET /api/v2/filters/industries (e.g. 'manufacturing', 'retail'). Resolved to NAICS codes at query time and combined with any naics values. Leave both industries and naics empty to include all industries.	N
`isMetric`	boolean	-	-	When true, distance values are returned in kilometres; when false, in miles. If omitted, defaults to the isMetric setting on the authenticated user's profile.	N
`isTrendAnalysis`	boolean	-	-	When true, results are returned per date range instead of aggregated across all ranges.	N
`naics`	array<integer (int64)>	-	-	Explicit raw NAICS integer codes to filter by. Combined with any industries values. Leave both naics and industries empty to include all industries.	N
`originIds`	array<string>	-	-	Encoded origin zone IDs. IDs use passThrough=false. Provide either originIds or origins, not both.	N
`origins`	array<object>	code: string; iso_3166_2: string; passThrough: string (values: false, true, only); type: string	-	Origin zone objects for the analysis. passThrough is optional and accepts 'false', 'true', or 'only'; omitted values default to 'false'. Provide either origins or originIds, not both.	N
`percentiles`	array<integer (int64)>	-	-	Percentile values (1–99) to calculate for journey distance and duration. Defaults to [15, 85] when omitted.	N
`tripChainCriteria`	object	maxStopDuration: integer (int64); shortJourneyDistanceThreshold: number (double)	-	Trip-chaining criteria. Omit or send zero values to run without trip chaining.	N
`vehicleClassIds`	array<string>	-	-	Vehicle class filter IDs from GET /api/v2/filters/vehicle-classes. IDs must use the scheme_vehicleClassIndex_categoryIndex format and share one scheme. An empty array includes all vehicle classes.	N
`vehicleClassSchemeId`	integer	-	-	Vehicle classification scheme, from 1 through 5. Defaults to 2 (FHWA/GVWR) when omitted.	N
`vehicleClasses`	array<object>	vehicleType: string; weightClass: string	-	Vehicle class filters. Use an empty array to include all vehicle classes.	N
`vocations`	array<VocationID>	-	1, 2, 3, 4, 5	Vocation IDs from GET /api/v2/filters/vocations. An empty array includes all vocations.	N

Examples

Segment corridor request

Converted from the v1 corridor/segment flow example using v2 zone fields.

{
  "componentTimeRange": {
    "component": "Both",
    "timeFrom": "00:00:00",
    "timeTo": "23:59:59.999"
  },
  "dateRanges": [
    {
      "dateFrom": "2026-01-01",
      "dateTo": "2026-01-31"
    }
  ],
  "destinations": [
    {
      "code": "32023",
      "iso_3166_2": "US-NV",
      "passThrough": "false",
      "type": "County"
    }
  ],
  "generateTimeSeries": false,
  "isMetric": false,
  "origins": [
    {
      "code": "32003",
      "iso_3166_2": "US-NV",
      "passThrough": "false",
      "type": "County"
    }
  ]
}

Success Responses

202 response: object

Job accepted and queued for processing. Poll the location header URL to check status.

Name	Type	Description
`error`	object	Details about why the job failed (RFC 7807 format), or null if it succeeded.
`id`	string	Unique job identifier.
`links`	object	Navigation URLs for polling and result retrieval.
`status`	string	Current job lifecycle state: PENDING, QUEUED, RUNNING, DONE, FAILED, CANCELED, or NOT_FOUND.

Response Errors

HTTP Status Code	Reason
400	The request body or parameters are invalid.
401	Authentication is required or the provided credentials are invalid.
403	The authenticated user lacks permission to perform this operation.
409	The operation conflicts with the current state of the resource.
422	The request is syntactically valid but semantically cannot be processed.
429	The request rate limit has been exceeded.
500	An unexpected server error occurred.