T3 API : Getting Started

• Getting Started with the T3 API
  • Learning to use the Command Line
    • Navigating Directories
    • Platform-Specific Tips
    • Common Issues
  • Setting up your environment
    • Installing Python
  • Download the check script
    • Option 1: Download the check script from the command line
    • Option 2: Download the check script manually
  • Set your terminal location
    • Virtual Environment (Recommended)
    • Installing Python Libraries
  • Learning to run Python scripts
  • Running the check script
• Next Steps

Getting Started with the T3 API

To take advantage of the T3 API, one only needs a basic knowledge of using the command line and running scripts. This knowledge can be picked up very quickly.

Note: The T3 API offers some free endpoints, but most will require a T3+ subscription.

Learning to use the Command Line

The command line, also called the terminal or shell, is an interface that lets you interact with your computer using text commands. It’s especially useful for running programs like Python without needing a graphical interface.

• Windows: Command Prompt (or PowerShell/Windows Terminal for more advanced usage).
  • Press Win + R, type cmd, and hit Enter for Command Prompt.
  • Alternatively, search for "PowerShell" or "Windows Terminal" and open it.
• macOS: Terminal app.
  • Press Command + Space to open Spotlight Search, type "Terminal," and press Enter.
• Linux: Terminal (built-in for most distributions).
  • Use the Ctrl + Alt + T shortcut, or find "Terminal" in your application menu.

Navigating Directories

To run a Python script, you need to be in the directory (also known as a "folder") where the script is stored. It's easiest to just open a terminal directly in the same folder you’re browsing. Here’s how to do it on each major operating system.

• Windows

  • Option 1: File Explorer Option:

    1. In Windows 10/11, navigate to the folder in File Explorer.
    2. Hold down the Shift key and right-click in the folder.
    3. Select Open PowerShell window here or Open Command Window here (depending on your system settings).

  • Option 2: File Explorer Address Bar:

    1. In File Explorer, click the folder path in the address bar.
    2. Type cmd for Command Prompt or powershell for PowerShell, then press Enter.
    3. This will open the specified terminal directly in the current folder.

  • Option 3: Windows Terminal (PowerShell/Command Prompt):

    1. Install Windows Terminal from the Microsoft Store if not already installed.
    2. Follow the same Shift + Right-click steps, then select Open in Windows Terminal.

• macOS

  • Option 1: Finder Context Menu:

    1. Open Finder and navigate to the desired folder.
    2. Right-click (or Control + click) in the folder.
    3. Select New Terminal at Folder (available in macOS Catalina and later).
       • If this option doesn’t appear, enable it from System Preferences > Keyboard > Shortcuts under Services.

  • Option 2: Terminal Command:

    1. Open Terminal (Applications > Utilities > Terminal).
    2. Type cd (note the space after cd).
    3. Drag and drop the folder from Finder into the Terminal window, then press Enter to change to that directory.

• Linux

  • Option 1: File Manager Context Menu:

    1. In GNOME (Ubuntu) or KDE (Plasma) environments, right-click in the folder.
    2. Select Open in Terminal from the context menu.
    3. Some distributions may require enabling this feature in File Manager settings.

  • Option 2: Nautilus Quick Shortcut:

    1. In Nautilus (the default file manager for many Linux distributions), open the file manager and navigate to your folder.
    2. Press Ctrl + Alt + T to open a terminal in the current directory.

  • Option 3: Address Bar:

    1. In some Linux file managers, you can also type terminal or gnome-terminal in the address bar to open a terminal.

Platform-Specific Tips

• Windows: You may need to use py script_name.py if python or python3 doesn’t work. This launches the latest installed Python version.
• macOS/Linux: The command python3 may be needed if python points to Python 2.

Common Issues

• "Python is not recognized as an internal or external command": This error means Python isn’t in your PATH. Refer to step 7.
• Permissions Errors: In macOS/Linux, use chmod +x script_name.py to give execute permissions, if needed.

Setting up your environment

For beginners, I recommend using Python to interact with the T3 API. All the T3 example scripts are written in Python.

Installing Python

Official Python getting started guide

Before running any Python script, verify that Python is installed.

• Type python3 --version and press Enter. You should see a version number like Python 3.x.x.
• If you see an error, install Python from python.org.

Download the check script

Once you have Python installed and configured, let's test to see if you have everything working properly. The T3 Examples repository has a script that checks to see if you have everything set up properly.

Option 1: Download the check script from the command line

Running this curl will download the file into the current terminal directory/folder:

curl -L -o api_check.py https://raw.githubusercontent.com/classvsoftware/t3-api-examples/refs/heads/master/api_check.py

Option 2: Download the check script manually

You can find the check script here, and download it by clicking "download raw file".

Set your terminal location

Open a terminal in the same folder as your script file. Instructions for easily doing this can be found here.

Virtual Environment (Recommended)

A Python virtual environment is just a container to install Python packages into. It's not strictly required, but it's recommended, and some operating systems like OS X require it.

The following commands create a virtual environment next to your script file, and activates it. Run them in order.

1. Create a virtual environment named "venv":

   python3 -m venv ./venv

2. Activate the virtual environment;

   source ./venv/bin/activate

NOTE: You will need to reactiveate the virtual environment with source ./venv/bin/activate every time you open up a terminal.

Installing Python Libraries

Once you have Python installed, you will also need the requests library to send requests to the API.

Run pip3 install requests to install the library. If you are using a virtual environment, ensure it is activated before running this command.

Tip: You might see error: externally-managed-environment on OSX. This just means you need to create a "virtual environment" for Python.

Learning to run Python scripts

Running Python scripts will take the following form: python3 [script filename] [extra stuff afterwards]. For example, python3 example_script.py --flag1=FLAG1VALUE --flag2=FLAG2value

You're not expected to know this format, all the scripts in the example repository will tell you how to run them and provide detailed messages on how to fix problems.

To ask a script how it should be run, use the --help flag. For example, python3 api_check.py --help.

The response will be something like this:

usage: api_check.py [-h] --hostname HOSTNAME --username USERNAME

Check API access configuration for Track and Trace Tools.

options:
  -h, --help           show this help message and exit
  --hostname HOSTNAME  The hostname of the Track and Trace Tools API (e.g., mo.metrc.com). This is required to target the correct server. Example: --hostname=mo.metrc.com
  --username USERNAME  Username for authentication with the Track and Trace Tools API. This should be a valid email or user identifier for the account. Example: [email protected]

So in this case, the correct format would be python3 api_check.py --hostname=mo.metrc.com [email protected]

All the scripts in the examples repository include help documentation that describing how the script should be run.

Running the check script

Run the check script you downloaded to test if your credentials can access the API.

If everything is normal, you will see You successfully authenticated with the T3 API. The output will also indicate if your Metrc username is registered for T3+.

Next Steps

• Refer to the T3 API documentation to explore all the available endpoints.
• Most API endpoints require a T3+ subscription. If you don't have a T3+ subscription, you can sign up here.