ups

UPS Tracking API - how to interpret local times in tracking detail response


The UPS Tracking API documentation doesn't have any explanation of how to interpret local dates and times of the tracking detail responses for the new json API.

In the UPS legacy XML tracking API (https://onlinetools.ups.com/ups.app/xml/Track) response, each activity had the local date and time, and also the GMT time and offsets, for example:

  <Activity>
    <ActivityLocation>
      <Address>
        <City>DUNLAP</City>
        <StateProvinceCode>TN</StateProvinceCode>
        <PostalCode>37327</PostalCode>
        <CountryCode>US</CountryCode>
      </Address>
      <Code>MN</Code>
      <Description>Side Door</Description>
      </ActivityLocation>
    <Date>20231130</Date>
    <Time>164340</Time>
    <GMTDate>2023-11-30</GMTDate>
    <GMTTime>21:43:40</GMTTime>
    <GMTOffset>-05:00</GMTOffset>
  </Activity>

In the new tracking API (https://onlinetools.ups.com/api/track/v1/details/{tracking-no}) response, only the local date and time is given:

  {
    "location": {
      "address": {
        "city": "DUNLAP",
        "stateProvince": "TN",
        "countryCode": "US",
        "country": "US"
      },
      "slic": "3740"
    },
    "status": {
      "type": "D",
      "description": "DELIVERED ",
      "code": "FS",
      "statusCode": "011"
    },
    "date": "20231130",
    "time": "164340"
  }

QUESTION: How should we calculate the time zone of the activity date and time in the response json? Options:

  1. Use the time zone of the city and state specified in activity.location.address
  2. Use the package origin address

Has anyone figured out the rule for determining the activity time zone?


Solution

  • The response documentation makes reference to the gmtOffset field which should be present (and is akin to the GMTOffset XML element).

    I've checked, however, and this field is missing in all responses I've checked. Thankfully, I'm a UPS customer and we've got cases raised with the relevant teams now and I'll update my answer here if/when I get this sorted.