Busine...onfirm(3pm)

📦
version 1.125 · 3 versions
, in ubuntu noble, ubuntu resolute, ubuntu stonking

💖 Busine...onfirm — aka the TrackConfirm page, section 3pm of the perl manual ✨

okok bestie, gather round, because we are about to track some PACKAGES 📦💅

🌸 NAME 🌸

Business::US::USPS::WebTools::TrackConfirm — track a shipment using the USPS Web Tools. that's it, that's the whole vibe. 👑

✨ SYNOPSIS ✨

here's what it looks like when you actually use it, no cap:

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);
        }
    }

literally so clean. ✨

🦋 DESCRIPTION 🦋

*** THIS IS ALPHA SOFTWARE ***

yes bestie, ALPHA. we're in our experimental era. 🧪💀

This module implements the Track & Confirm web service from the US Postal Service. It is a subclass of Business::US::USPS::WebTools. (so it inherits the family drama, iykyk)

📦 track( TrackID => VALUE )

Although the USPS API allows to make multiple queries in a single request, this method one queries only one. (one at a time bestie, we're not greedy 🙈)

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. (ngl, that's so thoughtful of them 🫶)

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

(that whole list is giving very much "cheat sheet" energy and we love her for it 💜)

✅ 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. (spaces are NOT the moment, so we yeet them 🌬️)

🏷️ 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. (author being honest about their L's, we respect it 😭)

<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. (yes the staging server is doing its own thing, iconic behavior 💅)

📝 TO DO 📝

(empty bestie. the vibes are immaculate. nothing to do, we're thriving 🎀)

👀 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

go star it or whatever, support the devs 🫶

👑 AUTHOR 👑

brian d foy

💜 MAINTAINER 💜

Steve Simms

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.

okay so that's the whole page!! 🎉 this was pulled from the perl manual, version v5.36.0, dated 2022-08-28 — and Busine...onfirm (the truncated title, because apparently even manpages have to abbreviate when they get too long, lowkey relatable 😭✨). go track your packages bestie, and remember: reverse your array so you read from oldest to newest, that's the main character move. periodt. 💅📦🌸

📦 where this page comes from