table of contents
Business::US::USPS::WebTools::TrackConfirm(3pm) | User Contributed Perl Documentation | Business::US::USPS::WebTools::TrackConfirm(3pm) |
NAME¶
Business::US::USPS::WebTools::TrackConfirm - track a shipment using the USPS Web Tools
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 $array_of_hashes = $tracker->track( TrackID => $tracking_number ); if( $tracker->is_error ) { warn "Oh No! $tracker->{error}{description}\n"; } else { foreach my $hash ( reverse $hash->{TrackDetail}->@* ) { say '-' x 50; say join "\n", map { "$_: $hash->{$_}" } qw(Event EventCity EventDate EventTime); } }
DESCRIPTION¶
*** THIS IS ALPHA SOFTWARE ***
This module implements the Track & Confirm web service from the US Postal Service. It is a subclass of Business::US::USPS::WebTools.
- track( TrackID => VALUE )
- Although the USPS API allows to make multiple queries in a single request,
this method one queries only one.
The "track" method takes the following keys, which come directly from the USPS web service interface:
TrackID The tracking number
It returns an anonymous array of hashes with the data from the response. Each hash represents one step in the tracking and is blessed into Hash::AsObject. The array is in reverse chronological order (so the oldest detail is the last element). The first element is the latest status (and is mostly the same as TrackSummary from the API).
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.
<TrackSummary> <EventTime>8:34 pm</EventTime> <EventDate>September 25, 2018</EventDate> <Event>Departed</Event> <EventCity>NEWARK</EventCity> <EventState /><EventZIPCode /> <EventCountry>UNITED STATES</EventCountry> <FirmName /> <Name /> <AuthorizedAgent>false</AuthorizedAgent> <EventCode>AT</EventCode> </TrackSummary>"
- test_server_host
- The testing API uses stg-production.shippingapis.com instead of the usual testing server.
TO DO¶
SEE ALSO¶
Business::US::USPS::WebTools
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¶
This source is in GitHub:
https://github.com/ssimms/business-us-usps-webtools
AUTHOR¶
brian d foy
MAINTAINER¶
Steve Simms
COPYRIGHT AND LICENSE¶
Copyright © 2020, Steve Simms. All rights reserved.
This program is free software; you can redistribute it and/or modify it under the terms of the Artistic License 2.0.
2022-08-28 | perl v5.34.0 |