queryType: getContainedZones*
The getContainedZones queryType is passed through the API to get information about all the requested zone types contained wholly within the input zones, with an applied buffer if provided.
The output of this API can serve as the input into zones input parameters across the Altitude platform.
Parameters
| Parameter | Description | Type | Defined Value Set | Value Req’d |
|---|---|---|---|---|
| queryType | Must equal getContainedZones. | STRING | getContainedZones | Y |
| asOfDate | The date for which OSM base map version to use. This parameter is required if you have included Segment or RelatedRoad in requestZoneTypes. This date should be reflective of the first day of the last month in the date range for which you plan to use any zones returned by this API. The value should be provided in YYYY-MM-DD string format. The default value is the latest basemap. | STRING | - | N |
| buffer | The buffer distance (kilometers or miles) to apply as a buffer around the input zone(s). The default value is 0 or no buffer. | FLOAT | - | 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. This filter is only applied if you have included “Custom” in requestZoneTypes. | ARRAY | - | N |
| excludeServiceRoads | True to exclude service roads, false to include them. Defaults to true | BOOLEAN | - | N |
| isMetric | True if the buffer value provided isMetric (kilometers), false if it is imperial (miles). | BOOLEAN | true or false | Y |
| relatedRoadTypes | Array of strings representing the different related road types to return related road metadata for. Empty array means all related road types. This filter is only applied if you have included “RelatedRoad” in requestZoneTypes. | ARRAY | See the list of OSM road types. Any value from the “Backend Value” column found here excluding “tertiary”, “residential_link”, and “living_street” which are all included under “residential” | N |
| requestZoneTypes | An array of strings representing the different zone types you would like to get returned if they are wholly contained within input zones. | ARRAY | “State”, ”County”, ”City”, ”CTR”, ”ZIP”, “TAZ”, “FSA”, “Custom”, “Segment”, “RelatedRoad” | Y |
| roadTypes | Array of strings representing the different road types to return segment zone metadata for. This filter is only applied if you have included “Segment” in requestZoneTypes. Empty array means all road types. | ARRAY | See the list of OSM road types. Any value from the “Backend Value” column found here. | N |
| zones |
An array of objects representing the zones for which you want information. Each object contains:
| ARRAY | ZoneType - “Custom”, “Segment”, ”RelatedRoad”, “State”, “County”, “City”, “TAZ”, “ZIP”, “CTR”, or “FSA” | Y |
Responses
| Code | Type | Description |
|---|---|---|
| 200 | JSON | The requested data. |
| 401 | JSON | Occurs for various unauthorized tasks, such as not providing credentials in your parameters. |
| 500 | JSON | Occurs if an internal server error occurs. Contact altitudesupport@geotab.com if this occurs. |
Response Schema
| Attribute | Description | Data Type | Defined Value Set |
|---|---|---|---|
| InputZoneId | Identifies the zone ID of the passed in zone. | STRING | - |
| Input_ISO_3166_2 | The ISO 3166:2 code of the passed in zone. | STRING | - |
| InputZoneDescription |
Description of the passed in zone when available. Zone description source values based on zone type:
| STRING | - |
| InputZoneType | The zone type of the passed in zone. | STRING | “State”, ”County”, ”City”, ”CTR”, ”ZIP”, “TAZ”, “FSA”, “Custom”, “Segment”, “RelatedRoad” |
| ISO_3166_2 | The ISO 3166:2 code of the contained zone. | STRING | - |
| IsPurchased | True if the contained zone is within a purchased county, false if it is not in a purchased county. | BOOLEAN | true or false |
| ZoneDescription |
Description of the contained zone when available. Zone description source values based on zone type:
| STRING | - |
| ZoneId | Identifies the zone ID of the contained zone. | STRING | - |
| ZoneSubType |
The subtype value of a zone where available. Zone sub type source values based on zone type:
| STRING | - |
| ZoneType | The zone type of the contained zone. | STRING | “State”, ”County”, ”City”, ”CTR”, ”ZIP”, “TAZ”, “FSA”, “Custom”, “Segment”, “RelatedRoad” |
Sample parameters
{
"isMetric":false,
"requestZoneTypes":["County"],
"queryType":"getContainedZones",
"zones":[{
"ZoneId":"US-NV",
"ISO_3166_2":"US-NV",
"ZoneType":"State"
}]
}