About this Repo

This repository contains json files that programatically describe how to detect, validate, and decode the following types of tracking numbers:

Supported Tracking Numbers

Carrier / Type	Length	Example	Data
UPS	18	1Z5R89390357567127	SerialNumberCheckDigitShipperIdServiceTypePackageId
Multiple / S10 International Standard	13	RB123456785GB	SerialNumberCheckDigitCountryCodeServiceType
FedEx / Ground 15	15	0414 4176 0228 964	SerialNumberCheckDigit
FedEx / Ground (SSCC 18)	18	00 0123 4500 0000 0027	SerialNumberCheckDigitShippingContainerType
FedEx / Ground (96)	22	9611020987654312345672	SerialNumberCheckDigitApplicationIdentifierSCNCServiceTypeShipperIDPackageId
Fedex / Ground (GSN)	34	9622 0015 6 000 123 4567 1 00 7948 0839 0594	SerialNumberCheckDigitApplicationIdentifierSCNCGSN
FedEx / Express 12	12	986578788855	SerialNumberCheckDigit
FedEx / Express Saver	34	1001921334250001000300779017972697	SerialNumberCheckDigitDestinationZip
FedEx / SmartPost	22	61299998820821171811	ApplicationIdentifier``SerialNumber, CheckDigit, ServiceType, ShipperId, PackageId
USPS 20	20	0307 1790 0005 2348 3741	SerialNumberCheckDigitServiceTypeMailerIdPackageId
USPS 91	25-34	420 2215391010268373310000395219361 2898 7870 0317 6337 957196 9010 7560 0307 7385	SerialNumberCheckDigitRoutingApplicationIdDestinationZipSCNCServiceTypeShipperIdPackageId
OnTrac	15	C11031500001879	SerialNumberCheckDigit
DHL Express	10	3318810025	SerialNumberCheckDigit
DHL Express Air	10	73891051146	SerialNumberCheckDigit
Amazon Logistics	15	TBA 487064622 000	SerialNumber

JSON Format

• couriers/*.json - identifies the standard couriers that might send mail

  • Each courier is defined by json hash with the following keys

    • name - Identifies the courier
    • courier_code - short code to identify the courier. Alphanumeric only, no spaces.
    • tracking_numbers - an array of possible tracking number formats for this courier

  • Each tracking number type is defined by a json hash with the following keys:

    • name - A name to identify this type of tracking number. Usually includes the carrier in the name, i.e. FedExGround

    • regex - A pcre compatible regular expression that identifies the tracking number regardless of spaces in-between characters.

      Every regex must contain the named groups SerialNumber and CheckDigit and depending on the tracking number can optionally contain the following common attributes:

      • ServiceType: indicating the type of delivery service
      • ShipperId: indicating the shipper id
      • PackageId: indicating the package id
      • DestinationZip: indicating the destination zip code

    • validation - Specifies how the tracking number is validated

      • checksum: if the tracking number has a checksum, include a checksum key with the details.
        • name: specifies the algorithm. Supported algorithms and parameters are mod10, mod7, s10, and sum_product_with_weightings_and_modulo. Look at existing examples for parameters.

        "validation": {
        "checksum": {
        "name": "mod10",
        "evens_multiplier": 1,
        "odds_multiplier": 2
        }
        }

      • serial_number_format: some tracking numbers require some modification of the group before validation. In the example below, the serial number needs a "91" prepended before validation unless the number starts with a 91, 92, 93, 94, or 95

      "serial_number_format": {
      "prepend_if": {
      "matches_regex": "^(?!9[1-5]).+",
      "content": "91"
      }
      }```

    • tracking_url - A url that we can use to find the tracking history for a particular tracking number. It assumes the tracking number can be entered using python style string formatting "www.courier.com?trackingnumber=%s".

    • test_numbers:

      • valid: an array of valid tracking numbers for testing
      • invalid: an array of invalid tracking numbers for testing

    • additional - (optional) further information relating to a named regex group can be specified. For instance, a lookup table for the ServiceType regex group, relating the two digit letter code with the type of service.

    "additional": [
    {
    "name": "Service Type",
    "regex_group_name": "ServiceType",
    "lookup": [
    {
    "matches": "01",
    "name": "UPS United States Next Day Air (Red)"
    },
    {
    "matches": "02",
    "name": "UPS United States Second Day Air (Blue)"
    }
    ]
    }
    ]

    Each hash in the lookup array should contain a key called matches or matces_regex, specifying how the value of regex_group_name should be compared.

Standard implementations of

• Check digit algorithms
• Serial number parsers

Using this repo:

List of Libraries using this repository, by Language

We suggest you check these out before rolling your own implementation.

Java:

• MysteryTrackingNumber Ruby:
• tracking_number

I am creating a new library

If you are using this repo, it is most likely because you are writing a library to get information out of tracking numbers.

1. Please check that your chosen programming language does not already have an implementation of a tracking number parser that uses these json files.
2. If you are creating a new library, great! Open an issue and let us know. We're happy to help!

I found a bug or missing couriers.

• Open an issue and specify the tracking numbers and courier service.
• PRs: Feel free to modify any json file that does not specify it is auto-generated by a script. Run ./lint_json.sh to clean up and validate the json file (you may need jq or other dependencies).

---

Helpful links

For finding the appropriate regular expressions and check digit algorithms for various couriers.

• misc:
  • http://www.gs1-128.info/sscc-18/
  • http://answers.google.com/answers/threadview/id/207899.html
• s10:
  • http://www.upu.int/uploads/tx_sbdownloader/S10TechnicalStandard.pdf
• fedex:
  • smartpost: https://www.fedex.com/us/smartpostguide/IMpbFAQ.html
  • barcode spec: http://images.fedex.com/us/solutions/ppe/FedEx_Ground_Label_Layout_Specification.pdf
  • updated barcode spec: http://www.fedex.com/us/gsn/barcode_guide.pdf
  • http://stackoverflow.com/questions/15744704/how-to-calculate-a-fedex-smartpost-tracking-number-check-digit
  • TODO: possible variation on fedex18:

  20 charss { "fedexsscc-18": "regex": "\d{2}(?<container_type>\d)(?<shipper_id>\d{7})(?\d{9})(?\d)"} "UCC/EAN 128": "regex": ""

• usps:
  • https://ribbs.usps.gov/intelligentmail_package/documents/tech_guides/PUB199IMPBImpGuide.pdf
    • page 109
  • http://about.usps.com/publications/pub97.pdf
    • "Electronic File Number"
    • "Package Identification Code (PIC)"
  • 13 char code uses two check digit algos:
    • mod10 (for domestic only)
    • s10 (for international or domestic mail)
  • other links:
    • http://about.usps.com/publications/pub97/pub97_appj_020.htm
    • http://about.usps.com/publications/pub97/pub97_appj_021.htm