Application Programming Interface

Version A, Release 2

Web developers may access the data in PhyloPic's database using the JavaScript Object Notation (JSON) API. JSONP (JSON with Padding) calls are also supported — simply send a GET or POST parameter called callback with the name of the function to pass the response to.

If the methods described herein are not sufficient for the desired functionality, developers are encouraged to propose new API methods or enhancements to existing ones.


Format

Every API call returns a JSON object. This object always has a property called success, storing a Boolean value indicating whether the call was successful.

If the call was successful, the object also has a property called result storing the result object. Example (where the result is an empty array):

{
	"result": [],
	"success": true
}

If the call was not successful, the object also has a property called fault storing a fault object. Example:

{
	"fault": {
		"code": "invalidField",
		"details": {
			"name": "nameUIDsToAdd",
			"value": "96aafc90-8bc2-11e1-b0c4-0800200c9a66"
		},
		"message": "Invalid name identifier."
	},
	"success": false
}

The fields of the fault object provide information about the error. The code property provides a short string indicating the general type of the error. The message property provides text explaining the error, which may be shown to users. The details property may provide an object storing further information (but it also may be null).

Some calls may produce a response with an HTTP error status code, such as 403 Forbidden (meaning the current user, if any, does not have permission to perform this action) or 404 Not Found (indicating that a specified entity does not exist). Any other HTTP error status code probably indicates a bug that should be reported.

Models

Many calls return data model objects. These calls usually involve a GET or POST parameter, called options, which stores a whitespace-separated list of optional fields for the model objects. For example, one type of model object is a taxonomic name. If options is not set, it will simply return an object with a single field, uid, storing a universally unique identifier (UUID):

{
	"uid": "74aea16b-666b-497a-b2cb-72201ad75a8e"
}

But, for example, if options is set to "string type votes" then it will return an object like this:

{
	"string": "Homo sapiens",
	"type": "scientific",
	"uid": "74aea16b-666b-497a-b2cb-72201ad75a8e",
	"votes": 0
}

Here is a list of the types of objects that may be returned, with their fields:

Image


credit
[optional]
String
The credit for the image. May be null, if licenseURL indicates a public domain license.
directNames
[optional]
Array
A list of model objects for taxonomic names that the image is directly associated with. (The image may be inferred to represent other names as well; see taxa.)
licenseURL
[optional]
String
The URL of the image's Creative Commons license. One of the following:
  • "http://creativecommons.org/licenses/by/3.0/"
  • "http://creativecommons.org/licenses/by-nc/3.0/"
  • "http://creativecommons.org/licenses/by-nc-sa/3.0/"
  • "http://creativecommons.org/licenses/by-sa/3.0/"
  • "http://creativecommons.org/publicdomain/mark/1.0/"
  • "http://creativecommons.org/publicdomain/zero/1.0/"
modified
[optional]
String
Timestamp string indicating when the image file was last updated. Format: YYYY-MM-DD HH:MM:SS.
pngFiles
[optional]
Array

A list of PNG file model objects.

Note Every image has two PNG files that are not included in this list:

  1. a thumbnail version, which is always 64×64px and always has the URL http://phylopic.org/assets/images/submissions/{imageUID}.thumb.png; and
  2. a blue icon version, which is always 32×32px and always has the URL http://phylopic.org/assets/images/submissions/{imageUID}.icon.png.
These are not included because their information is always the same.

submitted
[optional]
String
Timestamp string indicating when the image was first submitted. Format: YYYY-MM-DD HH:MM:SS.
submitter
[optional]
Object
svgFile
[optional]
Object
An SVG file model object. May be null.
taxa
[optional]
Array
A list of taxon model objects. This includes all taxa indicated by directNames as well as any taxa that the image is inferred to represent.
uid
[always]
String
Universally unique identifier.

Name


citationStart
[optional]
Integer
Indicates where in the string the citation starts. May be null.
html
[optional]
String
HTML version of the name.
namebankID
[optional]
String
uBio Namebank identifier. May be null.
root
[optional]
Boolean
If true, this name has no hyperonyms (names of supertaxa). (Should only be true for Panbiota/Vitae.)
string
[optional]
String
The text of the name, including the citation, if any.
type
[optional]
String
Either "scientific or "vernacular.
uid
[always]
String
Universally unique identifier.
uri
[optional]
String
The unique URI associated with the name.
votes
[optional]
Integer
The number of votes this name has received. (Currently unused.)

Name Set


names
[optional]
Array
uid
[always]
String
Universally unique identifier.

PNG File


height
[always]
Integer
Height, in pixels.
url
[always]
String
URL for the file.
width
[always]
Integer
Width, in pixels.

Source


title
[always]
String
Title of the source.
uri
[always]
String
Unique URI for the source.

SVG File


url
[always]
String
URL for the file.

Taxon


canonicalName
[optional]
Object
A model object for this taxon's canonical name (that is, the most preferred name). This is always present if names is absent.
icon
[optional]

Returns a model object with the UID of an image that may be used as an icon. This is either an illustration of the taxon or a supertaxon. If no appropriate images can be found, this will be null.

Note This just includes the uid field, not the full Image model object.

illustrated
[optional]
Boolean
Tells whether this taxon has any images. If false it may still be possible to search for an approximation.
names
[optional]
Array
A list of model objects for all names associated with this taxon.

User Profile


allowContact
[optional]
Boolean
Tells whether the user allows email contact from other parties.
email
[optional]
String
User's email address. This is never included if allowContact is false and the request is not made by the user themself or a manager.
firstName
[optional]
String
User's first name. This is never included if allowContact is false and the request is not made by the user themself or a manager.
lastName
[optional]
String
User's last name. This is never included if allowContact is false and the request is not made by the user themself or a manager.
uid
[always]
String
Universally unique identifier.

Methods

Account

Gets information on a user account.


Authorization

None

URL

http://phylopic.org/api/a/account or http://phylopic.org/api/a/account/{userUID}

URL Parameters

userUID [optional] User's universally unique identifier. If omitted, uses the currently logged-in user.

GET Parameters

options [optional] Space-separated list of optional fields for the result value.

Result

A user profile model object.

Account: Add

Registers a new user. If successful, an email is sent to the user with further instructions.


Authorization

None

URL

http://phylopic.org/api/a/account/add

POST Parameters

allowContact [optional] Tells whether the user allows other people to see their email address. String value of "true" or "false". Defaults to "false".
  email [required] User's email address.
  firstName [optional] User's given name.
  lastName [optional] User's family name.
  password [required] User's password.

Result

true

Account: Check

Checks whether the user is currently logged in, and what their role is if so.


Authorization

None

Result

If the user is not logged in, null. Otherwise, a string with the user's role, either "contributor" or "administrator".

Account: Edit

Updates the current user's information.


Authorization

User

URL

http://phylopic.org/api/a/account/edit

POST Parameters

allowContact [optional] Tells whether the user allows other people to see their email address. String value of "true" or "false". If neither, nothing is changed.
  currentPassword [optional] User's current password. If included, newPassword must also be included.
  firstName [optional] User's given name. If not included, this is not changed.
  lastName [optional] User's family name. If not included, this is not changed.
  newPassword [required] User's new password. If included, currentPassword must also be included.
  options [optional] Space-separated list of optional fields for the result value.

Result

A user profile model object.

Account: Images

Finds all the images a user has submitted. (Note: these are not all necessarily credited to the user.)


Authorization

None (if the specified user is the same as the logged-in user, or the specified user's allowContact setting is set to true)
or
Administrator (if the specified user is not the same as the logged-in user and the specified user's allowContact setting is set to false)

URL

http://phylopic.org/api/a/account/images/{start}/{length} or http://phylopic.org/api/a/account/{userUID}/images/{start}/{length}

URL Parameters

userUID [optional] User's universally unique identifier. If not provided, the user who is currently logged in is used. (The call will fail if userUID is not provided and nobody is logged in.)

 

start The index to start with. Using 0 starts with the most recently-submitted image.
  length The number of images to list.

GET Parameters

options [optional] Space-separated list of optional fields for the result value.

Result

A list of image model objects, from most to least recently submitted.

Account: Images Count

Counts the number of images a user has submitter.


Authorization

None (if the specified user is the same as the logged-in user, or the specified user's allowContact setting is set to true)
or
Administrator (if the specified user is not the same as the logged-in user and the specified user's allowContact setting is set to false)

URL

http://phylopic.org/api/a/account/images/count or http://phylopic.org/api/a/account/{userUID}/images/count

URL Parameters

userUID [optional] User's universally unique identifier. If not provided, the user who is currently logged in is used. (The call will fail if userUID is not provided and nobody is logged in.)

Result

An integer.

Account: Log In

Logs a registered user in.


Authorization

None

URL

http://phylopic.org/api/a/account/login

POST Parameters

email [required] User's email address.
  options [optional] Space-separated list of optional fields for the result value.
  password [required] User's password.

Result

A user profile model object.

Account: Log Out

Logs the current user out.


Authorization

User

URL

http://phylopic.org/api/a/account/logout

Result

true

Account: Password Reset Request

Initiates a request to reset a user's password, emailing them a link with a key.


Authorization

None

URL

http://phylopic.org/api/a/account/password/reset/request

POST Parameters

email [required] User's email address.

Result

true

Hyponymy: Add

Creates a relationship between two names, indicating one as the hyperonym (name of the supertaxon) and the other as the hyponym (name of the subtaxon).


Authorization

User

URL

http://phylopic.org/api/a/hyponymy/{hyperonymUID}/{hyponymUID}/add

URL Parameters

hyperonymUID The UUID of the hyperonym (supertaxon's name).
  hyponymUID The UUID of the hyponym (subtaxon's name).

Result

Boolean value telling whether the hyponymy is enabled.

Hyponymy: Toggle

Enables or disables a hyponymy. (See Hyponymy Add.)


Authorization

Administrator

URL

http://phylopic.org/api/a/hyponymy/{hyperonymUID}/{hyponymUID}/toggle

URL Parameters

hyperonymUID The UUID of the hyperonym (supertaxon's name).
  hyponymUID The UUID of the hyponym (subtaxon's name).

POST Parameters

enabled [optional] A value of "true" or "false", indicating whether the hyponymy is to be enabled or disabled. If neither, or not provided, simply uses the opposite of the current value.

Result

Boolean value telling whether the hyponymy is enabled.

Image

Retrieves information about an image.


Authorization

None

URL

http://phylopic.org/api/a/image/{imageUID}

URL Parameters

imageUID The UUID of the image.

GET Parameters

options [optional] Space-separated list of options for the result value.

Result

Image model object.

Image: Add

Creates a new image in the PhyloPic gallery.


Authorization

Contributor

URL

http://phylopic.org/api/a/image/add or http://phylopic.org/api/a/image/{imageUID}/add

URL Parameters

imageUID [optional] The UUID of the image. This should be generated according to the UUID Version 4 specification (§ 4.4). If omitted, the server will generate one.

POST Parameters

credit [optional] Credit for this image. Only optional if the image has a Public Domain license.
  licenseURL [required] The URL of the license for this image. See the Image model specification for a list of valid URLs.
  nameUIDs [required] A space-separated list of UUIDs of Name model objects. There must be at least one.

Muli-Part Attachments

file [required] The image file. A variety of formats are supported.

Result

Image model object.

Image: Count

Finds the total number of PhyloPic images.


Authorization

None

Result

An integer

Image: Delete

Removes an image from the database.


Authorization

Contributor or Administrator

URL

http://phylopic.org/api/a/image/{imageUID}/delete

URL Parameters

imageUID The UUID of the image.

Result

true

Image: Edit

Edits the information and/or files for an existing image.


Authorization

Contributor or Administrator

URL

http://phylopic.org/api/a/image/{imageUID}/edit

URL Parameters

imageUID [required] The UUID of the image.

POST Parameters

credit [optional] Credit for this image. If omitted, the value will not be changed.
  licenseURL [optional] The URL of the license for this image. See the Image model specification for a list of valid URLs. If omitted, the value will not be changed. The license may not be changed to a license that is stricter than the current one.
  nameUIDsToAdd [optional] A space-separated list of UUIDs of Name model objects to add to the image. If omitted, none will be added.
  nameUIDsToRemove [optional] A space-separated list of UUIDs of Name model objects to remove from the image. All synonyms of the specified names will be removed as well. If omitted, none will be removed.

Muli-Part Attachments

file [optional] A new image file to replace the existing one.

Result

Image model object (updated).

Image: List

Lists images in chronological order, from most to least recently modified.


Authorization

None

URL

http://phylopic.org/api/a/image/list/{start}/{length}

URL Parameters

start The index to start with. Using 0 starts with the most recently-submitted image.
  length The number of images to list.

GET Parameters

options [optional] Space-separated list of options for the result value.

Result

A list of image model objects.

Image: Time Range

Lists images within a given time range, from most to least recent.


Authorization

None

URL

http://phylopic.org/api/a/image/list/{timestamp}/{from}/{to}
or
http://phylopic.org/api/a/image/list/{timestamp}/{from}

URL Parameters

timestamp [required] Either "modified" (to go by the last time the image file was modified) or "submitted" (to go by the time the image was first submitted).
  from [required] A timestamp string, in "YYYY-MM-DD-HH-MM-SS" format, telling the earliest time to retrieve images for.

All numbers past the year are optional. For example, these are acceptable: "2011-10-29-20-30", "2011-10-29-20", "2011-10-29", "2011-10", and "2011". Omitted numbers indicate the lowest possible value for that number, for example, "2011" indicates "2011-01-01-00-00-00" (2011 January 1, midnight).

Numbers in the string do not need to be padded. For example, this is acceptable: "2011-1-1-0-0-0".

The image list will include any images dated at the indicated time.

Use a value of "0" (zero) to include all images up to the to time.
  to [optional] A date-time string, in "YYYY-MM-DD-HH-MM-SS" format, telling the earliest time to retrieve images for.

See the from parameter for more details on the format.

The image list will include any images dated up to, but not including, the indicated time.

If omitted, the list will include all images after the from time.

GET Parameters

options [optional] Space-separated list of options for the result value.

Result

A list of image model objects.

Image: Transfer

Transfers ownership of an image to another user.


Authorization

Contributor or Administrator

URL

http://phylopic.org/api/a/image/{imageUID}/transfer

URL Parameters

imageUID The UUID of the image.

POST Parameters

email [required] The new owner's email address.

Result

true

Name

Retrieves information on a taxonomic name.


Authorization

None

URL

http://phylopic.org/api/a/name/{nameUID}

URL Parameters

nameUID The UUID of the taxonomic name.

GET Parameters

options [optional] Space-separated list of options for the result value.

Result

Name model object.

Name: Add

Adds a new name to the database.


Authorization

User

URL

http://phylopic.org/api/a/name/add

POST Parameters

citationStart [optional] Integer indicating where in the string the citation begins. If not included, an algorithm is used to guess whether the string has a citation and, if so, where it begins. If set to 0, this indicates that the string does not include a citation. If type is set to "vernacular", citationStart is automatically null.
  options [optional] Space-separated list of options for the result value.
  string [required] The string of the name.
  type [optional] The type of the name, either "scientific" or "vernacular". If not set, "scientific" is assumed.
  uri [optional] The URI of the name. If not set, a URI based on the automatically generated UUID is used.

Result

Name model object.

Name: Edit

Updates a taxonomic name.


Authorization

Contributor or Administrator

URL

http://phylopic.org/api/a/name/{nameUID}/edit

URL Parameters

nameUID The UUID of the taxonomic name.

POST Parameters

citationStart [optional] Integer indicating where in the string the citation begins. If not included, no change is made. If set to 0, this indicates that the string does not include a citation. If type is set to "vernacular", citationStart is automatically null.
  options [optional] Space-separated list of options for the result value.
  string [optional] The string of the name. If not included, no change is made.
  type [optional] The type of the name, either "scientific or "vernacular. If not included, no change is made.

Result

Name model object.

Name: Images

Searches for images for a taxonomic name.


Authorization

None

URL

http://phylopic.org/api/a/name/{nameUID}/images

URL Parameters

nameUID The UUID of the taxonomic name.

GET Parameters

subtaxa [optional] If set to "true", includes subtaxa in the search.
  supertaxa [optional] If not set to "false", includes supertaxa in the search.
  options [optional] Space-separated list of options for the result value.
  other [optional] If set to "true", includes related taxa in the search.

Result

An object with the following fields, each of which is an array of image model objects: same, subtaxa, supertaxa, other.

Name: Minimal Supertaxa

Finds the minimal common supertaxa for a list of names.


Authorization

None

URL

http://phylopic.org/api/a/name/minSupertaxa

GET Parameters

nameUIDs [required] Space-separated list of UUIDs for taxonomic names.
  options [optional] Space-separated list of options for the result value.

Result

An array of taxon model objects.

Name: Taxonomy

Collects taxonomic data for a name.


Authorization

None

URL

http://phylopic.org/api/a/name/{nameUID}/taxonomy

URL Parameters

nameUID The UUID of the taxonomic name.

GET Parameters

subtaxa [optional] If immediate, returns data for immediate subtaxa ("children"). Otherwise, does not include subtaxa.
  supertaxa [optional] If immediate, returns data for immediate supertaxa ("parents"). If all, returns data for all supertaxa ("ancestors"). Otherwise, does not include supertaxa.
  options [optional] Space-separated list of options for the result value.
  useUBio [optional] If true and there is pending data from uBio that needs to be cached, a list of commands will be passed back instead of the normal result.

Result

The result will always include a field called uBioCommands, which stores a Boolean value. This is true if and only if:

  1. the GET parameter useUBio is "true", and
  2. there is pending data to be downloaded from uBio.

The rest of the result fields depend on this value.

Case 1

If uBioCommands is true, then result is an object with a single field, commands, which is a list of objects representing uBio commands, to be called in order. Each command has two fields:

title
The label to display (in HTML).
url
The API URL to call to complete the command.

Once all commands are loaded, the call can be made again.

Case 2

If uBioCommands is false, then result is an object with two fields:

taxa
A list of all the relevant taxon model objects.
inclusions
A list of ordered pairs (two-member arrays) where the first number indicates a supertaxa and the second indicates a subtaxon. The numbers refer to the index of a taxon in taxa.

Name: Taxonomy (Multiple)

Collects taxonomic data for multiple names.


Authorization

None

URL

http://phylopic.org/api/a/name/taxonomy/multiple

GET Parameters

nameUIDs [required] Space-separated list of Name UUIDs.
  options [optional] Space-separated list of options for the result value.

Result

An object with two fields:

taxa
A list of all the relevant taxon model objects.
inclusions
A list of ordered pairs (two-member arrays) where the first number indicates a supertaxa and the second indicates a subtaxon. The numbers refer to the index of a taxon in taxa.

Note that passing a single UUID is equivalent to using the Taxonomy method with supertaxa set to "all" and useUBio and subtaxa omitted.

Name: Taxonomy Sources

Collects data about the sources for a name's taxonomy.


Authorization

None

URL

http://phylopic.org/api/a/name/{nameUID}/taxonomy/sources

URL Parameters

nameUID The UUID of the taxonomic name.

GET Parameters

options [optional] Space-separated list of options for the result value.

Result

An object with the following fields:

hyponymies
An array of arrays, each one containing (in order): hyperonym UUID, hyponym UUID, disabled flag (Boolean value), array of source URIs
names
An array of name model objects.
sources
An array of source model objects.
synonymies
An array of arrays, each one containing (in order): conserved name UUID, suppressed name UUID, disabled flag (Boolean value), array of source URIs

Name: Toggle

Enables or disables a taxonomic name.


Authorization

Contributor or Administrator

URL

http://phylopic.org/api/a/name/{nameUID}/toggle

URL Parameters

nameUID The UUID of the taxonomic name.

POST Parameters

enabled [optional] A value of "true" or "false", indicating whether the name is to be enabled or disabled. If neither, or not provided, simply uses the opposite of the current value.

Result

Boolean value telling whether the name is enabled.

Name Set

Retrieves information on a set of taxonomic names.


Authorization

None

URL

http://phylopic.org/api/a/name/set/{nameSetUID}

URL Parameters

nameSetUID The UUID of a set of taxonomic names.

GET Parameters

options [optional] Space-separated list of options for the result value.

Result

Name Set model object.

Name Set: Add

Adds a new name set to the database, or retrieves an existing one.


Authorization

None

URL

http://phylopic.org/api/a/name/set/add

GET Parameters

nameUIDs [required] Space-separated list of UUIDs of Name model objects.
  options [optional] Space-separated list of options for the result value.

Result

Name Set model object.

Name Set: Taxonomy

Collects taxonomic data for a set of taxonomic names.


Authorization

None

URL

http://phylopic.org/api/a/name/set/{nameSetUID}/taxonomy

URL Parameters

nameSetUID The UUID of a set of taxonomic names.

GET Parameters

options [optional] Space-separated list of options for the result value.

Result

An object with two fields:

taxa
A list of all the relevant taxon model objects.
inclusions
A list of ordered pairs (two-member arrays) where the first number indicates a supertaxa and the second indicates a subtaxon. The numbers refer to the index of a taxon in taxa.

Synonymy: Add

Adds a synonymy.


Authorization

User

URL

http://phylopic.org/api/a/synonymy/{conservedUID}/{suppressedUID}/add

URL Parameters

conservedUID The UUID of the conserved (preferred) name.
  suppressedUID The UUID of the suppressed name.

Result

true

Synonymy: Flip

Flips a synonymy, so that the name that was conserved is now suppressed, and vice versa.


Authorization

Administrator

URL

http://phylopic.org/api/a/synonymy/{nameAUID}/{nameBUID}/flip

URL Parameters

nameAUID The UUID of one of the names.
  nameBUID The UUID of one the other name.

POST Parameters

options [optional] Space-separated list of options for the result value.

Result

A list of two name model objects: the conserved name followed by the suppressed name.

Synonymy: Toggle

Enables or disables a synonymy.


Authorization

Administrator

URL

http://phylopic.org/api/a/synonymy/{conservedUID}/{suppressedUID}/toggle

URL Parameters

conservedUID The UUID of the conserved (preferred) name.
  suppressedUID The UUID of the suppressed name.

POST Parameters

enabled [optional] A value of "true" or "false". If neither, or not provided, simply uses the opposite of the current value.

Result

Boolean value telling whether the synonymy is enabled.

uBio Classification: Update

Updates data for a classification node from uBio.


Authorization

None

URL

http://phylopic.org/api/a/ubio/{classificationbankID}/update

URL Parameters

classificationbankID The identifier for a node in uBio Classificationbank.

Result

true

uBio Name

Retrieves information on a taxonomic name that is in uBio Namebank.


Authorization

None

URL

http://phylopic.org/api/a/ubio/name/{namebankID}

URL Parameters

namebankID The identifier for a name in uBio Namebank.

GET Parameters

options [optional] Space-separated list of options for the result value.

Result

Name model object.

uBio Name: Update

Updates the data for a uBio name.


Authorization

None

URL

http://phylopic.org/api/a/ubio/name/{namebankID}/update

URL Parameters

namebankID The identifier for a name in uBio Namebank.

Result

true