iiPythonx / USPS

A CLI for tracking packages from USPS (with crude support for UPS packages).
If you have any tracking numbers you're willing to share, please send them to [email protected].

Installation

uv pip install usps-cli

# or, install from dev:
uv pip install git+https://github.com/iiPythonx/usps

Usage

Important

For UPS packages, USPS-cli only support the 1Z version of UPS tracking numbers right now.

Get the tracking information for a package:

usps track 9400100000000000000000

Add a tracking number to your package list:

usps add 9400100000000000000000

Remove a tracking number from your package list:

usps remove 9400100000000000000000

Show all your current packages:

usps track

Add a name to a package:

$ usps name 9400100000000000000000 "Amazon Package"

# If you don't specify name, it will prompt for one.
$ usps name 9400100000000000000000
Choose a package name: Amazon Package

Remove the name from a package:

usps name --erase 9400100000000000000000

For more details, run usps --help.

Requirements

Note

If you only plan to track UPS packages, you can skip installing a selenium driver.

Since this package uses selenium for challenge solving, you'll need to install a Gecko-based browser and geckodriver.
Feel free to modify the code to use Chromium instead if you prefer it.

If you're on Arch: sudo pacman -S firefox geckodriver,

How it works

• Selenium goes to the USPS tracking website, completing the JS challenge and saving the cookies.
• This client saves that request data to a JSON file for reuse (speeds up the client dramatically).
• Next, requests pulls the page from USPS using our saved cookies and parses it with BeautifulSoup.
• Apply some basic scraping and there you go, a USPS tracking client.

It's worth noting I scrape USPS because their APIs get basically no support, require the creation of business accounts and filling out every piece of information about yourself, and even then you have to request explicit access to the tracking API.

Triggered?

If you're a USPS web tools representative or something and have a problem with this repository, shoot me an email: [email protected].