tracking_number_data

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	SerialNumber CheckDigit ShipperId ServiceType PackageId
Multiple / S10 International Standard	13	RB123456785GB	SerialNumber CheckDigit CountryCode ServiceType
FedEx / Ground 15	15	0414 4176 0228 964	SerialNumber CheckDigit
FedEx / Ground (SSCC 18)	18	00 0123 4500 0000 0027	SerialNumber CheckDigit ShippingContainerType
FedEx / Ground (96)	22	9611020987654312345672	SerialNumber CheckDigit ApplicationIdentifier SCNC ServiceType ShipperID PackageId
Fedex / Ground (GSN)	34	9622 0015 6 000 123 4567 1 00 7948 0839 0594	SerialNumber CheckDigit ApplicationIdentifier SCNC GSN
FedEx / Express 12	12	986578788855	SerialNumber CheckDigit
FedEx / Express Saver	34	1001921334250001000300779017972697	SerialNumber CheckDigit DestinationZip
FedEx / SmartPost	22	61299998820821171811	ApplicationIdentifier``SerialNumber, CheckDigit, ServiceType, ShipperId, PackageId
USPS 20	20	0307 1790 0005 2348 3741	SerialNumber CheckDigit ServiceType MailerId PackageId
USPS 91	25-34	420 221539101026837331000039521 9361 2898 7870 0317 6337 95 7196 9010 7560 0307 7385	SerialNumber CheckDigit RoutingApplicationId DestinationZip SCNC ServiceType ShipperId PackageId
OnTrac	15	C11031500001879	SerialNumber CheckDigit
DHL Express	10	3318810025	SerialNumber CheckDigit
DHL Express Air	10	73891051146	SerialNumber CheckDigit
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