MGnify Proteins API in Python

Look up cluster representatives, search by biome or Pfam domain, and build a FASTA file.

Edit and run the cells below, in order. The first visit may take a minute to load. Copy any code you want to keep before leaving or reloading the page.

The endpoints, parameters and response fields used here are described in the Proteins API reference.

Set up

Every example reuses this base address and helper.

Look up a protein

Fetch one cluster representative and read its sequence. Replace the accession to look up a different protein.

The same record written out as FASTA:

Find proteins carrying a Pfam domain

The search endpoint takes exactly one filter. Searching by Pfam accession returns the matching cluster representatives:

Search results carry only mgyp, full_length and cluster_size. Fetching each hit from the detail endpoint adds the sequence length and the domains it carries:

Build a FASTA file for a biome

A common workflow: find the cluster representatives observed in a biome, then retrieve each sequence. Searching by biome_lineage covers the biome and all of its sub-biomes. Edit the lineage or the limit, then run the cell again to rebuild the download.

Note

requests encodes the query parameters, so biome names that contain spaces — for example root:Host-associated:Human:Digestive system — need no special handling.

Tip

This makes one request per protein, so keep LIMIT modest and be considerate of the service, which is rate-limited. For thousands of sequences, query the release remotely with Parquet and DuckDB, or take a bulk download instead.

Explore outwards from one protein

The biome ids in a detail response are the same ids the search endpoint accepts, so you can start from a protein of interest and find others sharing its biome:

Running this code in your own environment

Install the package from a terminal:

python -m pip install requests

Run the Python cells in a notebook or script. To save the FASTA to a file instead of downloading it from the browser, replace the download cell with:

with open(fasta_filename, "w") as fasta_file:
    fasta_file.write(fasta_text)