queryType: getRoadSegments*

The getRoadSegments queryType is passed to the API to get information about road segments.

Note:

See Special Case APIs for more information.

This API call will return a consolidated set of road segments that fall within any of the geospatial inputs i.e. zone, coordinates and/or ways. It will also pass information like the SegmentId, which can be used in other API calls.

Parameters

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

ParameterDescriptionTypeDefined Value SetValue Req'd
queryTypeMust equal getRoadSegments.STRINGgetRoadSegmentsY
asOfDate

The date for which OSM base map version to use. This date must be reflective of the first day of the last month in the date range for which you plan to use any segments returned by this API. The value should be provided in YYYY-MM-DD string format.

STRING-Y
coordinates

Array of objects representing longitude/latitude points to be used as a reference for identifying road segments. Each object contains:

  • Longitude (float) - the longitude value for the point.
  • Latitude (float) - the latitude value for the point.

    This parameter requires a radius value to define the zone within the given radius of the coordinates.

ARRAY-N
excludeServiceRoadsTrue to exclude service roads, false to include them. Defaults to trueBOOLEAN-N
isMetricTrue for data to be returned in metric units, false for imperial.BOOLEANtrue or falseY
radius

The radius distance (kilometers or miles) to apply to input coordinates to get the radius of interest for road segments.

This value is required if coordinates have been input. The default value is 0 or no radius.

FLOAT64-N
roadTypesArray of strings representing the different road types for which you want data. Passing an empty array will return all road types.ARRAYList of OSM road types. Any value from the “Road Types” column found in the Data Dictionary.N
waysArray of integers representing way Ids for which you want data.ARRAY-N
zones

An array of objects representing the zones for which you want information. Each object contains:

  • ZoneId (string) – A custom zone ID, a segment 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, segments or related roads and can be set to null.
  • ZoneType (string) – the type of zone.
ARRAYZoneType - “Custom”, “Segment”, “State”, “County”, “City”, “TAZ”, “ZIP”, “CTR”, or “FSA”N

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
AsOfDateThe date as of which the map snapshot was created for OSM.DATE-
CardinalDirectionStartingAtNodeFromCardinal direction in the direction of NodeFrom to NodeTo. (Direction = 1).STRING-
CardinalDirectionStartingAtNodeToCardinal direction in the direction of NodeTo to NodeFrom. (Direction = -1).STRING-
CountryThe name of the country.STRING-
CountyThe name of the county.STRING-
CountyIdThe county id. A County id is a unique identifier for a county; typically, the FIPS code or Canadian census subdivision CSDUID from StatCan.STRING-
GeographyA GeoJSON string representing the geography of the returned data.STRING-
ISO_3166_2The ISO 3166:2 code of the state.STRING-
ISO_A3ISO-A3 code for the country.STRING-
IsOneWayIndicates if the road is one-way. True indicates the road is one way, false indicates the road is not one way.BOOLEANTrue or False
NodeFromOSM NodeId of the start point of the segment.INTEGER-
NodeToOSM NodeId of the end point of the segment.INTEGER-
ReferenceDateThe most recent change set applied to OSM (generally, this is one to three weeks behind the AsOfDate).DATE-
RoadTypeOSM road type.STRINGRefer to OSM Road Mapping in the Data Dictionary.
SegmentIdSegment Id (also known as a Geotab segment ID that results from breaking down OSM ways into smaller road segments) or unique identifier for the segment.STRING-
SegmentIndexThe order of the segment, starting at 0, inside the OSM way.INTEGER-
SegmentNameRoad name, if available.STRING-
WayIdWay Id (a collection of nodes defined by OpenStreetMap).INTEGER-

Sample parameters


{
"asOfDate": "2023-10-01",
"excludeServiceRoads":true,
"queryType":"getRoadSegments",
"roadTypes":["motorway"],
"zones":[{
    "ZoneId":"32003", 
    "ISO_3166_2":"US-NV", 
    "ZoneType":"County"
	}]
}