Start zones by radius job

Creates a zones by radius job. Returns GeoJSON features for all zones within the specified radius of a center point.

Altitude Help Center — getZonesByRadius

Request Body

zones by radius parameters.

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.	N
`customZoneSubTypes`	array<string>	-	-	Custom zone subType IDs to filter results. Empty means all subTypes. Only applied when zoneType is 'Custom'.	N
`excludeServiceRoads`	boolean	-	-	Exclude service roads from results. Defaults to true. Only applied when zoneType is 'Segment'.	N
`isMetric`	boolean	-	-	Return results in metric units. Omit to use the requesting user's stored preference.	N
`radius`	number (double)	-	-	Radius around the center zone centroid in kilometers (isMetric true) or miles (isMetric false).	Y
`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 filter results. Empty means all road types. Only applied when zoneType is 'Segment'.	N
`zoneIds`	array<string>	-	-	Encoded zone ID strings. Provide exactly one of zoneIds or zones (not both).	N
`zoneType`	string	-	-	Type of zones to return (e.g. 'County', 'ZIP', 'Segment', 'Custom').	Y
`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 radius request

Translated from the v1 getZonesByRadius sample.

{
  "isMetric": false,
  "radius": 25,
  "zoneType": "County",
  "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.