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.

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:

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:

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.

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:

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_".

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.

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.

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.

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 2023 February 12:

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.

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.

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:

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

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.

Choosing an Image File

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

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.