Start speed summary job

Creates a job to generate a speed summary analysis. Returns aggregated speed metrics (spot speed, travel speed, free-flow speed, pace bands, percentiles, observed count, vehicle-class/vocation/industry breakdowns) across the supplied road segments or zones, optionally broken out by aggregation period. Only Custom and Segment zone types are accepted; requests with other zone types are rejected.

Altitude Help Center — getSpeedAnalysisSummary

Request Body

Analysis parameters.

application/json: object

Name	Type	Input Shape	Values	Description	Value Required
`aggregationPeriod`	object	unit: string; value: integer	-	Time interval used to group the results. Set unit to '*' for one summary of the whole period, or to 'hour', 'minute' or 'week' for a breakdown over time.	Y
`dateFrom`	string (date)	-	-	First date of the analysis range, formatted as yyyy-mm-dd.	Y
`dateTo`	string (date)	-	-	Last date of the analysis range (inclusive), formatted as yyyy-mm-dd.	Y
`daysOfWeek`	array<integer>	-	-	Days of the week to include (1=Sunday … 7=Saturday). An empty array includes all days.	N
`isDirectional`	boolean	-	-	When true, one record is returned per direction of travel; when false, results are averaged across both directions.	Y
`isMetric`	boolean	-	-	When true, speeds are returned in km/h; when false, in mph. Defaults to the unit setting in your user profile when omitted.	N
`jobId`	string	-	-	Optional identifier for the job. Generated by the server when omitted.	N
`percentiles`	array<integer>	-	-	Percentile values to compute (1–99). Defaults to the 15th, 50th and 85th percentiles when omitted.	N
`segmentsDirectional`	array<object>	direction: integer (values: -1, 1); segmentId: string	-	Ordered directional road segments. Provide exactly one of zones, zoneIds, or segmentsDirectional. Direction must be 1 or -1; input order is preserved.	N
`timeFrom`	string	-	-	Start of the time-of-day window, formatted as hh:mm:ss. Defaults to 00:00:00 when omitted.	N
`timeTo`	string	-	-	End of the time-of-day window, formatted as hh:mm:ss.999. Defaults to 23:59:59.999 when omitted.	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; IDs that do not name a known vehicle class are rejected. An empty array includes all vehicle classes.	N
`vehicleClassSchemeId`	integer	-	1, 2, 3, 4, 5, 6	Vehicle classification scheme: 1 = VIUS, 2 = GVWR (FHWA), 3 = Truck Weight Classes, 4 = CARB, 5 = Gross Weight Group (custom scheme), 6 = Expansion Factors (custom scheme). Defaults to 2 when omitted. See GET /api/v2/filters/vehicle-class-schemes.	N
`vehicleClasses`	array<object>	vehicleType: string (values: Truck, Passenger, MPV, Bus, Limo, Other, n/a); weightClass: string (values: *, Class 1, Class 2, Class 3, Class 4, Class 5, Class 6, Class 7, Class 8, Class A, Class B, Class C, Class D, Class E, Class F, Class G, Class H)	-	Vehicle class filters. Use an empty array to include all vehicle classes.	N
`zoneIds`	array<string>	-	-	Zones to include, as encoded zone IDs. Provide exactly one of zoneIds or zones (not both).	N
`zones`	array<object>	code: string; iso_3166_2: string; type: string (values: Custom, Segment)	-	Zones to include, each identified by a code, a zone type and a state or province code (iso_3166_2). Provide exactly one of zones or zoneIds (not both).	N

Examples

Directional segment speed summary

Translated from the v1 directional-segment sample using the v2 segmentsDirectional selector.

{
  "aggregationPeriod": {
    "unit": "*",
    "value": 1
  },
  "dateFrom": "2026-01-01",
  "dateTo": "2026-01-07",
  "daysOfWeek": [],
  "isDirectional": true,
  "isMetric": false,
  "percentiles": [
    15,
    50,
    85
  ],
  "segmentsDirectional": [
    {
      "direction": 1,
      "segmentId": "-5413282495872703901"
    },
    {
      "direction": 1,
      "segmentId": "-4350021053557322330"
    },
    {
      "direction": 1,
      "segmentId": "-5326185399566610743"
    }
  ],
  "timeFrom": "00:00:00",
  "timeTo": "23:59:59.999",
  "vehicleClassSchemeId": 2,
  "vehicleClasses": []
}

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.