Route

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

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

 

Items

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.

If the field is required, it is being specified only for an input request body on a PUT or a POST, for example. GET returns a read-only field.

 

Field Type Description Valid Sample Values
address
Container Wrapper for the address fields. Required. -
streetAddress
String The physical street address where the shipment will be picked up or delivered. Usually line 1 of the mailing address. "100 Main Avenue"
alternateStreetAddress
String Additional origin or destination information such as building, suite, unit. "Bldg 8, Suite 100"
majorMunicipality
String The main city, metropolis, or large town where the shipment will be picked up or delivered. Required with stateProvince when postalCode or latitude and longitude are not provided. "Centerville"
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. "90210"
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. "FL"
stateProvinceLabel
String The localized name of the state or province. "Florida" or "California" or "Texas"
country
String The alpha-2 country code where the shipment will be picked up or delivered. Required. "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) | "BusinessWithLoadingDockOrForklift" or "Entreprise (avec quai ou chariot élévateur)"
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 Wrapper for the arrival or delivery fields. Required. -
label
String

The localized description of the pick up or delivery date or date range.

If the "Flexible" label returns in a listing, it will look like this:

"timeFrame": {
  "label": "Flexible",
  "shortLabel": "Flexible",
  "timeFrameType": {
    "value": "none",
    "label": "Flexible",
    "shortLabel": "Flexible"
  }
}

"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 JSON 


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

{
  "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"
        }
      }
    ]
  }
}