tracking_number_data v1.0.1

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

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