WHO API Client

An unofficial, community-built Python client and CLI for the WHO Classification of Tumours web application. This project wraps the undocumented internal API used by the site's frontend — there is no official public API. Browse books, chapters, content, attachments, and search across the full WHO Classification database from the command line or from Python code.

Note: This project is not affiliated with or endorsed by the World Health Organization or IARC. The API is undocumented and may change without notice. Users must comply with the IARC/WHO Terms of Use at all times. A valid WHO Classification subscription is required.

Features

Complete API coverage - series, books, chapters, content, attachments, search, favourites, user profile
Type-safe Python API - Pydantic v2 models with full validation for every endpoint
Rich CLI - 15 commands with table, tree, JSON, and other output formats
Image downloads - batch-download chapter figures with automatic WSI/table detection
Search - simple text search from the CLI, advanced boolean search (AND/OR/NOT, parentheses) from Python
Secure credential storage - credentials encrypted at rest (AES) with restricted file permissions
Automatic token management - transparent login, refresh, and retry

Requirements

Python >= 3.10
A WHO Classification of Tumours account with valid credentials

Installation

Install globally as a CLI tool:

uv tool install who-api-client

Or run directly without installing:

uvx who-api-client --help

As a project dependency:

uv add who-api-client

Or with pip:

pip install who-api-client

Quick Start

# 1. Authenticate (interactive prompt)
who-api-client login

# 2. Browse the catalogue
who-api-client series
who-api-client books
who-api-client chapters 31

# 3. Read content
who-api-client content 31 11
who-api-client attachments 31 11

# 4. Search
who-api-client search "adenocarcinoma"

Authentication

Credentials are encrypted at rest using Fernet (AES-128-CBC + HMAC-SHA256) and stored in ~/.config/who-api-client/credentials.enc. The encryption key is stored alongside it in .encryption_key with restricted file permissions (0600). This works reliably across all installation methods (uv tool install, pipx, pip, etc.).

The client checks for credentials in this order:

Environment variables (WHO_EMAIL, WHO_PASSWORD) — highest priority, ideal for CI/CD
Encrypted config file (~/.config/who-api-client/credentials.enc) — default, works across all installation methods
.env file — development convenience

# Interactive login (encrypts and saves to config file)
who-api-client login

# Provide email via flag (password is always prompted securely)
who-api-client login --email you@example.com

# Use system keyring instead (opt-in)
who-api-client login --use-keyring

# Save to .env file in current directory
who-api-client login --save-to-env

# Check authentication status
who-api-client status

# View your profile and subscription
who-api-client profile

# Remove stored credentials
who-api-client logout

CLI Reference

Authentication

Command	Description
`login`	Authenticate and save credentials
`logout`	Remove stored credentials
`status`	Check authentication status
`profile`	Show user profile and subscription details

Data Access

Command	Arguments	Formats	Default
`series`		table, json	table
`books`		table, json	table
`chapters`	`BOOK_ID`	tree, table, json	tree
`content`	`BOOK_ID CHAPTER_ID`	text, markdown, html, json	text
`attachments`	`BOOK_ID CHAPTER_ID`	list, json	list
`tables`	`BOOK_ID CHAPTER_ID`	markdown, json	markdown
`download-images`	`BOOK_ID CHAPTER_ID`
`ancestors`	`BOOK_ID CHAPTER_ID`	tree, table, json	tree
`favourites`		tree, table, list, json	tree
`favorites`		(alias for favourites)
`search`	`QUERY`	table, compact, list, json	table

Examples

# List all book series
who-api-client series

# List books as JSON
who-api-client books --format json

# Browse chapter tree, limit depth
who-api-client chapters 31 --max-depth 2

# Read chapter content
who-api-client content 31 11

# Clean markdown output (ideal for piping or LLM consumption)
who-api-client content 31 11 --format markdown

# Fetch only specific sections
who-api-client content 31 11 --format markdown --sections "Definition,Histopathology"

# View raw HTML content
who-api-client content 31 11 --format html

# List only figure attachments
who-api-client attachments 31 11 --type figure

# Render tables as markdown
who-api-client tables 31 11

# Download all figures from a chapter
who-api-client download-images 31 11 --output ./images/

# Show chapter breadcrumb path
who-api-client ancestors 31 11

# View favourites sorted by chapter
who-api-client favourites --sort chapter

# Search specific books for a term
who-api-client search "carcinoma" --books 31,32

# Search in headings and content
who-api-client search "melanoma" --headings --content

# Compact output (one line per chapter, deduplicated, ideal for piping)
who-api-client search "GIST" --headings --content --format compact

# Search only headings (exclude chapters)
who-api-client search "sarcoma" --no-chapters --headings

Python API

from who_api_client import WHOAPIClient

with WHOAPIClient() as client:
    # Browse the catalogue
    series = client.get_book_series()
    books = client.get_books()
    book = client.get_book(31)
    chapters = client.get_chapters(31)

    # Read content
    content = client.get_chapter_content(31, 11)
    for section in content:
        print(section.headingTitle)
        print(section.clean_content_text)

    # Attachments and images
    attachments = client.get_attachments(31, 11)
    figures = [a for a in attachments if a.is_figure]
    wsi = [a for a in attachments if a.is_wsi]
    tables = [a for a in attachments if a.is_table]

    # Download figures
    client.download_image(figures[0], "output.jpg")
    stats = client.download_chapter_images(31, 11, "./images/")

    # Chapter context
    ancestors = client.get_chapter_ancestors(31, 11)
    assignments = client.get_assignments(31, 11)

    # User info
    user = client.get_user_details()
    colors = client.get_book_colors(31)

    # Favourites
    favourites = client.get_favourites()
    client.add_chapter_to_favourites(31, 11)
    client.remove_chapter_from_favourites(31, 11)

    # Simple search
    results = client.search("adenocarcinoma", book_ids=[31, 32])

    # Advanced search with boolean logic
    results = client.advanced_search([
        ("sarcoma", None, True, False),       # (sarcoma
        ("lipoma", "OR", False, True),        # OR lipoma)
        ("tumour", "AND", False, False),      # AND tumour
    ], search_in="both")

Client Methods

Method	Returns	Description
`get_book_series()`	`BookSeriesResponse`	All series with their books
`get_books()`	`list[Book]`	All available books
`get_book(book_id)`	`Book`	Single book details
`get_chapters(book_id)`	`list[Chapter]`	Hierarchical chapter structure
`get_chapter_content(book_id, chapter_id)`	`list[ChapterContent]`	Chapter text content
`get_attachments(book_id, chapter_id)`	`list[Attachment]`	Images, tables, WSI
`get_chapter_ancestors(book_id, chapter_id)`	`list[ChapterAncestor]`	Breadcrumb path
`get_assignments(book_id, chapter_id)`	`list[Assignment]`	Contributors and roles
`get_book_colors(book_id)`	`BookColors`	Color theme configuration
`get_user_details()`	`UserDetails`	Profile and subscription
`get_favourites()`	`list[FavouriteBook]`	Favourite chapters by book
`add_chapter_to_favourites(book_id, chapter_id)`	`AddFavouriteResponse`	Add to favourites
`remove_chapter_from_favourites(book_id, chapter_id)`	`RemoveFavouriteResponse`	Remove from favourites
`is_chapter_in_favourites(book_id, chapter_id)`	`bool`	Check favourite status
`download_image(attachment, path)`	`None`	Download single figure
`download_chapter_images(book_id, chapter_id, dir)`	`dict`	Batch download figures
`search(text, ...)`	`SimpleSearchResponse`	Simple text search
`advanced_search(terms, ...)`	`AdvancedSearchResponse`	Boolean search

Data Model

BookSeries -> Book -> Chapter -> ChapterContent
                              -> Attachment (figure / WSI / table)
                              -> Assignment -> Contributor
                              -> ChapterAncestor (breadcrumb)

All text models provide clean_* properties that strip HTML tags, decode entities, and normalize whitespace.

Attachment objects expose type-detection properties: is_figure, is_wsi, is_table, is_image, and image_type.

Security Considerations

This is an unofficial API client. Use it at your own risk.

Credential storage: Credentials are encrypted at rest following the same pattern used by the Google Workspace CLI:

Component	Storage	Protection
Credentials	`~/.config/who-api-client/credentials.enc`	AES-encrypted (Fernet), file permissions `0600`
Encryption key	`~/.config/who-api-client/.encryption_key`	File permissions `0600`
Config directory	`~/.config/who-api-client/`	Directory permissions `0700`

The encryption key is stored as a file rather than in the OS keychain, ensuring consistent behavior across all Python installation methods and platforms. Running who-api-client logout removes both the credentials file and the encryption key.

Other credential backends have different security properties:

Backend	Security	Notes
Environment variables	Moderate	Suitable for CI/CD. May be visible in process listings or shell history.
System keyring (`--use-keyring`)	Strongest	OS-level encryption (macOS Keychain, Windows Credential Manager, Linux Secret Service). May prompt with unsigned Python binaries on macOS.
`.env` file (`--save-to-env`)	Weakest	Plaintext on disk (file permissions `0600`) in the current directory. Avoid committing — `.env` is in `.gitignore` by default.

Error Handling

Exception	When
`ConfigurationError`	Missing or invalid credentials
`AuthenticationError`	Login failure or expired token
`TokenError`	Token operation failure
`WHOAPIError`	Base class for all client errors

The client automatically retries on transient failures with exponential backoff, and re-authenticates when tokens expire.

Development

# Clone and install with dev dependencies
git clone https://github.com/tbedau/who-api-client.git
cd who-api-client
uv sync

# Run unit tests
uv run pytest tests/unit/

# Run with coverage
uv run pytest --cov=who_api_client

# Lint and format
uv run ruff check
uv run ruff format

# Run integration tests (requires valid credentials)
uv run pytest tests/integration/

Disclaimer

This is an unofficial client that wraps the undocumented internal API of the WHO Classification of Tumours web application. It is not affiliated with, endorsed by, or in any way officially connected to the World Health Organization (WHO) or the International Agency for Research on Cancer (IARC).

The API is not public — it is an undocumented internal API and may change or break at any time.
A valid WHO Classification subscription is required to use this client.
All content accessed through this client is subject to the IARC/WHO Terms of Use.
Built-in rate limiting (0.5s between requests) helps avoid excessive load on WHO servers. Please do not disable or circumvent it.

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 12 Commits
.github/workflows		.github/workflows
src/who_api_client		src/who_api_client
tests		tests
.env.example		.env.example
.gitignore		.gitignore
.python-version		.python-version
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
README.md		README.md
cli-books-output.png		cli-books-output.png
pyproject.toml		pyproject.toml
uv.lock		uv.lock

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

WHO API Client

Features

Requirements

Installation

Quick Start

Authentication

CLI Reference

Authentication

Data Access

Examples

Python API

Client Methods

Data Model

Security Considerations

Error Handling

Development

Disclaimer

License

About

Uh oh!

Releases

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

WHO API Client

Features

Requirements

Installation

Quick Start

Authentication

CLI Reference

Authentication

Data Access

Examples

Python API

Client Methods

Data Model

Security Considerations

Error Handling

Development

Disclaimer

License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages