Shared API Members
Contents
Shared API members are objects used in several API calls. The structure that is shared is the same for each API request and response.
StopLocation
The StopLocation structure is used to pass all data associated with a geographic location. It can contain either an address or geographic coordinates. Either the address element is sent or the coords element is specified. Only one is required and specifying both will result in an error. The StopLocation extends the Location class.
Element | Definition | Required | ||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Address | A system object of the Address. Gets or sets the address information for the location.
Usage:
| Yes (if not sending coords) | ||||||||||||||||
Coords | A system object of type Coordinates. Gets or sets the geographic coordinates for the location.
Usage:
| Yes (if not sending Address) | ||||||||||||||||
Costs | A system object of type StopCost. Gets or sets the cost associated with this stop.
Usage:
| No | ||||||||||||||||
Label | A string value. Gets or sets a string which represents a label to be displayed on maps and in reports in association with a stop.
Usage:
| No | ||||||||||||||||
PlaceName | A string value. Gets or sets the place name which corresponds to a custom place; this would supersede standard address entries for geocoding or identify a custom place to be associated with the address. Available for premium account types only.
Usage:
| No | ||||||||||||||||
Region | An enumeration of DataRegion. Gets or sets the Region that the location is in.
Usage:
| Yes | ||||||||||||||||
SideOfStreetAdherence |
An enumeration value. How strict to be in order to avoid the destination being on the opposite side of the street.
| No | ||||||||||||||||
ID | A string value. Gets or sets the ID for the stop.
Usage:
| No |
Location
The Location structure represents a real world location made up of an address, latitude/longitude coordinates, or both. It is inherited by StopLocation.
Element | Definition | Required |
---|---|---|
Address | A system object of the Address. Gets or sets the address information for the location.
Usage:
| Yes (if not sending coords) |
Coords | A system object of type Coordinates. Gets or sets the geographic coordinates for the location.
Usage:
| Yes (if not sending Address) |
Label | A string value. Gets or sets a string which represents a label to be displayed on maps and in reports in association with a stop.
Usage:
| Yes |
PlaceName | A string value. Gets or sets the place name which responds to a custom place; this would supersede standard address entries for geocoding or identify a custom place to be associated with the address. Available for premium account types only.
Usage:
| No |
Region | An enumeration of DataRegion. Gets or sets the Region that the location is in.
Usage:
| Yes |
Address
The Address structure represents a street address with support for Standard Point Location Codes (SPLC).
Element | Definition | Required | ||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
AbbreviationFormat | An enumeration of CountryAbbreviationType. Gets or sets the AbbreviationFormat. The default setting is FIPS.
Usage:
| No | ||||||||||||||||||
City | A string value. Gets or sets the city
Usage:
| Yes (when sending state) | ||||||||||||||||||
Country | A string value. Gets or sets the country.
Usage:
| No | ||||||||||||||||||
CountryPostalFilter | An enumeration of PosCodeType. Gets or sets the postal code country filter. This can be used to filter the postal code by country within North America.
Usage:
| No | ||||||||||||||||||
County | A string value. Gets or sets the county or jurisdiction. Used in conjunction with City/State
Usage:
| No | ||||||||||||||||||
SPLC | A string value. Gets or sets the Standard Point Location Code.
Usage:
| No | ||||||||||||||||||
State | A string value. Gets or sets the state or country name if the Region is outside of the North America.
Usage:
| Yes (When city specified) | ||||||||||||||||||
StreetAddress | A string value. Gets or sets the house number and/or street name. Premium accounts only have street-level routing.
Usage:
| No |
Region
Represents the Region the location is in.
Member Name | Value | Description |
---|---|---|
AF | 1 | Indicates Africa |
AS | 2 | Indicates Asia |
EU | 3 | Indicates Europe |
NA | 4 | Indicates North America |
OC | 5 | Indicates the Australian continent |
SA | 6 | Indicates South America |
ME | 7 | Indicates Middle East |
Coords
Represents geographic coordinates, i.e. latitude and longitude.
Element | Definition | Required |
---|---|---|
Lat
| Gets or sets the latitude in decimal degrees or decimal degrees as a string. Usage:Lat = “34.079799”; | Y(When sending coords) |
Lon
| Gets or sets the longitude in decimal degrees or decimal degrees as a string Usage:Lon = “-118.412935”; | Y(When sending coords) |
StopCosts
The StopCosts structure is used to pass all data associated with any additional costs incurred by stopping at a location. This structure is referenced as part of the StopLocation structure.
Element | Definition | Required |
---|---|---|
CostOfStop
| A double value. Gets or sets the cost of the stop(in dollars). Usage:CostOfStop = 10.5; | N |
HoursPerStop
| A double value. Gets or sets a length of time allocated for this stop. The format is in decimal hours. Usage:HoursPerStop = 2.5; | N |
Loaded
| A boolean value. Gets or sets a value indicating whether the truck is loaded. Usage:Loaded = true; | N |
OnDuty
| A boolean value. Gets or sets a value indicating whether the truck is on duty. Usage:onDuty = true; | N |
UseOrigin
| A boolean value. Gets or sets a value indicating whether to default all the settings to those associated with the route origin. Usage:UseOrigin = true; | N |
ReportOptions
The ReportOptions structure is used to create route reports.
Element | Definition | Required | |||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
EstimatedTimeOptions | A system object of type EstimatedTimeOptions. Gets or sets the estimated time options.
Usage:EstimatedTimeOptions timeOpts = new EstimatedTimeOptions() { DateAndTime = dateAndTime, DateOption = DateOption.Specific, DateOptionSpecified = true, ETAETD = ETAETDType.Arrival, ETAETDSpecified = true }; | No | |||||||||||||||||||||
ExchangeRate | A double value. Gets or sets the change rate to convert US dollars to Canadian dollars.
Usage:ExchangeRate = 1.5; | No | |||||||||||||||||||||
FuelUnits | An enumeration of VolumeUnits. Gets or sets the fuel units to gallons(default) or liters.
Values:
Usage:FuelUnits = VolumeUnits.Gallons; | No | |||||||||||||||||||||
IncludeFerryDistance | A boolean value. Gets or sets a value indicating whether or not miles traveled on ferries are included in mileage calculation. The default is true.
Usage:IncludeFerryDistance=false | No | |||||||||||||||||||||
Language | An enumeration of Language Type. Gets or sets the language in which the information is to be displayed. The default is ENUS for English United States.
Values:
Usage:Language = LanguageType.DE; | No | |||||||||||||||||||||
RouteCosts | A system object of type RouteCosts. Gets or sets the route costs.
Usage:RouteCosts routeCosts = new RouteCosts { CostTimeLoaded = 15, CostTimeLoadedSpecified = true, FuelEconomyEmpty = 1, FuelEconomyEmptySpecified = true, FuelEconomyLoaded = 16, FuelEconomyLoadedSpecified = true, PricePerFuelUnit = 3.95, PricePerFuelUnitSpecified = true, TruckStyle = TruckStyle.FiftyThreeSemiTrailer, TruckStyleSpecified = true }; | No | |||||||||||||||||||||
TimeCosts | An object on the typeTimeCosts. Gets or sets the time costs.
Usage:TimeCosts timeCosts = new TimeCosts() { BorderWait = 5, BorderWaitSpecified = true, BreakInterval = 4, BreakIntervalSpecified = true, BreakLength = 2, BreakLengthSpecified = true }; | No | |||||||||||||||||||||
TollCurrency | An enumeration of TollCurrency. Gets or sets the toll currency, currently US or CDN
Values:
Usage:TollCurrency = Currency.US; | No | |||||||||||||||||||||
TollDiscount | A string value. Gets or sets a string containing the applicable toll discount program. This field is only valid if the user has quarterly toll data privileges and the UseTollData is set to true. Available programs are: 407ETR Transponder, A25 Transponder, BreezeBy,C-Pass, Cruise Card, E-Pass, E-Pass Canada, EXpress Toll, EZ Tag, EZPass, EZPass-NJ, EZPass-WV, FAST LANE, FasTrak, GeauxPass, GO-PASS, Good to Go, I-PASS, I-Zoom, K-TAG, Laredo Trade Tag, Leeway, MACPASS, NC Quick Pass, NEXPRESS TOLL, Palmetto Pass, Peach Pass, PikePass, Quickpass, Smart Tag, StraitPASS, SunPass, TollTag, TxTag, and WabashPass or All.
Usage:TollDiscount = “All”; | No | |||||||||||||||||||||
UseCustomRoadSpeeds | A boolean value. Gets or sets a value indicating whether or not to use custom road speeds.
Usage:Use CustomRoadSpeeds = false; | No | |||||||||||||||||||||
UseTollData | A boolean value. Gets or sets a value indicating whether or not toll data should be used.
Usage:UseTollData=false; | No | |||||||||||||||||||||
UseTraffic | A boolean value. Gets or sets a value indicating whether or not to use traffic data when calculating transit times.
Usage:UseTraffic=true; | No |
EstimatedTimeOptions
EstimatedTimeOptions represents options for generating ETA/ETD in reports.
Element | Definition | Required | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
DateAndTime | A system object of type DateTimeType. Gets or sets the date, time, time of day and time zone information.
Usage:DateTimeType dateAndTime = new DateTimeType() { CalendarDate = "10/10/2014", DayOfWeek =DayOfWeek.Friday, DayOfWeekSpecified = true, TimeOfDay = "12:00", TimeZone = TimeZone.Eastern, TimeZoneSpecified = true }; | No | ||||||||||||
DateOption | An enumeration of DateOption.
Values:
Usage:FuelUnits = VolumeUnits.Gallons; | No | ||||||||||||
ETAETD | An enumeration of ETAETD type.
Values:
Usage:ETAETD = ETAETD.Arrival; | No |
TimeCosts
The TimeCosts structure is used to pass all data associated with additional delays associated with the trip. This structure is part of the RouteOptions structure and is valid for the GetReport functionality.
Element | Definition | Required |
---|---|---|
BorderWait | A float value. Gets or sets the additional amount of time at the border to the overall trip.
Usage:BorderWait=5; | No |
BreakInterval | A float value. Gets or sets the elapsed time of the trip before a break will be taken. The format is in decimal hours.
Usage:BreakInterval = 4; | No |
BreakLength | A float value. Gets or sets the amount of time a break will last. The format is in decimal hours.
Usage:BreakLength = 2; | No |
DepartTime | A TimeOfDay object. Gets or sets the start time of the trip. The format is HH:MM A[P]M. This field is conditional, and valid if the RoutingType is Fastest.
Usage:DepartTime = new TimeOfDay() { AmPm = AmPmType.AM, AmPmSpecified = true, Hour = 10, HourSpecified = true, Minute = 15, MinuteSpecified = true } | No |
RemainingHoursOfService | A float value. Gets or sets the remaining hours of service at the start of the trip before the driver needs to take a break. The format is in decimal hours.
Usage:RemainingHoursOfService = 2; | No |
TimeOfDay
The TimeOfDay structure contains the hour, minute, and AM/PM.
Element | Definition | Required | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
AmPm | An enumeration of AmPmType. Gets or sets the value indicating military, am, or pm.
Values:
Usage:AmPm = AmPmType.AM; | No | ||||||||||||
Hour | An integer value. Gets or sets the hour value.
Usage:Hour = 10; | No | ||||||||||||
Min | An Integer value. Gets or sets the minute value.
Usage:Minute = 30; | No |
RouteCosts
The RouteCosts structure represents route cost information associated with a Route and subclasses such as MapRoute and ReportRoute.
Element | Definition | Required | ||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
CostTimeEmpty | A double value. Gets or sets the estimated labor or other cost per hour when empty.
Usage:CostTimeEmpty = 5.5; | No | ||||||||||||||||
CostTimeLoaded | A double value. Gets or sets the estimated labor or other cost per hour when loaded.
Usage:CostTimeEmpty = 15; | No | ||||||||||||||||
FuelEconomyEmpty | A double value. Gets or sets the fuel efficiency(distance units per volume units) when empty.
Usage:FuelEconomyEmpty = 1; | No | ||||||||||||||||
FuelEconomyLoaded | A double value. Gets or sets the fuel efficiency(distance units per volume units) when loaded.
Usage:FuelEconomyLoaded = 16; | No | ||||||||||||||||
GreenHouseGas | A double value. Gets or sets the greenhouse gas cost in lbs per fuel unit.
Usage:GreenHouseGas = 1; | No | ||||||||||||||||
OtherCostPerDistanceUnitEmpty | A double value. Gets or sets the maintenance cost per mile when empty.
Usage:OtherCostPerDistanceUnitEmpty = 5; | No | ||||||||||||||||
OtherCostPerDistUnitLoaded | A double value. Gets or sets the maintenance cost per distance unit when loaded.
Usage:OtherCostPerDistUnitLoaded = 2; | No | ||||||||||||||||
PricePerFuelUnit | A double value. Gets or sets the price per gallon of fuel.
Usage:PricePerFuelUnit = 3.95; | No | ||||||||||||||||
TruckStyle | An enumeration of TruckStyle. Gets or sets the truck style which includes vehicle dimensions and route costs.
Values:
Usage:TruckStyle = TruckStyle.FiftyThreeSemiTrailer; | No |
Route
The Route structure represents a route and all its associated information from the standpoint of a request for either mapping or reporting.
Element | Definition | Required |
---|---|---|
Options
| A system object. Sets the routing options with the RouteOption class. See RouteOptions. Usage:RouteOptions opts = new RouteOptions(){}; | N |
RouteId
| A string value. Sets the unique route identifier. This may be used to identify routes when reports are created. Usage:routeID = “PhillytoAC”; | N |
Stops
| A list of the StopLocation object. Sets the collection of stops that make up the route. Usage:StopLocation [] stops = new StopLocation[3]; | Y |
AssetId
| A string value. The ID of the asset (device, vehicle or driver) associated with this request. | N |
RouteOptions
The RouteOptions structure represents options specific to the kind of route to be run.
Element | Definition | Required | |||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
BordersOpen | A boolean value. Gets or sets a value indicating whether borders are open for travel. The default is true.
Usage:bordersOpen = true; | No | |||||||||||||||||||||||||||||||||||||||
ClassOverrides | An enumeration of ClassOverrideType. Gets or sets the enumeration of class overrides. This is an optional field and the default is None.
Values:
Usage:ClassOverrides = ServiceRef.ClassOverrideType.FiftyThreeFoot | No | |||||||||||||||||||||||||||||||||||||||
CustomRoadSpeeds |
An array of RoadSpeedBase objects containing custom road speeds per road category in mph. This is an optional field and the default is an empty list.
RoadSpeedBase :
RoadType :
| No | |||||||||||||||||||||||||||||||||||||||
DistanceUnits | An enumeration of DistanceUnits. Gets or sets the distance units to miles(default) or kilometers. The unit of measure to calculate route, and when drawing a map, the scale bar legend will use these distance units.
Values:
Usage:DistanceUnits = ServiceRef.DistanceUnits.Miles; | No | |||||||||||||||||||||||||||||||||||||||
HazMatType | An enumeration of HazMatType. Gets or sets the hazardous material type. See details in Glossary. The default is none.
Values:
Usage:HazMatType = ServiceRef.HazMatType.Caustic; See details in Glossary. | No | |||||||||||||||||||||||||||||||||||||||
HighwayOnly | A boolean value. Gets or sets a value indicating whether to use highways only. Street-level routing is available for premium account only.
Usage:HighwayOnly = true; | No | |||||||||||||||||||||||||||||||||||||||
HubRouting | A boolean value. Gets or sets a value indicating whether or not to enable hub routing. The default is false to disable hub routing.
Usage:HubRouting = true; | No | |||||||||||||||||||||||||||||||||||||||
OverrideRestrict | A boolean value. Gets or sets a value indicating whether or not to override truck restrictions. The default is false to keep the restrictions.
Usage:OverrideRestrict = true; | No | |||||||||||||||||||||||||||||||||||||||
RouteOptimization | An enumeration of RouteOptimizeType. Gets or sets the method by which to optimize the route stops. Default is None
Values:
Usage:RouteOptimization=RouteOptimizeType.DestinationFixed; | No | |||||||||||||||||||||||||||||||||||||||
RoutingType | The type of route you want to calculate. Versions prior to 27 do not support fastest routing, practical will be used if fastest is supplied.
Values:
Usage:RoutingType=RoutingType.Practical; | No | |||||||||||||||||||||||||||||||||||||||
TollDiscourage | A boolean value. Gets or sets a value indicating whether or not tolls should be discouraged on the route. The default is false. This parameter is deprecated. Use TollRoads instead.
Usage:TollDiscourage=true; | N | |||||||||||||||||||||||||||||||||||||||
TollRoads | Indicates whether or not to avoid toll roads when generating a route. If this parameter is specified, the value in TollDiscourage will be ignored. If this parameter is null, the value in TollDiscourage will be used.Values include: 3 (Use) 2 (Avoid if Possible) 1 (Always Avoid) Default is null Usage:TollRoads=2; | N | |||||||||||||||||||||||||||||||||||||||
avoidCountry | A comma-separated list of ISO2 codes for countries that should be avoided when generating a route. Default is an empty list. Available in PCM34 and Later. | No | |||||||||||||||||||||||||||||||||||||||
avoidState | A comma-separated list of ISO2 codes for states that should be avoided when generating a route. Default is an empty list. This parameter is for North America only. Available in PCM34 and Later. | No | |||||||||||||||||||||||||||||||||||||||
favorCountry | A comma-separated list of ISO2 codes for countries that should be favored when generating a route. Default is an empty list. This parameter is for regions outside of North America. Available in PCM34 and Later. | No | |||||||||||||||||||||||||||||||||||||||
favorState | A comma-separated list of ISO2 codes for states that should be favored when generating a route. Default is an empty list. This parameter is for North America only. Available in PCM34 and Later. | No | |||||||||||||||||||||||||||||||||||||||
TruckCfg | A system object. Gets or sets the truck configuration.
Usage:ServiceRef.TruckConfigCfg=new Serv.TruckConfig(){}; | No | |||||||||||||||||||||||||||||||||||||||
UseAvoidsAndFavors | A boolean value. Gets or sets a value indicating whether or not to use avoids and favors. Available for premium account types only.
Usage:UseAvoidFavors=false; | No | |||||||||||||||||||||||||||||||||||||||
VehicleType | An enumeration of vehicleType. Gets or sets the type of the vehicle.
Values:
Usage:VehicleType = ServiceRef.VehicleType.Truck; | No | |||||||||||||||||||||||||||||||||||||||
ElevLimit |
A boolean value. Gets or sets a value indicating elevation limit when generating a route.
Elevation units can be either meters or feet determined by DistanceUnits .
Limit will be ignored if routing is deemed impractical with the limit, or a stop is located at an elevation higher than the limit. Usage:elevLimit = true; | No | |||||||||||||||||||||||||||||||||||||||
FerryDiscourage |
A boolean value. Gets or sets a value indicating Whether or not to avoid ferries while routing. The default is false to disable avoiding ferries.
Usage:FerryDiscourage = true; | No | |||||||||||||||||||||||||||||||||||||||
SideOfStreetAdherence |
An enumeration value. How strict to be in order to avoid the destination being on the opposite side of the street.
| No | |||||||||||||||||||||||||||||||||||||||
GovernorSpeedLimit |
An Integer value. Maximum average road speed to use in route calculations that overrides all other road speeds when they are above this value.
Valid value is between 1 and 100 mph, or 1 and 161kph determined by DistanceUnits .
Usage:GovernorSpeedLimit = 50; | No |
TruckCfg
The Truckcfg structure is used to pass all data associated with the truck configuration (vehicle dimension, weight and number of axles) for routing and tolls.
Element | Definition | Required | |||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Axles | An integer value. Gets or sets the number of axles on the truck. If TrailerConfig.MaxAxles is also set, then the two values must add up to the total axle count of the vehicle. Acceptable values are 2 through 14. The default value is 5.
Usage:Axles = 2; | No | |||||||||
Height |
A string value. Gets or sets the height of the truck in feet and inches, or meters depending upon the units. If TrailerConfig.MaxHeight is also set, then the greater of the two will be used.
Valid range is between 5' and 15' in North America, or between 2 and 5 meters in Europe. The default is 13'6" in all regions except Europe, which is 12'6". Usage:Height = "13'6" | No | |||||||||
LCV | A boolean value. Gets or sets a value indicating whether the truck is a multi-trailer or longer combination vehicle. This is used for calculation of toll costs, and only for North region.
Usage:LCV = true; | No | |||||||||
Length |
A string value. Gets or sets the length of the truck in feet or meters, depending upon the units.
Valid range is between 8' and 70' in North America, or between 5 and 25 meters in Europe. Read more about setting vehicle dimensions. Usage:Length = "53'0"; | No | |||||||||
Units | An enumeration of VehicleDimUnits. Gets or sets the units of measure to be used for the vehicle dimensions.
Values:
Usage:Units = VehicleDimUnits.English; | No | |||||||||
Weight |
A string value. Gets or sets the weight of the truck in pounds or kilos, depending upon units. If TrailerConfig.MaxWeight is also set, then the two values will be added up to determine the total vehicle weight.
Valid range is between 1500 and 156470 lbs in North America, or between 680.39 and 60000 kgs in Europe. The default value is 80,000 pounds for all regions. Usage:Weight = "132000"; | No | |||||||||
Width | A string value. Gets or sets the width of the truck in inches or meters, depending upon units.
Valid range is between 60" and 102" in North America, or between 2 and 3 meters in Europe. Read more about setting vehicle dimensions. Usage:Width = "102\""; | No | |||||||||
MaxWeightPerAxleGroup | A double value. Gets or sets maximum weight per axle group, depending upon units.
Acceptable values are 800 to 45,000 pounds in North America and 1 tonne to 20 tonnes in Europe. Read more about setting vehicle dimensions. Usage:MaxWeightPerAxleGroup = 34000.00 | No |