tufman_extract.py

Downloads report(s) from the Tufman2 API and saves each as a CSV file in output/.

This is just a boilerplate example to demonstrate how Tufman 2 Reports data can be extracted using an API request.

Currently this repo contains only a python workflow for accessing Tufman 2 Reports data but it would be great to expand it and include other other frameworks using different computer languages. For R users, SPC currently maintains a R package for accessing Tufman 2 reports called Tufman2R

The Python script can be used as a starting point but it should easy to modify it for saving outputs in a database or incorporated in Apps directly accessing T2 reports.

The sections below describe the steps to run the python workflow mainteined under the folder python.

1. Create a virtual environment

From the repo root (ffa-example/):

py -3.13 -m venv .venv

Use py -3.13 (or whichever Python 3.x you have installed) rather than plain python.

2. Activate the venv and install dependencies

PowerShell:

.\.venv\Scripts\Activate.ps1
pip install -r python\requirements.txt

Git Bash:

source .venv/Scripts/activate
pip install -r python/requirements.txt

3. Set up the .env file

Copy python/envtemplate to python/.env and fill in your Tufman credentials:

TUF_USER=your.email@spc.int
TUF_PASSWORD=your_password
TUF_COUNTRY=SB

TUF_COUNTRY is the Tufman country/instance code (e.g. SB, PW).

4. Run the script

With the venv activated:

cd python
python tufman_extract.py

Each configured report is downloaded and saved to python/output/<report_name>.csv. An auth token is cached in python/.tuf_token_cache.json and reused until it expires, so you won't re-authenticate on every run.

5. Add more reports

Reports are listed in the REPORTS list near the top of tufman_extract.py:

REPORTS = [
    {
        "name": "report_e334f4cc",
        "guid": "e334f4cc-0708-fdc6-926e-3a1e37719963",
        "lang": "en",
        "run_params": "{}",
    },
]

Access parameters for a specific T2 report

Each Tufman2 report can have their own parameters (ie.: year, eez, country,...). To know exactly which parameters you should inform in the run_params payload you will need to go to T2 and:

• request the data for the report you are interested in
• right click on the page, select Inspect
• refresh the page
• in the network tab, look for the api call that starts with 'Run?'
• click on it and then check the exact payload for that query (go to the Payload tab)

To add another report:

1. Open the report in the Tufman2 web app and copy its GUID from the URL (.../ReportDefinition/<guid>/result).
2. Add a new entry to REPORTS with a unique name, the guid, lang, and any run_params the report needs, e.g. "run_params": "{year: 2025}".
3. Save and re-run the script — it will fetch every report in the list on each run.