API Recipes

The PhyloPic API is thoroughly documented at the API Documentation Website. As an alternative introduction, this article offers a simpler (but non-comprehensive) guide to using the API, with some examples of commonly-needed functionality, like listing images and searching for taxa. As well, it documents how other APIs may be used to augment searching capabilities.

This article is intended for readers who are familiar with:

  • using a command-line prompt (UNIX, etc.),
  • basic World Wide Web technological terms (URL, HTTP header, query parameter, etc.), and
  • the JSON data format.

Examples are given as curl commands which may be run in a command-line prompt. Or, click the “play“ icon (⏵) to run queries and see results on this page. As an example, this call loads the index for the RESTful API, with JSON data detailing other resource endpoints and general metadata about the site.

API Index
curl --location "https://api.phylopic.org"

For compatibility with future versions of the API, it is strongly recommended that you include the major API version (2) in the Accept header thusly:

API Index (major API version specified)
curl --header "Accept: application/vnd.phylopic.v2+json" --location "https://api.phylopic.org"

But this is not a strict requirement. For brevity, the ensuing examples will forgo it.

Builds

You may notice that the JSON response includes properties called "build" and "buildTimestamp". Updates to PhyloPic are published in discrete builds. In order to return data, each API call must include the current build number in the query string. If no build number is included, a 307 Temporary Redirect response is returned, indicating a modified URL (in the Location header) with the current build number added to the query string. (This is why the command above includes the --location option.) The response to the modified URL will always include a "build" property with the current build number.

To skip the redirect, simply place the current build number in the query string:

API Index (current build specified)
curl "https://api.phylopic.org?build=NaN"

URLs that specify a previous build will result in a 410 Gone error response. The current build number is included in the response so that it can be used in subsequent calls.

API Index (obsolete build specified)
curl "https://api.phylopic.org?build=1"

Entities

There are three major types of entity in PhyloPic’s database: images, nodes, and contributors. Each individual entity is identified by a UUID, which can be included in the URL to retrieve data about it. Examples:

Image
curl --location "https://api.phylopic.org/images/045279d5-24e5-4838-bec9-0bea86812e35"

Node
curl --location "https://api.phylopic.org/nodes/8f901db5-84c1-4dc0-93ba-2300eeddf4ab"

Contributor
curl --location "https://api.phylopic.org/contributors/060f03a9-fafd-4d08-81d1-b8f82080573f"

Each entity may includes links to other individual entities, in the _links object. For example, nodes include a link to parentNode (except for the root node) and primaryImage. Images include a link to their contributor, specificNode, and sometimes a generalNode, as well as a list of nodes: a lineage including specificNode and generalNode.

These linked entities may be embedded in the response directly using certain query parameters whose names start with "embed_".

Image with Embedded Entities
curl --location "https://api.phylopic.org/images/045279d5-24e5-4838-bec9-0bea86812e35?embed_generalNode=true&embed_nodes=true&embed_specificNode=true"

Node with Embedded Entities
curl --location "https://api.phylopic.org/nodes/8f901db5-84c1-4dc0-93ba-2300eeddf4ab?embed_parentNode=true&embed_primaryImage=true"

Lists

The API uses the same structure for lists of any type of entity. By default, a list endpoint returns metadata about the list: number of items, number of pages, and links to the first and last page.

List of All Images
curl --location "https://api.phylopic.org/images"

Subsequent calls to the list endpoint can include a zero-indexed page query parameter to get a particular page of entities. Examples are included in the list metadata, under _links.firstPage and _links.lastPage. The build parameter must be included for page queries.

First Page of All Images
curl "https://api.phylopic.org/images?build=NaN&page=0"

Page responses list links to individual entities in _links.items. These entities can also be embedded in the response itself, using the embed_items parameter.

First Page of All Images, with Items Embedded
curl "https://api.phylopic.org/images?build=NaN&embed_items=true&page=0"

Lists can also be filtered with certain parameters whose names start with "filter_". For example, this command this returns metadata for all images submitted on or after :

List of Images Created after a Given Date
curl "https://api.phylopic.org/images?build=NaN&filter_created_after=2023-02-12T00:00:00.000Z"

Searching for a Taxonomic Name

PhyloPic mostly only covers taxa for which it has silhouettes. But it also provides tools for augmenting searches with external resources that cover other taxa. To take full advantage, you may need to make multiple calls both to the PhyloPic API and to other APIs. Examples below include the GBIF API, the Open Tree of Life API, and the Paleobiology Database API.

Searching in PhyloPic

To search for a taxonomic name in PhyloPic, send the search text (preferably lower-case, with non-alphabetic characters removed and whitespace trimmed) as a filter parameter (filter_name) to the/nodes endpoint:

Search for a Taxonomic Name
curl --location "https://api.phylopic.org/nodes?filter_name=primates"

You may optionally preface these searches with autocomplete calls, to get matching strings that PhyloPic will definitely return results for:

Autocomplete for Taxonomic Names
curl --location "https://api.phylopic.org/autocomplete?query=prim"

You may also wish to skip loading the list metadata and just load the first page (which usually has the most relevant results). Remember to include the current build number. (And note that this will yield a 404 Not Found response if there are no results.)

First Page of Search Results for a Taxonomic Name
curl "https://api.phylopic.org/nodes?build=NaN&filter_name=primates&page=0"

Searching in GBIF

The full documentation for the GBIF API is available here: https://www.gbif.org/developer/summary

To get a list of taxon suggestions for a search string, use the /species/suggest endpoint:

Taxon Suggestions for GBIF
curl "https://api.gbif.org/v1/species/suggest?q=dionaea+m"

Alternately, you can search for a full-string match with the /species/match endpoint:

Taxonomic Name Matches for GBIF
curl "https://api.gbif.org/v1/species/match?name=Dionaea+muscipula&verbose=true"

Once you have a matching object, collect the rank keys from lowest rank to highest rank: speciesKey, genusKey, familyKey, orderKey, classKey, phylumKey, and kingdomKey. Place those as a comma-separated list in a query to the PhyloPic API’s /resolve/gbif.org/species endpoint in order to find the closest match in PhyloPic.

Resolve Node for GBIF
curl --location "https://api.phylopic.org/resolve/gbif.org/species?build=NaN&objectIDs=5421410,3191248,5399,422,220,7707728,6"

Searching in the Open Tree of Life

The full documentation for the Open Tree of Life API is available here: https://opentreeoflife.github.io/develop/api

To get a list of taxa matching a search string, POST a JSON object to the /tnrs/autocomplete_name endpoint:

Autocomplete for Open Tree of Life
curl --data "{\"name\":\"prim\"}" "https://api.opentreeoflife.org/v3/tnrs/autocomplete_name"

This will yield a list of objects with an ott_id property serving as a unique identifier. You may use the ott_id to get the full lineage of a particular taxon.

Lineage for Open Tree of Life
curl --data "{\"include_lineage\":true,\"ott_id\":7501342}" "https://api.opentreeoflife.org/v3/taxonomy/taxon_info"

Collect the ott_id values from the lineage, from the least inclusive taxon to the most inclusive taxon (i.e., the order in the response), and place those as a comma-separated list in a query to the PhyloPic API’s /resolve/opentreeoflife.org/taxonomy endpoint in order to find the closest match in PhyloPic.

Resolve Node for Open Tree of Life
curl --location "https://api.phylopic.org/resolve/opentreeoflife.org/taxonomy?build=NaN&objectIDs=70119,937683,329706,844843,2914936,178260,409995,802117,155737,189832,117569,641038,691846,5246131,332573,304358,93302,805080"

Searching in the Paleobiology Database

The full documentation for the Paleobiology Database API version 1.2 is available here: https://paleobiodb.org/data1.2

To get a list of taxa matching a search string, use the /taxa/auto.json endpoint:

Autocomplete for Paleobiology Database
curl "https://training.paleobiodb.org/data1.2/taxa/auto.json?limit=10&name=prim"

This will yield an object with a list of records, each with an oid property serving as a unique identifier. You may use the oid to get the full lineage of a particular taxon.

Lineage for Paleobiology Database
curl "https://training.paleobiodb.org/data1.2/taxa/list.json?id=txn:133360&rel=all_parents"

Collect the oid values (minues the "txn:" prefix) from the records into an array, in order from the least inclusive taxon to the most inclusive taxon (i.e., the reverse of the order in the response). Place those as a comma-separated list in a query to thePhyloPic API’s /resolve/paleobiodb.org/txn endpoint in order to find the closest match in PhyloPic.

Resolve Node for Paleobiology Database
curl --location "https://api.phylopic.org/resolve/paleobiodb.org/txn?build=NaN&objectIDs=133360,133359,39168,38935,91793,38882,53189,56749,465406,37177,125547,53190,77135,219195,67348,34881,67344,67149,33815,67145,272902,67103,67091,212579,1,28595"

Choosing an Image for a Taxa

Once you have found the node (or as close as PhyloPic has to it), how do you select a silhouette for it? The easiest way is to use the primaryImage property. In general this is the earliest-submitted image of those that most closely illustrate the node.

Node with Embedded Primary Image
curl --location "https://api.phylopic.org/nodes/37040a3d-bf9c-4aa0-9ca4-d953caac1d1c?embed_primaryImage=true"

However, you may want to select from a list of images that directly represent the node. Use the node’s UUID as a filter to get the list metadata:

List of Images for a Node
curl --location "https://api.phylopic.org/images?filter_node=37040a3d-bf9c-4aa0-9ca4-d953caac1d1c"

And use this to get the first page in the list (usually the only page), with image metadata embedded in the response:

First Page of Images for a Node
curl "https://api.phylopic.org/images?build=NaN&embed_items=true&filter_node=37040a3d-bf9c-4aa0-9ca4-d953caac1d1c&page=0"

Using filter_node will only retrieve images that directly represent that particular node. For ancestral nodes, it may be better to get all the images within the full clade (the node and all descendant nodes). The image entries will be roughly sorted in order of their subject matter’s proximity to the ancestral node.

List of Images within a Clade
curl "https://api.phylopic.org/images?build=NaN&embed_items=true&filter_clade=36c04f2f-b7d2-4891-a4a9-138d79592bf2&page=0"

Choosing an Image File

Once you have the metadata for the image, there will be several options for the image file.

Image
curl --location "https://api.phylopic.org/images/c466a71f-90b9-4ea7-b6ba-56cb37d47f22"

Look in the _links object and select from these:

http://ogp.me/ns#image
An image meant to be used as a preview in social media.
rasterFiles
A list of raster files (pixel-based, PNG format), from largest to smallest.
sourceFile
The original file, as uploaded.
thumbnailFiles
A list of square thumbnail files (PNG format), from largest to smallest.
vectorFile
A vector version of the image (SVG format), automatically generated from sourceFile. This image is pure black on a transparent background, and may look different from the original file.

Making Your Own Recipes

Hopefully this article has provided a gentle introduction to the PhyloPic API. You may read the complete documentation to see about other possibilities and optimizations for your own needs.

You may also take a look at the open source code repository and even make contributions to it.

Happy coding!

Buy me a coffee.