Start road segments job

Creates a road segments job. Provide at least one of zones/zoneIds, coordinates with a positive radius, or ways. These selectors are additive: the result is the union of segments matched by any supplied selector. The zones and zoneIds alternatives are mutually exclusive. Results are GeoJSON features with segment metadata such as road name, road type, and speed limit.

Altitude Help Center — getRoadSegments

Request Body

Road segment query parameters. Zone, coordinate, and way selectors may be combined; results are their union.

application/json: object

Name	Type	Input Shape	Values	Description	Value Required
`asOfDate`	string	-	-	OSM basemap version date in YYYY-MM-DD format. Omit to use the most recent month.	Y
`coordinates`	array<object>	latitude: number (double); longitude: number (double)	-	WGS-84 coordinate pairs near which to find road segments. Results are the union of all supplied selectors (zones/zoneIds, coordinates, ways). At least one selector is required.	N
`excludeServiceRoads`	boolean	-	-	When true, service road categories are excluded from results.	N
`isMetric`	boolean	-	-	When true, lengths are returned in kilometres; when false, in miles. Defaults to the isMetric setting on the authenticated user's profile when omitted.	N
`radius`	number (double)	-	-	Search radius around the provided coordinates in metres. Required and must be greater than zero when coordinates are provided, including when coordinates are combined with zones or ways.	N
`roadTypes`	array<RoadType>	-	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. An empty array returns segments for all road types.	N
`ways`	array<integer (int64)>	-	-	OSM way IDs to look up directly. Selectors are additive: results are the union of segments matched by zones, coordinates, and ways. At least one selector is required.	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	-	Zone objects with code, type, and iso_3166_2. Provide exactly one of zones or zoneIds (not both).	N

Examples

County road segments request

Translated from the v1 getRoadSegments sample.

{
  "asOfDate": "2025-01-01",
  "excludeServiceRoads": true,
  "isMetric": false,
  "roadTypes": [
    "motorway"
  ],
  "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.