Plazi APItb.plazi.org ↗
Search and retrieve structured taxonomic treatments from TreatmentBank (tb.plazi.org): nomenclature, classifications, specimens, figures, and references via 2 endpoints.
What is the Plazi API?
The TreatmentBank API exposes 2 endpoints for accessing structured taxonomic treatments published in Plazi's TreatmentBank repository. The search_treatments endpoint filters treatments by kingdom, family, genus, species, rank, and publication year, while get_treatment returns the full content of a single treatment including 14 taxon classification fields, article metadata, text sections, materials citations, figures with DOIs, and literature references.
curl -X GET 'https://api.parse.bot/scraper/613af108-f46a-47fc-a38c-210d088a2163/search_treatments?genus=Quercus' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace tb-plazi-org-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Walkthrough: TreatmentBank SDK — search plant treatments, drill into full detail."""
from parse_apis.tb_plazi_org_api import TreatmentBank, TreatmentNotFound
client = TreatmentBank()
# Search for oak (Quercus) treatments published between 2020 and 2023.
for summary in client.treatment_summaries.search(genus="Quercus", year_from="2020", year_to="2023", limit=5):
print(summary.taxon_name, summary.year, summary.materials_citation_count)
# Drill down: take the first hit and fetch its full treatment via the typed navigation.
hit = client.treatment_summaries.search(family="Fagaceae", limit=1).first()
if hit is not None:
treatment = hit.details()
print(treatment.taxon.name, treatment.taxon.rank)
# Walk text sections included in this treatment.
for section in treatment.sections:
print(f" [{section.type}] p.{section.page_number}: {section.text[:120]}")
# Inspect materials citations (specimen records).
for mc in treatment.materials_citations or []:
print(f" specimen: {mc.country} — {mc.type_status} — {mc.verbatim[:100]}")
# Point lookup by a treatment_id discovered above.
if hit is not None:
try:
detail = client.treatments.get(treatment_id=hit.treatment_id)
print(detail.article.title, detail.article.year)
except TreatmentNotFound:
print("treatment no longer available")
print("exercised: treatment_summaries.search / details / treatments.get")
Searches TreatmentBank taxonomic treatments by taxonomic filters and publication year. One row per treatment (a taxon's account inside one article) with its classification, publication metadata, DOIs and specimen counts. By default restricted to kingdom Plantae; all taxonomic filters are exact, case-sensitive single-word epithets (e.g. genus Quercus, family Fagaceae). Results are ordered by treatment_id and paged with page/page_size (page_size max 100; default page 1, page_size 50); page * page_size may not exceed 2000, so narrow the filters (family, genus, year range) to walk large result sets. total is the count of all matching treatments; has_more tells whether a further page is reachable. Unknown taxon names yield a valid empty result. Two upstream round trips per call.
| Param | Type | Description |
|---|---|---|
| page | integer | 1-based page number. |
| rank | string | Rank of the treated taxon as a single lowercase word; values seen in results include species and genus. Omitted = all ranks. |
| genus | string | Genus epithet, e.g. Quercus. Omitted = no genus filter. |
| order | string | Taxonomic order epithet, e.g. Fagales. Omitted = no order filter. |
| family | string | Taxonomic family epithet, e.g. Fagaceae. Omitted = no family filter. |
| kingdom | string | Taxonomic kingdom epithet to restrict results to. |
| species | string | Species epithet (lowercase, e.g. glauca). Omitted = no species filter. |
| year_to | string | Latest publication year (inclusive), 4-digit year. Omitted = no upper bound. |
| page_size | integer | Treatments per page, capped at 100. |
| year_from | string | Earliest publication year (inclusive), 4-digit year. Omitted = no lower bound. |
{
"type": "object",
"fields": {
"page": "page number echoed",
"items": "array of treatment summaries: treatment_id (32-hex UUID, input for get_treatment), article_id, taxon_name (verbatim), rank, status (e.g. sp. nov. or null), authority, kingdom..species classification epithets (null when absent), article_title, article_author, year (integer), journal, volume/first_page/last_page (integers, 0 when unknown upstream), article_doi, treatment_doi, treatment_url, materials_citation_count, specimen_count, collecting_countries (array of country names)",
"total": "total number of treatments matching the filters",
"has_more": "true when a further page can be requested",
"page_size": "effective page size after capping"
},
"sample": {
"data": {
"page": 1,
"items": [
{
"rank": "species",
"year": 2013,
"class": "Magnoliopsida",
"genus": "Quercus",
"order": "Fagales",
"family": "Fagaceae",
"phylum": "Tracheophyta",
"status": null,
"volume": 137,
"journal": "Phytotaxa",
"kingdom": "Plantae",
"species": "glauca",
"authority": "Thunb.",
"last_page": 33,
"article_id": "FFBA3C15FFA9FFA9163FFF993A6FFFD5",
"first_page": 31,
"taxon_name": "Quercus glauca Thunb.",
"article_doi": "10.11646/phytotaxa.137.1.3",
"treatment_id": "0383446DFFADFFAF16A8FD843A8CFD2C",
"article_title": "Typification of Quercus acuta Thunb. and Q. glauca Thunb. (Fagaceae)",
"treatment_doi": null,
"treatment_url": "https://treatment.plazi.org/id/0383446D-FFAD-FFAF-16A8-FD843A8CFD2C",
"article_author": "DENG, Min & LI, Qiansheng & COOMBES, Allen & XU, Jin",
"specimen_count": 20,
"collecting_countries": [
"China",
"Hong Kong",
"Japan",
"Taiwan"
],
"materials_citation_count": 20
}
],
"total": 319,
"has_more": true,
"page_size": 5
},
"status": "success"
}
}About the Plazi API
Search Taxonomic Treatments
The search_treatments endpoint queries TreatmentBank's corpus of published taxonomic treatments. Each result row includes a treatment_id (32-character hex UUID), taxon_name, rank, status, and article_id. Filters can be combined: kingdom, family, genus, species, order, and rank narrow the taxon scope; year_to caps the publication year. Results default to kingdom Plantae when no kingdom filter is specified. Pagination is controlled via the page parameter, and the response includes total, has_more, and page_size to manage iteration across large result sets.
Retrieve Full Treatment Content
The get_treatment endpoint accepts a treatment_id from search results and returns the complete structured record for that treatment. The taxon object covers the full classification hierarchy from kingdom down to variety, plus authority, authority_year, and nomenclatural status. The article object includes authors, journal, volume, issue, year, article_doi, and source_url. Text is broken into a sections array where each entry carries a type label (such as nomenclature or description) and page_number, preserving document order.
Figures, References, and Cross-Links
Each treatment can include a figures array with caption_text, figure_doi, and image_url per figure. The references array provides structured bibliographic entries. Cross-treatment citations appear in cited_treatments, each with taxon_name, author, year, and a persistent treatment_url. The treatment itself is identified by a treatment_doi and a treatment_url, and a gbif_taxon_id links to the corresponding GBIF record when available.
The Plazi API is a managed, monitored endpoint for tb.plazi.org — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when tb.plazi.org changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official tb.plazi.org API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Build a species checklist for a taxonomic family by filtering
search_treatmentswith thefamilyparameter and collectingtaxon_nameandstatusfields. - Populate a biodiversity database with full classification hierarchies (kingdom through variety) using
get_treatment'staxonobject. - Track publication trends in a taxonomic group by querying
search_treatmentswithyear_toand aggregating results by year. - Link treatment records to GBIF occurrences using the
gbif_taxon_idfield returned byget_treatment. - Extract type specimen data and materials citations from the
sectionsarray to support systematic revisions. - Compile literature networks by parsing the
cited_treatmentsandreferencesarrays across multiple treatments. - Retrieve figure DOIs and image URLs from the
figuresarray to build illustrated taxon pages.
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 200 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
| Team | $300/mo | 20,000 | 300 req/min |
| Company | $1,000/mo | 100,000 | 500 req/min |
Each endpoint has a fixed posted price per successful call — most fall between 1 and 10 credits — shown on this API's page before you run it. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does Plazi's TreatmentBank have an official developer API?+
What does `get_treatment` return beyond the basic taxon name?+
taxon object with up to 14 classification fields (kingdom through variety, plus authority and authority_year), an article object with journal metadata and DOI, a sections array of typed text blocks in document order, a figures array with image URLs and figure DOIs, a references array of bibliographic entries, cited_treatments with persistent URLs, and identifiers including treatment_doi, treatment_url, and gbif_taxon_id.Does `search_treatments` cover all kingdoms, or only plants?+
kingdom parameter explicitly. The rank filter can then further narrow results to, for example, only genus-level or species-level treatments within that kingdom.Can I filter treatments by publication journal or author name?+
search_treatments endpoint filters by taxonomic rank, taxon epithet (kingdom, order, family, genus, species), and publication year upper bound. Journal and author filters are not exposed. You can fork this API on Parse and revise it to add those filters if the underlying data supports them.Is there a way to retrieve all treatments from a specific article at once?+
get_treatment call returns one treatment by treatment_id, and the search_treatments response includes an article_id per result, but there is no endpoint that accepts an article_id and returns all treatments within that article in a single call. You can fork the API on Parse and revise it to add an article-scoped endpoint.