Calculating the UPS Tracking Number Check Digit

Introduction

This article serves to describe the algorithm used to calculate a UPS Tracking Number. It took me a while to figure this out, researching mostly. I thought I would make it a bit easier for others by describing it here.

Using the code

The following code is a generic method that can be used to calculate a check digit for a UPS Tracking Number. The input for the method is a string, but you could rework it to use a raw char[] if wish. This method leaves the rest of the tracking number up to you. It takes a 15 character sequence, in this case a string, and calculates the check digit using this sequence. For information sake, I will describe how the company I work for generates tracking numbers. This is up to you, as only two portions are required by UPS, the rest you can make up on your own.

The first two characters must be "1Z".
The next 6 characters we fill with our UPS account number "XXXXXX".
The next 2 characters denote the service type:

"01" for Next Day Air shipments.
"02" for Second Day Air shipments.
"03" for Ground shipments.

The next 5 characters is our invoice number (our invoices are 6 digits; we drop the first digit, e.g., the 123456 invoice would yield 23456 characters).
The next 2 digits is the package number, zero filled. E.g., package 1 is "01", 2 is "02".
The last and final character is the check digit.

First of all, you will notice that the described sequence above gives us 17 characters, where as we only need 15 to calculate the check digit. To do this, we drop the "1Z" portion, and only use the last 15 characters in the method.

Next, let me take a moment to outline the algorithm used to generate the check digit. Then, you'll see the method below the outline:

Start a running total.
Examine each character in the sequence:

If the character is in an odd position (e.g., 1^st, 3^rd, 5^th....), then:

If the character is numeric, then add the numeric value to the running total.
If the character is alpha, then:

Calculate n to be (ASCII value of character - 48)
Calculate x to be ((2 * n) - (9 * INT(n/5))) where INT(n/5) returns n/5 rounded down to the next integer (e.g., 34.3 would be 34, but 34.8 would also be 34).
Add x to the running total.

If the character is in an even position (e.g., 2^nd, 4^th, 6^th......), then:

If the character is numeric, then:

Calculate n to be (2 * the numeric value of the character).
Add n to the running total.

If the character is alpha, then:

Calculate n to be (ASCII value of character - 48).
Add n to the running total.

Calculate x to be (running total modulo 10)

If x = 0, then x is the check digit.
If x > 0, then:

Calculate y to be (10 - x).
y is the check digit.

Here is the method:

//
// UPS Check Digit Calculation Method
//

private int CalculateCheckDigit(String trk)
{
   int checkdigit = 0;
   char[] chars = trk.ToCharArray();
   int charindex = 1;
   int runningtotal = 0;
   foreach(Char ch in chars)
   {
      if((charindex % 2) == 0) //Indicates character in even position
      {
         int testeven;
         if(Int32.TryParse(ch.ToString(), out testeven) == true)
         // Indicates numeric value
         {
            runningtotal += (2 * testeven);
         }
         else // Indicates alpha value
         {
            int asciivalue = System.Convert.ToInt32(ch);
            int n = asciivalue - 48;
            runningtotal += n;
         }
      }
      else // Indicates character in odd position
      {
         int testodd;
         if(Int32.TryParse(ch.ToString(), out testodd) == true)
         // Indicates numeric value
         {
            runningtotal += testodd;
         }
         else // Indicates alpha value
         {
            int asciivalue = System.Convert.ToInt32(ch);
            int n = asciivalue - 48;
            int x = ((2 * n) - (9 * (int)(n / 5)));
            runningtotal += x;
         }
      }
      charindex++;
   }
   int x = (runningtotal % 10);
   if(x == 0) checkdigit = x;
   else if(x > 0) checkdigit = (10 - x);
   return checkdigit;
}

License

This article, along with any associated source code and files, is licensed under The Code Project Open License (CPOL)

About the Author

stebo0728

United States

Member

Article Top

Poor

Excellent

Add a reason or comment to your vote: x
Votes of 3 or less require a comment

Comments and Discussions

You must Sign In to use this message board. (secure sign-in)

Search this forum
	Profile popups Noise Layout Per page

My Courier Class to check for valid check digits

blyxx86

10:37 21 Jun '11

Parts of the code are a little messy, but it works!

Courier Class:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Text.RegularExpressions;
using System.ComponentModel;
 
namespace MyApp
{
    static class Courier
    {
        public static CourierName GetCourier(string trackingNumber)
        {
            switch (trackingNumber.Length)
            {
                case 12:
                    return CourierName.FedExExpress;
                case 15:
                    return CourierName.FedExGround;
                case 18:
                    return CourierName.UPS;
                default:
                    return CourierName.Unknown;
            }
        }
        public static bool IsValid(string trackingNumber)
        {
            return IsValid(trackingNumber, GetCourier(trackingNumber));
        }
        public static bool IsValid(string trackingNumber, CourierName courierName)
        {
            // trim any extra characters
            trackingNumber = Regex.Replace(trackingNumber, @"[^0-9A-Za-z]", "").ToUpper();
 
            if (courierName == CourierName.FedExExpress) // fedex express method
            {
                return _ValidateFedExExpressCheckDigit(trackingNumber);
            }
            else if (courierName == CourierName.UPS) // UPS method
            {
                return _ValidateUPSCheckDigit(trackingNumber);
            }
            else if (courierName == CourierName.FedExGround)
            {
                return _ValidateFedExGroundCheckDigit(trackingNumber);
            }
            return false;
        }
 
        private static bool _ValidateFedExExpressCheckDigit(string trackingNumber)
        {
            char[] trackingNumberArray = new char[trackingNumber.Length];
            trackingNumberArray = trackingNumber.ToCharArray();
 
            //reverse array
            Array.Reverse(trackingNumberArray, 0, trackingNumber.Length);
            int sum = 0;
            int multiplier = 7;
            int check = 0;
            for (int i = 1; i < trackingNumber.Length; i++) //skip check digit
            {
                if (multiplier == 7)
                {
                    multiplier = 1;
                }
                else if (multiplier == 1)
                {
                    multiplier = 3;
                }
                else if (multiplier == 3)
                {
                    multiplier = 7;
                }
                sum += (Convert.ToInt32(trackingNumberArray.GetValue(i)) - 48) * multiplier;
            }
            check = sum % 11;
            if (check == 10)
            {
                check = 0;
            }
 
            if ((Convert.ToInt32(trackingNumberArray.GetValue(0)) - 48) == check)
            {
                // check digit passes
                return true;
            }
            else
            {
                // check digit fails
                return false;
            }
        }
 
        public enum CourierName
        {
            [Description("FedEx Express")]
            FedExExpress = 1,
            [Description("FedEx Ground")]
            FedExGround = 2,
            UPS = 3,
            OnTrac = 4,
            Unknown = 100
 
        }
        
        private static bool _ValidateUPSCheckDigit(string trackingNumber)
        {
            char[] trackingNumberArray = new char[trackingNumber.Length];
            trackingNumberArray = trackingNumber.ToCharArray();
            int checkDigit = 0;
            int sum = 0;
            for (int i = 2; i < trackingNumber.Length - 1; i++)
            {
                if (char.IsDigit(trackingNumberArray[i]) == false)
                {
                    if (Regex.IsMatch(trackingNumberArray[i].ToString(), "[A-H]"))
                    {
                        trackingNumberArray[i] = (char)(Convert.ToInt32(trackingNumberArray.GetValue(i)) - 15);
                    }
                    else if (Regex.IsMatch(trackingNumberArray[i].ToString(), "[I-R]"))
                    {
                        trackingNumberArray[i] = (char)(Convert.ToInt32(trackingNumberArray.GetValue(i)) - 25);
                    }
                    else if (Regex.IsMatch(trackingNumberArray[i].ToString(), "[S-Z]"))
                    {
                        trackingNumberArray[i] = (char)(Convert.ToInt32(trackingNumberArray.GetValue(i)) - 35);
                    }
 
                }
                if (i % 2 == 0) // adding all odd positions
                {
                    sum += (Convert.ToInt32(trackingNumberArray.GetValue(i)) - 48);
                }
                else
                {
                    sum += 2 * (Convert.ToInt32(trackingNumberArray.GetValue(i)) - 48);
                }
 
            }
            checkDigit = (int)(Math.Ceiling(sum / 10.0d) * 10) - sum; // round to the next highest ten (71 becomes 80)
            if ((Convert.ToInt32(trackingNumberArray.GetValue(trackingNumber.Length - 1)) - 48) == checkDigit)
            {
                // check digit passes
                return true;
            }
            else
            {
                // check digit fails
                return false;
            }
        }
        private static bool _ValidateFedExGroundCheckDigit(string trackingNumber)
        {
            char[] trackingNumberArray = new char[trackingNumber.Length];
            trackingNumberArray = trackingNumber.ToCharArray();
 
            //reverse array
            Array.Reverse(trackingNumberArray, 0, trackingNumber.Length);
            int sum = 0;
            int check = 0;
            for (int i = 1; i < trackingNumber.Length; i++) // skip position 0
            {
                if (i % 2 == 1) // every other digit multiplied by 3
                {
                    sum += (Convert.ToInt32(trackingNumberArray.GetValue(i)) - 48) * 3;
                }
                else
                {
                    sum += (Convert.ToInt32(trackingNumberArray.GetValue(i)) - 48);
                }
            }
            check = (int)(Math.Ceiling(sum / 10.0d) * 10) - sum;
            if (check == 10)
            {
                check = 0;
            }
            if ((Convert.ToInt32(trackingNumberArray.GetValue(0)) - 48) == check)
            {
                // check digit passes
                return true;
            }
            else
            {
                // check digit fails
                return false;
            }
        }
    }
}

Include in main class:

using System.Reflection;
namespace MyApp
{
class Program
 
    {
        public static string GetDescription(Enum value)
        {
            FieldInfo fi = value.GetType().GetField(value.ToString());
 
            DescriptionAttribute[] attributes =
                (DescriptionAttribute[])fi.GetCustomAttributes(
                typeof(DescriptionAttribute),
                false);
 
            if (attributes != null &&
                attributes.Length > 0)
                return attributes[0].Description;
            else
                return value.ToString();
        }
    }
}

Usage:

string message = "";
string trk = "123412349999";
if (Courier.IsValid(trk))
{
    // is valid
    message += GetDescription(Courier.GetCourier(trk)) + ": " + trk + " is valid.\n\r";
}
else
{
    // is not valid
    message += GetDescription(Courier.GetCourier(trk)) + ": " + trk + " is not valid.\n\r";
}

Updates to original function

heyheyitsdavid

6:01 20 Nov '07

I was attempting to implement your function to validate UPS tracking numbers and it seemed to be fairly inconsistent in producing the correct check digit for real UPS tracking numbers that I was trying it with. It would be right about 25% of the time and off by 1 digit the rest of the time. I did a little research and found some information here that helped me make a few corrections to your function to get it working better for me.

A quick summary of the small changes I made:

1. I decided to strip out the "1z" and final (check) digit inside the function, it just seemed more convenient to pass the whole unaltered tracking number rather than stripping these 15 digits away outside the function.

2. Instead of subtracting 48 from the Alpha characters, I subtract 63 from them and then mod the result by 10. This results in the values from the Alpha to Numeric chart that can be found via the link above.

3. All even position values (both Alpha and Numeric) are multiplied by two and added to the total and all odd position values are simply added to the running total. This differs in that it does not matter if the value was derived from and Alpha or Numeric, it's multiplier is only dependent on it's position.

private int CalculateUPSCheckDigit(String trk)
{
    //Drop first 2 characters ("1Z"), take next 15 characters, drop final character (check digit)
    trk = trk.Substring(2, 15);
 
    int checkdigit = 0;
    char[] chars = trk.ToCharArray();
    int charindex = 1;
    int runningtotal = 0;
    foreach (Char ch in chars)
    {
        if ((charindex % 2) == 0) //Indicates character in even position
        {
            int testeven;
            if (Int32.TryParse(ch.ToString(), out testeven) == true) // Indicates numeric value
            {
                runningtotal += (2 * testeven);
            }
            else // Indicates alpha value
            {
                int asciivalue = System.Convert.ToInt32(ch);
                int n = ((asciivalue - 63) % 10) * 2; 
                runningtotal += n;
            }
        }
        else // Indicates character in odd position
        {
            int testodd;
            if (Int32.TryParse(ch.ToString(), out testodd) == true) // Indicates numeric value
            {
                runningtotal += testodd;
            }
            else // Indicates alpha value
            {
                int asciivalue = System.Convert.ToInt32(ch);
                int n = (asciivalue - 63) % 10;
                runningtotal += n;
            }
        }
        charindex++;
    }
    
    int y = (runningtotal % 10);
 
    if (y == 0)
    {
        checkdigit = y;
    }
 
    else if (y > 0)
    {
        checkdigit = (10 - y);
    }   
 
    return checkdigit;
}

I also used the page linked above to create a function to calculate the check digit value of FedEx tracking numbers if anyone would be interested.

Thanks,
David Bowker