Shipment Tracking Event

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/usps/json-schema/usps-shipment-tracking-schema.json",
  "title": "Shipment Tracking Event",
  "description": "Details about a shipment tracking event, including location, status, and facility information.",
  "x-generated": "2026-11-11",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/usps-logistics-shipments-openapi.yml#/components/schemas/ShipmentTracking",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "externalLoadNumber",
    "appointmentID",
    "appointmentDate",
    "trailerID",
    "schedulerCRID",
    "location",
    "currentLocation",
    "currentEvent",
    "positionalInfo"
  ],
  "properties": {
    "externalLoadNumber": {
      "type": "string",
      "description": "Unique identifier for the shipment load.",
      "minLength": 1,
      "maxLength": 50,
      "pattern": "^[A-Z0-9]+$"
    },
    "appointmentID": {
      "type": "string",
      "description": "Appointment ID assigned from FAST.",
      "minLength": 1,
      "maxLength": 12,
      "pattern": "^[A-Za-z0-9]{1,12}$"
    },
    "appointmentDate": {
      "type": "string",
      "format": "date-time",
      "description": "Date and time of the appointment (ISO 8601).",
      "minLength": 20,
      "maxLength": 30
    },
    "trailerID": {
      "type": "string",
      "description": "Unique identifier for the trailer.",
      "minLength": 1,
      "maxLength": 20,
      "pattern": "^[A-Z0-9]+$"
    },
    "schedulerCRID": {
      "type": "string",
      "description": "Scheduler's unique identifier.",
      "minLength": 1,
      "maxLength": 20,
      "pattern": "^[0-9]+$"
    },
    "ETA": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "description": "Estimated time of arrival (ISO 8601). Required unless currentEvent.eventType is FACILITY_ARRIVE or FACILITY_DEPART.",
      "minLength": 20,
      "maxLength": 30
    },
    "ETAStatus": {
      "type": [
        "string",
        "null"
      ],
      "description": "The ETA status of the current destination and not the appointment. Required unless currentEvent.eventType is FACILITY_ARRIVE or FACILITY_DEPART.",
      "minLength": 4,
      "maxLength": 12,
      "enum": [
        "ON_TIME",
        "EARLY",
        "DELAYED",
        "LATE",
        "CANCELLED",
        "REDIRECTED",
        "RESCHEDULED"
      ]
    },
    "location": {
      "$ref": "#/$defs/TrackingLocation"
    },
    "currentLocation": {
      "$ref": "#/$defs/TrackingCurrentLocation"
    },
    "currentEvent": {
      "$ref": "#/$defs/TrackingCurrentEvent"
    },
    "positionalInfo": {
      "$ref": "#/$defs/TrackingPositionalInfo"
    },
    "resourceInfo": {
      "$ref": "#/$defs/TrackingResourceInfo"
    }
  },
  "$defs": {
    "TrackingCurrentEvent": {
      "type": "object",
      "description": "The current event type for the shipment.",
      "additionalProperties": false,
      "required": [
        "eventType"
      ],
      "properties": {
        "eventType": {
          "type": "string",
          "description": "The type of event.",
          "minLength": 7,
          "maxLength": 15,
          "enum": [
            "EN_ROUTE",
            "PRE_ARRIVAL",
            "FACILITY_ARRIVE",
            "FACILITY_DEPART"
          ]
        }
      }
    },
    "TrackingCurrentLocation": {
      "type": "object",
      "description": "Current location details for the tracking event.",
      "additionalProperties": false,
      "required": [
        "latitude",
        "longitude",
        "currentDateTime"
      ],
      "properties": {
        "latitude": {
          "type": "number",
          "description": "Latitude of the current location.",
          "minimum": -90,
          "maximum": 90
        },
        "longitude": {
          "type": "number",
          "description": "Longitude of the current location.",
          "minimum": -180,
          "maximum": 180
        },
        "currentDateTime": {
          "type": "string",
          "format": "date-time",
          "description": "Timestamp of the current location.",
          "minLength": 20,
          "maxLength": 30
        }
      }
    },
    "TrackingLocation": {
      "type": "object",
      "description": "Location details for the tracking event.",
      "additionalProperties": false,
      "required": [
        "locationType",
        "stopType",
        "stopSequence"
      ],
      "properties": {
        "locationType": {
          "type": "string",
          "description": "Type of location (e.g., USPS, CUSTOMER, NON_USPS).",
          "minLength": 1,
          "maxLength": 15,
          "enum": [
            "USPS",
            "CUSTOMER",
            "NON_USPS"
          ]
        },
        "dropSiteKey": {
          "type": "string",
          "description": "Key for the drop site. Required when locationType is USPS.",
          "minLength": 1,
          "maxLength": 15,
          "pattern": "^[A-Z0-9]+$"
        },
        "ZIPCode5": {
          "type": "string",
          "description": "Five-digit ZIP Code. Required when locationType is CUSTOMER or NON_USPS.",
          "minLength": 5,
          "maxLength": 5,
          "pattern": "^[0-9]{5}$"
        },
        "stopType": {
          "type": "string",
          "description": "Type of stop (Pickup or Delivery).",
          "minLength": 6,
          "maxLength": 8,
          "enum": [
            "PICKUP",
            "DELIVERY"
          ]
        },
        "stopSequence": {
          "type": "integer",
          "description": "The actual stop number in the route.",
          "minimum": 1,
          "maximum": 100
        }
      }
    },
    "TrackingPositionalInfo": {
      "type": "object",
      "description": "Positional information for the shipment.",
      "additionalProperties": false,
      "required": [
        "pingInterval",
        "distance",
        "speed",
        "accuracy"
      ],
      "properties": {
        "pingInterval": {
          "type": "integer",
          "description": "Interval in milliseconds between location pings.",
          "minimum": 0,
          "maximum": 10000
        },
        "distance": {
          "type": "number",
          "description": "Distance traveled in kilometers.",
          "minimum": 0,
          "maximum": 10000
        },
        "speed": {
          "type": [
            "number",
            "null"
          ],
          "description": "Velocity of the device in meters per second.",
          "minimum": 0,
          "maximum": 155
        },
        "accuracy": {
          "type": [
            "number",
            "null"
          ],
          "description": "Accuracy of the coordinates in meters.",
          "minimum": 0,
          "maximum": 1000
        }
      }
    },
    "TrackingResourceInfo": {
      "type": "object",
      "description": "Information about the resource sending the information.",
      "additionalProperties": false,
      "properties": {
        "submissionType": {
          "type": "string",
          "description": "Type of submission.",
          "enum": [
            "MANUAL",
            "AUTOMATIC"
          ],
          "default": "AUTOMATIC",
          "minLength": 6,
          "maxLength": 9
        },
        "submissionBy": {
          "type": "string",
          "description": "Who submitted the information.",
          "enum": [
            "CUSTOMER",
            "DRIVER"
          ],
          "default": "CUSTOMER",
          "minLength": 6,
          "maxLength": 8
        },
        "comments": {
          "type": "string",
          "description": "Comments related to the submission.",
          "pattern": "^[A-Za-z0-9\\s\\-\\.,]+$",
          "minLength": 1,
          "maxLength": 256
        },
        "rating": {
          "type": "number",
          "description": "Rating (0-5).",
          "minimum": 0,
          "maximum": 5
        },
        "locationPermission": {
          "type": "string",
          "description": "Permission of location services status.",
          "enum": [
            "GRANTED",
            "DENIED",
            "NOT_REQUIRED"
          ],
          "minLength": 6,
          "maxLength": 12
        },
        "notificationPermission": {
          "type": "string",
          "description": "Permission of notification services status.",
          "enum": [
            "GRANTED",
            "DENIED",
            "NOT_REQUIRED"
          ],
          "minLength": 6,
          "maxLength": 12
        }
      }
    }
  }
}