Command-Line Interface

The epmc-cli tool provides a command-line interface for the Europe PMC API and for local file processing.

Usage

epmc-cli [OPTIONS] COMMAND [ARGS]...

Options

• –email TEXT: Contact email for API identification.

• –tool TEXT: Tool name for API identification.

Commands

• local: Commands for local file processing.

• articles: Commands for the Europe PMC Articles API.

• annotations: Commands for the Europe PMC Annotations API.

• grants: Commands for the Europe PMC Grants API.

• oai: Commands for the Europe PMC OAI-PMH service.

Local Commands

The local command group provides tools for processing local files.

jats2json

Converts a JATS XML file to a structured JSON format. By default, it also performs sentence splitting.

The command intelligently detects the input type. The input can be a local file path, a URL pointing to a JATS XML file, or a Europe PMC article ID (PMCID).

epmc-cli local jats2json <input> <path_to_output_json> [--no-sentenciser]

Arguments:

• INPUT: The input to process. This can be a local file path, a URL, or a PMCID (e.g., PMC11704132).

• OUTPUT_PATH: Path to save the output JSON file.

Options:

• –no-sentenciser: Disable sentence splitting.

Examples:

• From a local file: .. code-block:: bash

  epmc-cli local jats2json test_data/PXD053361.xml output.json

• From a URL: .. code-block:: bash

  epmc-cli local jats2json https://www.ebi.ac.uk/europepmc/webservices/rest/PMC11704132/fullTextXML output.json

• From a PMCID: .. code-block:: bash

  epmc-cli local jats2json PMC11704132 output.json

The tool provides specific error messages if the input file cannot be found, the URL is invalid, or the PMCID does not have a full-text XML available.

extract-accessions-resources

Extracts accession numbers and resources from a JSON file (previously generated by jats2json).

epmc-cli local extract-accessions-resources output.json accessions.json

You can also run this command in offline mode to avoid online validation of the extracted entities:

epmc-cli local extract-accessions-resources output.json accessions.json --offline

Articles API

Search for articles:

epmc-cli articles search "machine learning" --page-size 1

Get article metadata:

epmc-cli articles get PMC11704132

Get full-text XML:

epmc-cli articles fulltext PMC11704132

Annotations API

Get annotations by article ID:

epmc-cli annotations by-id PMC:11704132

Find articles that cite a specific entity:

epmc-cli annotations by-entity p53

Get annotations of a specific type:

• By data accession:

  epmc-cli annotations by-type --type 'Accession Numbers' --subtype 'uniprot'
  

• By gene name:

  epmc-cli annotations by-type --type 'Gene_Proteins'
  

• By resource name:

  epmc-cli annotations by-type --type 'Resources'
  

Grants API

Search for grants:

epmc-cli grants search "cancer" --page-size 1

OAI Service

Harvest metadata:

epmc-cli oai harvest --metadata-prefix oai_dc