queryType: getZonesByRadius*

The getZonesByRadius queryType is passed to the API to generate an array of zones that fall within a given radius of the centroid of a central zone.

Note: See Special Case APIs for more information.

Parameters

These parameters should be passed to the functionParameters object regardless of which method you choose to make an API request.

ParameterDescriptionTypeDefined Value SetValue Required
queryTypeMust equal getZonesByRadius.STRINGgetZonesByRadiusY
asOfDate

The date for which OSM base map version to use. The date is in YYYY-MM-DD string format. If not provided will use the most recent month.

Note:

This date is utilized to pull the correct basemap reference when utilizing a segment as your zone; it is recommended you provide input.

STRING-N
customZoneTypes

Array of custom zone type IDs representing the types of custom zones you would like returned. Empty array means all custom zone types.

Note:

This filter is only applied when requestZoneType is “Custom”.

ARRAY-N
excludeServiceRoadsTrue to exclude service roads, false to include them. The default is true.BOOLEAN-N
isMetricTrue if you want the data returned to be metric, false if you want imperial.BOOLEANtrue or falseY
radiusThe length of the radius (kilometers or miles) based on isMetric.FLOATtrue or falseY
requestZoneTypeThe type of zones you want returned.STRING

  • ZoneType - “Segment”

  • “Custom”

  • “State”

  • “County”

  • “City”

  • “TAZ”

  • “ZIP”

  • “CTR”

  • “FSA”.

See Zones for details on how to structure the zone inputs for each zone type.

Y
roadTypes

Array of strings representing the different road types for which you want data. Empty array means all road types.

Note: This filter is only applied when requestZoneType is “Segment”.
ARRAYList of OSM road types. See the Road Types table.N
zones

An object representing the zone reference for returning zones of the requested type:

  • ZoneId (string)– A custom zone ID or a standard zone ID such as county ID, city ID, etc.

  • ISO_3166_2 (string)– The ISO code of the standard zone. Does not apply to custom zones and can be set to null.

  • ZoneType (string)– the type of zone.

ARRAY

  • ZoneType - “Custom”

  • “State”

  • “County”

  • “City”

  • “TAZ”

  • “ZIP”

  • “CTR”

  • “FSA”.

See Zones for details on how to structure the zone inputs for each zone type.

Y

Responses

CodeTypeDescription
200JSONThe requested data.
401JSONOccurs for various unauthorized tasks, such as not providing credentials in your parameters.
500JSONOccurs if an internal server error occurs. Contact altitudesupport@geotab.com if this occurs.

Response Schema

AttributeDescriptionData TypeDefined Value Set
GeographyA GeoJSON string representing the geography of the zone.STRING-
ISO_3166_2The ISO 3166:2 code for the state or province.STRING-
MaxLatitudeMaximum latitude of the zone.FLOAT64-
MaxLongitudeMaximum longitude of the zone.FLOAT64-
MinLatitudeMinimum latitude of the zone.FLOAT64-
MinLongitudeMinimum longitude of the zone.FLOAT64-
ZoneIdThe zone ID for which data is being returned.STRING-
ZoneDescription

Description of the zone when available. The value is based on the type of zone:

  • “State” — state name.

  • “County” — county name.

  • “City” — city name.

  • “CTR” — census tract description.

  • “Custom” — custom zone description, if available.

STRING-
ZoneSubType

The zone type subclassification value, where applicable. This value is based on requestZoneType input parameter value:

  • “Segment” — the road type value for the road segment.

  • “Custom” — string array of all customer zone type Ids associated with the custom zone.

All other values return a null.

STRING-
ZoneTypeThe zone type of the zone.STRING“State”, ”County”, ”City”, ”CTR”, ”ZIP”, “TAZ”, “FSA”, “Custom” and “Segment”

Sample parameters

{
"queryType": "getZonesByRadius",
"isMetric": false,
"radius": 50.0,
"requestZoneType": " CTR ",
"zones": [{
	"ZoneId": "36063",
	"ISO_3166_2": "US-NY",
	"ZoneType": "county"
	}]
}