PubTator3 API Client

Fetch biomedical literature annotations from the PubTator3 database via its REST API.

Quick Start

0. Install uv (Recommended)

# On Linux/macOS
curl -LsSf https://astral.sh/uv/install.sh | sh

# On Windows (PowerShell)
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# Or via pip
pip install uv

Documentation: https://docs.astral.sh/uv/getting-started/installation/

1. Install Dependencies

# Using uv (recommended) - single command setup
uv sync

# Or using pip
pip install pandas requests

2. Run the Script

Edit the pmids list in accessing_pubtator_api.py, then run:

uv run python accessing_pubtator_api.py

Output files are saved to the output/ directory:

• NER.csv - Named Entity Recognition annotations (genes, diseases, chemicals, etc.)
• Relations.csv - Extracted relations between entities
• Failed.csv - List of PMIDs that failed to fetch

Usage

Basic Example

from accessing_pubtator_api import obtain_pubtator_ner_and_re_from_selected_pmids

pmids = [19805025, 19411856, 17970072, 10367897, 2110366]

# Uses default output files: output/NER.csv, output/Relations.csv, output/Failed.csv
obtain_pubtator_ner_and_re_from_selected_pmids(pmids, batch_size=15)

Custom Output Files

obtain_pubtator_ner_and_re_from_selected_pmids(
    pmids,
    ner_output_file='my_ner_results.csv',
    relations_output_file='my_relations.csv',
    failed_pmids_file='my_failed_pmids.csv',
    batch_size=10
)

Environment Variables

# Custom API endpoint
export PUBTATOR_API_BASE="https://mirror.com/api/export"

# Export format (biocjson, biocxml, json, pubtator, pubtatorcentral)
export PUBTATOR_FORMAT="json"

# Custom output directory
export PUBTATOR_OUTPUT_DIR="results"

uv run python accessing_pubtator_api.py

Retrying Failed PMIDs

If some PMIDs fail during the initial run (network issues, API errors, etc.), you can retry just the failed PMIDs using the retry_failed_pmids.py script.

Command Line Usage

# Default: reads output/Failed.csv and saves to output_retry/
uv run python retry_failed_pmids.py

Python Script Usage

from retry_failed_pmids import retry_failed

# Retry with default settings
retry_failed()

# Retry with custom files
retry_failed(
    failed_file='output/Failed.csv',
    output_dir='output_retry'
)

Retry Output Files

The retry script creates a new output_retry/ directory with:

• NER_retry.csv - NER results from retried PMIDs
• Relations_retry.csv - Relations from retried PMIDs
• Failed_retry.csv - PMIDs that still failed (if any)

Notes

• Uses smaller batch size (10) for better stability
• Handles both output/Failed.csv and PMIDs_failed.csv formats
• Original failed file is not modified

Output Files

File	Description
output/NER.csv	Entity annotations from initial run (genes, diseases, chemicals, variants, species). Columns include: PMC, PMID, entity text, locations, type, name, identifier
output/Relations.csv	Relations from initial run (treat, cause, interact, etc.). Includes relation type, source, and target entities
output/Failed.csv	PMIDs that failed during initial run with error codes
output_retry/NER_retry.csv	Entity annotations from retry run
output_retry/Relations_retry.csv	Relations from retry run
output_retry/Failed_retry.csv	PMIDs that still failed after retry

Configuration

Parameter	Default	Description
batch_size	15	PMIDs per API request (10-20 recommended)
api_base	PubTator3 official	Override API endpoint
format	biocjson	Export format

Troubleshooting

Error	Solution
502 Bad Gateway	Reduce batch_size to 10, check connection
429 Rate Limit	Built-in rate limiter prevents this; check for other scripts
Timeout	Reduce batch_size, check internet connection
Failed PMIDs	Check output/Failed.csv, then run uv run python retry_failed_pmids.py

API Details

• Rate Limit: ~30 requests/minute
• Retry Logic: Automatic retries for 502/503/504 errors with exponential backoff
• PubTator3 API Documentation | Tutorial