Route and Time API Model

The route object exists in listings, shipments, and rate requests models. It contains information for the time and place of important events like pickup and delivery.

Distance Fields

Field	Type	Description	Sample Values
kilometers	Decimal	The number of kilometers traveled for the listing route.	1123.45
label	String	The localized string description of the distance traveled for the listing route.	"698 miles"
shortLabel	String	The localized string for the route distance as shown on a mobile or touch device.	"698 mi."

Item Fields

The array order is preserved.

The origin address is the first item in the route array.
The destination address is the last item in the route array.

Field	Type	Description	Sample Values
address	Container	Required wrapper for the address fields.
streetAddress	String	The physical street address where the shipment will be picked up or delivered.	"200 Henry Road"
alternateStreetAddress	String	Additional detail on address, often the building, unit or suite number.	"Apt 128C"
majorMunicipality	String	The main city or town where the shipment will be picked up or delivered. Required with stateProvince when postalCode or latitude and longitude are not provided.	"Baton Rouge"
postalCode	String	The postal code where the shipment will be picked up or delivered. International postal codes are supported. Required if majorMunicipality and stateProvince or latitude and longitude are not provided.	"70744"
stateProvince	String	The abbreviated state or province where the shipment is picked up or delivered. Required with majorMunicipality when postalCode or latitude and longitude are not provided.	"LA"
stateProvinceLabel	String	The localized name of the state or province.	"Louisiana"
country	String	The required alpha-2 country code where the shipment will be picked up or delivered.	"US"
countryLabel	String	The localized name of the country or nation.	"United States", "États-Unis"
latitude	Decimal	The geographical latitude of the shipment location in decimal degrees. Required with longitude when postalCode or majorMunicipality and stateProvince are not provided.	34.096629
longitude	Decimal	The geographical longitude of the shipment location in decimal degrees. Required with latitude when postalCode or majorMunicipality and stateProvince are not provided.	-118.412426
label	String	The localized name of the location. The city and abbreviated state/province for the latitude and longitude.	"Miami, FL"
shortLabel	String	The localized string for the location name as shown on a mobile or touch device. When a location is geocoded, the city or major municipality and state or province abbreviation is returned. This field is intended for mobile application and mobile responsive consumers.	"Miami, FL"
type	String	The kind of pick up or delivery address. See Address Types.	"Residence" or "Domicile" (localized label)
timeZone	String	Time zone for the shipment. When this field is provided or specified in the input JSON body, the API uses the field value as the time zone of the pick up or delivery address. If the value that is provided is not the correct time zone for the pick up or delivery address, the API calculates the correct time zone and that value overrides what is provided. When this field is not specified, the API calculates the time zone of the shipment based on the pick up or delivery address.	"America/Chicago", "America/Los_Angeles"
timeFrame	Container	Required wrapper for the arrival or delivery fields.
label	String	The localized description of the pick up or delivery date or date range.	"Before 8/5/2012", "On 7/17/2014" "Avant le 25/01/2013" "Entre le 04/02/2013 - 14/02/2013
shortLabel	String	The localized description of the pick up or delivery date or date range as shown on a mobile or touch device.	"Before 8/5", "7/17" \| "Avant le 25/01" \| "04/02 - 14/02"
earliestArrival	String	The earliest date the pick up or delivery date can occur. Use "YYYY/MM/DD" for the input format. Also valid: YYYY-MM-DD or MM/DD/YYYY	"2014/10/10" as input and can return more specifically as "2014-10-10T00:00:00"
latestArrival	String	The latest date the pick up or delivery date can occur. Use "YYYY/MM/DD" for the input format. Also valid: YYYY-MM-DD or MM/DD/YYYY	"2014/10/20" as input and can return more specifically as "2014-10-20T00:00:00
timeFrameType	String	The time frame type value to specify. Valid Options: "after", "before", "between", and "on" where you must specify the date range for "between". When using "on" the earliest and latest arrival dates must match exactly. If this field returns, it is a container wrapper for the data trio, the value, label, and shortLabel. Example GET /v2/listings/ value: "on", label: "On", shortLabel: "On"	"on", "between", "after", "flexible"

Sample Request

Depending on the resource accessed, the "route" wrapper may not be used. Terminal information only available when provided.

JSON
    
 
{  "route": {    "items": [      {        "address": {          "streetAddress": "100 Avenue A",          "alternateStreetAddress": "Bldg 2, Suite 100",          "majorMunicipality": "Tampa",          "postalCode": "33623",          "stateProvince": "FL",          "country": "US",          "latitude": 28.056858,          "longitude": -82.605871,          "type": "Residence",          "timeZone": "America/New_York"        },        "timeFrame": {          "earliestArrival": "2014-11-01T00:00:00Z",          "latestArrival": "2014-11-01T00:00:00Z",          "timeFrameType": "on"        },        "terminal": {          "phoneNumber": "9876543210",          "city": "Tampa",          "state": "FL",          "postalCode": "33623"        }      },      {        "address": {          "postalCode": "78741",          "country": "US",          "type": "Residence"        },        "timeFrame": {          "earliestArrival": "2014-11-11T00:00:00Z",          "latestArrival": "2014-11-21T00:00:00Z",          "timeFrameType": "between"        },        "terminal": {          "phoneNumber": "1234567890",          "city": "Austin",          "state": "TX",          "postalCode": "78704"        }      }    ]  }}
Copy

Additional detail on time frame model

While "earliestArrival", "latestArrival" and "between" are the typical parameters for the time frame model, uShip can support other configurations. Please see the table below for more information on Before, On, and Relative time frames.

Field	Type	Description
date1	String	Required. The “date1” is an origin or from value that must always be less than the “date2” value.
date2	String	Required. if supplied as a destination or range value. If specified with the timeFrametype "On", the dates must match exactly.
delay	Integer	Required.when passing in the "timeFrameType" as Relative. The number of days before or after booking/pickup.
timeFrameType	String	Required. The supported values are: `Before` - The pick up or delivery will be made before a specified time frame. `between` - The pick up or delivery will be made between specified time frames. `On` - The pick up or delivery will be made on a specified date. `Relative` - The pick up or delivery will be a specified number of days before or after a specified time frame.

Last updated on