Start road reverse lookup job

Creates a job to generate a road reverse lookup analysis. Given a set of zone IDs, identifies matching road segments and returns per-segment speed, travel-time, and vehicle breakdown metrics.

Altitude Help Center — getRoadReverseLookup

Request Body

Analysis parameters.

application/json: object

Name	Type	Input Shape	Values	Description	Value Required
`aggregationPeriod`	object	unit: string; value: integer	-	Aggregation interval for the analysis. Set unit to '*' for a full-period summary, or 'hour' / 'week' for time-series breakdowns.	Y
`dateFrom`	string	-	-	First date of the analysis range, formatted as yyyy-mm-dd.	Y
`dateTo`	string	-	-	Last date of the analysis range, 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
`excludeServiceRoads`	boolean	-	-	When true, service road categories are excluded from results. Defaults to true when omitted.	N
`filterAndCondition`	boolean	-	-	When true, a segment must satisfy all supplied filters (AND logic); when false, satisfying any one filter is sufficient (OR logic).	Y
`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 isMetric setting on the authenticated user's profile when omitted.	N
`jobId`	string	-	-	Optional job identifier in the format its_<unixMillis>_<11-char alphanumeric> (e.g. its_1234567890123_abcde123456). Generated by the server when omitted.	N
`percentiles`	array<integer>	-	-	Percentile values to compute (1–99). Defaults to [15, 50, 85] when omitted.	N
`roadTypes`	array<string>	-	living_street, motorway, motorway_link, primary, primary_link, residential, road, secondary, secondary_link, service, tertiary, tertiary_link, trunk, trunk_link, unclassified	OSM road types to include. Must contain at least one value.	Y
`speedLimitFilter`	object	filterMode: string; filterValue: number	-	Filter on posted speed limit. Provide filterValue (any float) and filterMode ('greater' or 'less'). At least one filter field across all filter fields is required.	N
`spotSpeedFilter`	object	filterMode: string; filterType: string; filterValue: number	-	Filter on spot speed. Provide filterValue, filterMode ('greater' or 'less'), and filterType ('average' or 'median').	N
`spotSpeedPctOfFreeFlowFilter`	object	filterMode: string; filterValue: number	-	Filter on spot speed as a percentage of free-flow speed.	N
`spotSpeedPctOfSpeedLimitFilter`	object	filterMode: string; filterValue: number	-	Filter on spot speed as a percentage of the posted speed limit.	N
`spotSpeedPctOverSpeedLimitFilter`	object	filterMode: string; filterValue: number	-	Filter on the percentage of vehicle passes where spot speed exceeded the speed limit.	N
`timeFrom`	string	-	-	Start of the time-of-day range, formatted as hh:mm:ss. Defaults to 00:00:00 when omitted.	N
`timeTo`	string	-	-	End of the time-of-day range, formatted as hh:mm:ss.999. Defaults to 23:59:59.999 when omitted.	N
`travelSpeedFilter`	object	filterMode: string; filterType: string; filterValue: number	-	Filter on travel speed. Provide filterValue, filterMode ('greater' or 'less'), and filterType ('average' or 'median').	N
`travelSpeedPctOfFreeFlowFilter`	object	filterMode: string; filterValue: number	-	Filter on travel speed as a percentage of free-flow speed.	N
`travelSpeedPctOfSpeedLimitFilter`	object	filterMode: string; filterValue: number	-	Filter on travel speed as a percentage of the posted speed limit.	N
`travelSpeedPctOverSpeedLimitFilter`	object	filterMode: string; filterValue: number	-	Filter on the percentage of vehicle passes where travel speed exceeded the speed limit.	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	Vehicle classification scheme, from 1 through 5. Defaults to 2 (FHWA/GVWR) when omitted.	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>	-	-	Encoded zone ID strings. Provide exactly one of zoneIds or zones (not both).	N
`zones`	array<object>	code: string; iso_3166_2: string; type: string (values: Country, State, County, City, FSA, ZIP, TAZ, CTR, Custom, Segment, RelatedRoad)	-	Zone objects with code, type, and iso_3166_2. Provide exactly one of zones or zoneIds (not both).	N

Examples

County road reverse lookup request

Translated from the v1 getRoadReverseLookup sample.

{
  "aggregationPeriod": {
    "unit": "*",
    "value": 1
  },
  "dateFrom": "2026-01-01",
  "dateTo": "2026-01-07",
  "filterAndCondition": false,
  "isDirectional": true,
  "roadTypes": [
    "motorway"
  ],
  "speedLimitFilter": {
    "filterMode": "greater",
    "filterValue": 0
  },
  "zones": [
    {
      "code": "32003",
      "iso_3166_2": "US-NV",
      "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.