📦 seventeentrack: A Simple Python API for 17track.net

seventeentrack is a simple Python library to track packages in 17track.net accounts.

This project was built off of py17track.

V1 API

You can register an account first here: https://features.17track.net/en/api Each account will have 100 free tracking quota for testing. Once logged in, you can find the API token/Access key under Settings -> Security -> Access Key

Python Versions

seventeentrack is currently supported on:

Python 3.7
Python 3.8
Python 3.9
Python 3.10

Installation

pip install seventeentrack

Usage

import asyncio

from aiohttp import ClientSession

from seventeentrack import Client


async def main() -> None:
    """Run!"""
    client = Client()

    # Login with API token:
    client.profile.login("<TOKEN>")

    # Get a summary of the user's packages:
    summary = await client.profile.summary()
    # >>> {'In Transit': 3, 'Expired': 3, ... }

    # Get all packages associated with a user's account:
    packages = await client.profile.packages()
    # >>> [seventeentrack.package.Package(..), ...]

    # Add new packages by tracking number
    await client.profile.add_package('<TRACKING NUMBER>', '<FRIENDLY NAME>')


loop = asyncio.get_event_loop()
loop.run_until_complete(main())

By default, the library creates a new connection to 17track with each coroutine. If you are calling a large number of coroutines (or merely want to squeeze out every second of runtime savings possible), an aiohttp ClientSession can be used for connection pooling:

import asyncio

from aiohttp import ClientSession

from seventeentrack import Client


async def main() -> None:
    """Run!"""
    async with ClientSession() as session:
        client = Client(session=session)

        # ...


loop = asyncio.get_event_loop()
loop.run_until_complete(main())

Each Package object has the following info:

destination_country: the country the package was shipped to
friendly_name: the human-friendly name of the package
info: a text description of the latest status
location: the current location (if known)
timestamp: the timestamp of the latest event
origin_country: the country the package was shipped from
package_type: the type of package (if known)
status: the overall package status ("In Transit", "Delivered", etc.)
tracking_info_language: the language of the tracking info
tracking_number: the all-important tracking number
carrier: the logistics company transporting the package

Contributing

Check for open features/bugs or initiate a discussion on one.
Fork the repository.
(optional, but highly recommended) Create a virtual environment: python3 -m venv .venv
(optional, but highly recommended) Enter the virtual environment: source ./.venv/bin/activate
Install the dev environment: script/setup
Code your new feature or bug fix.
Write tests that cover your new functionality.
Run tests and ensure 100% code coverage: script/test
Update README.md with any new documentation.
Add yourself to AUTHORS.md.
Submit a pull request!

Updating Carrier and Country JSON

If the carrier or country lists need to be updated to support new ones, simply download the updated JSON from 17track.

https://res.17track.net/asset/carrier/info/carrier.all.json

https://res.17track.net/asset/carrier/info/country.all.json