NAME¶

SYNOPSIS¶

        use Business::US::USPS::WebTools::TrackConfirm;

        my $tracker = Business::US::USPS::WebTools::TrackConfirm->new( {
                UserID   => $ENV{USPS_WEBTOOLS_USERID},
                Password => $ENV{USPS_WEBTOOLS_PASSWORD},
                Testing  => 1,
                } );

        my $hash = $tracker->track(
                );

        if( $tracker->is_error )
                {
                warn "Oh No! $tracker->{error}{description}\n";
                }
        else
                {
                print join "\n", map { "$_: $hash->{$_}" }
                        qw(FirmName Address1 Address2 City State Zip5 Zip4);
                }

DESCRIPTION¶

This module implements the Track & Confirm web service from the US Postal Service. It is a subclass of Business::US::USPS::WebTools.

track( KEY, VALUE, ... )

The "track" method takes the following keys, which come directly from the USPS web service interface:

        TrackID   The tracking number
    

It returns an anonymous hash with the data from the response. Although the USPS API allows one to make multiple queries in a single request, this method one queries one.

If you want to see if something went wrong, check:

        $tracker->is_error;
    

See the "is_error" documentation in Business::US::USPS::WebTools for more details on error information.

tracking_number_regex

Returns the regex that checks a tracking number. I have it in its own method so you can easily override it if I got it wrong.

The USPS shows the valid forms at

        https://tools.usps.com/go/TrackConfirmAction!input.action

        USPS Tracking®                        9400 1000 0000 0000 0000 00
        Priority Mail®                        9205 5000 0000 0000 0000 00
        Certified Mail®                       9407 3000 0000 0000 0000 00
        Collect on Delivery                       9303 3000 0000 0000 0000 00
        Global Express Guaranteed®                82 000 000 00
        Priority Mail Express International™  EC 000 000 000 US
        Priority Mail Express™                9270 1000 0000 0000 0000 00
                                          EA 000 000 000 US
        Priority Mail International®          CP 000 000 000 US
        Registered Mail™                      9208 8000 0000 0000 0000 00
        Signature Confirmation™               9202 1000 0000 0000 0000 00
    

is_valid_tracking_number( ID )

Returns a normalized version of the tracking number if ID looks like a tracking number, based on the regex from "tracking_number_regex". Returns false otherwise.

Normalizing ID merely removes all whitespace. Sometimes the USPS shows the numbers with whitespace.

service_type( ID )

Returns the service type, based on the examples shown by the USPS and shown in "tracking_number_regex". I know this is wrong because I have tracking numbers that don't have the same leading characters for Priority Mail International.

TO DO¶

SEE ALSO¶

The WebTools API is documented on the US Postal Service's website:

https://www.usps.com/business/web-tools-apis/track-and-confirm-api.htm

SOURCE AVAILABILITY¶

        https://github.com/briandfoy/business-us-usps-webtools

AUTHOR¶

COPYRIGHT AND LICENSE¶

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.