Multiple matches found. Please select one.
No matches were found. Please check the spelling. You can adjust the spelling and try the search again, or, if you are sure it is correct, you can add this name to the PhyloPic database.
Check out the beta version of the newer, faster PhyloPic 2.0.
This version of the API will be replaced in the future. To read the specifications for the new API (currently in development), go here: PhyloPic OpenAPI Documentation.
If interested, you may sign up for email updates below:
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.
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.
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:
creditnull, if licenseURL indicates a public domain license.
directNamestaxa.)
licenseURL"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/"
modifiedYYYY-MM-DD HH:MM:SS.
pngFilesA list of PNG file model objects.
Note Every image has two PNG files that are not included in this list:
http://phylopic.org/assets/images/submissions/{imageUID}.thumb.png; andhttp://phylopic.org/assets/images/submissions/{imageUID}.icon.png.submittedYYYY-MM-DD HH:MM:SS.
taxadirectNames as well as any taxa that the image is inferred to represent.
uidcitationStartnull.
htmlnamebankIDnull.
roottrue, this name has no hyperonyms (names of supertaxa).
(Should only be true for Panbiota/Vitae.)
stringtype"scientific or "vernacular.
uidurivotesuidheighturlwidthtitleuriurlcanonicalNamenames is absent.
icon
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.
illustratedfalse it may still be possible to search for an approximation.
allowContactemailallowContact is false and the request is not made by the user themself or a manager.
firstNameallowContact is false and the request is not made by the user themself or a manager.
lastNameallowContact is false and the request is not made by the user themself or a manager.
uidGets information on a user account.
http://phylopic.org/api/a/account
or
http://phylopic.org/api/a/account/{userUID}
userUID
[optional]
User's universally unique identifier.
If omitted, uses the currently logged-in user.
Registers a new user. If successful, an email is sent to the user with further instructions.
http://phylopic.org/api/a/account/add
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.
true
Checks whether the user is currently logged in, and what their role is if so.
null.
Otherwise, a string with the user's role, either "contributor" or "administrator".
Updates the current user's information.
http://phylopic.org/api/a/account/edit
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.
Finds all the images a user has submitted. (Note: these are not all necessarily credited to the user.)
allowContact setting is set to true)
allowContact setting is set to false)
http://phylopic.org/api/a/account/images/{start}/{length}
or
http://phylopic.org/api/a/account/{userUID}/images/{start}/{length}
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.
Counts the number of images a user has submitter.
allowContact setting is set to true)
allowContact setting is set to false)
http://phylopic.org/api/a/account/images/count
or
http://phylopic.org/api/a/account/{userUID}/images/count
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.)
Logs a registered user in.
http://phylopic.org/api/a/account/login
email
[required]
User's email address.
password
[required]
User's password.
Logs the current user out.
http://phylopic.org/api/a/account/logout
true
Initiates a request to reset a user's password, emailing them a link with a key.
http://phylopic.org/api/a/account/password/reset/request
email
[required]
User's email address.
true
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).
http://phylopic.org/api/a/hyponymy/{hyperonymUID}/{hyponymUID}/add
hyperonymUID
The UUID of the hyperonym (supertaxon's name).
hyponymUID
The UUID of the hyponym (subtaxon's name).
Enables or disables a hyponymy. (See Hyponymy Add.)
http://phylopic.org/api/a/hyponymy/{hyperonymUID}/{hyponymUID}/toggle
hyperonymUID
The UUID of the hyperonym (supertaxon's name).
hyponymUID
The UUID of the hyponym (subtaxon's name).
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.
Retrieves information about an image.
http://phylopic.org/api/a/image/{imageUID}
imageUID
The UUID of the image.
options
[optional]
Space-separated list of options for the result value.
Creates a new image in the PhyloPic gallery.
http://phylopic.org/api/a/image/add
or
http://phylopic.org/api/a/image/{imageUID}/add
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.
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.
file
[required]
The image file.
A variety of formats are supported.
Finds the total number of PhyloPic images.
Removes an image from the database.
http://phylopic.org/api/a/image/{imageUID}/delete
imageUID
The UUID of the image.
true
Edits the information and/or files for an existing image.
http://phylopic.org/api/a/image/{imageUID}/edit
imageUID
[required]
The UUID of the image.
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.
file
[optional]
A new image file to replace the existing one.
Lists images in chronological order, from most to least recently modified.
http://phylopic.org/api/a/image/list/{start}/{length}
start
The index to start with.
Using 0 starts with the most recently-submitted image.
length
The number of images to list.
options
[optional]
Space-separated list of options for the result value.
Lists images within a given time range, from most to least recent.
http://phylopic.org/api/a/image/list/{timestamp}/{from}/{to}
http://phylopic.org/api/a/image/list/{timestamp}/{from}
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.
"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).
"2011-1-1-0-0-0".
"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.
from parameter for more details on the format.
from time.
options
[optional]
Space-separated list of options for the result value.
Transfers ownership of an image to another user.
http://phylopic.org/api/a/image/{imageUID}/transfer
imageUID
The UUID of the image.
email
[required]
The new owner's email address.
true
Retrieves information on a taxonomic name.
http://phylopic.org/api/a/name/{nameUID}
nameUID
The UUID of the taxonomic name.
options
[optional]
Space-separated list of options for the result value.
Adds a new name to the database.
http://phylopic.org/api/a/name/add
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.
Updates a taxonomic name.
http://phylopic.org/api/a/name/{nameUID}/edit
nameUID
The UUID of the taxonomic name.
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.
Searches for images for a taxonomic name.
http://phylopic.org/api/a/name/{nameUID}/images
nameUID
The UUID of the taxonomic name.
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.
same,
subtaxa,
supertaxa,
other.
Finds the minimal common supertaxa for a list of names.
http://phylopic.org/api/a/name/minSupertaxa
nameUIDs
[required]
Space-separated list of UUIDs for taxonomic names.
options
[optional]
Space-separated list of options for the result value.
Finds the taxa whose names match a piece of text.
http://phylopic.org/api/a/name/search
text
[required]
The text string to search on.
options
[optional]
Space-separated list of options for the result value.
Collects taxonomic data for a name.
http://phylopic.org/api/a/name/{nameUID}/taxonomy
nameUID
The UUID of the taxonomic name.
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.
The result will always include a field called uBioCommands, which stores a Boolean value.
This is true if and only if:
useUBio is "true", andThe rest of the result fields depend on this value.
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:
titleurlOnce all commands are loaded, the call can be made again.
If uBioCommands is false, then result is an object with two fields:
taxainclusionstaxa.
Collects taxonomic data for multiple names.
http://phylopic.org/api/a/name/taxonomy/multiple
options
[optional]
Space-separated list of options for the result value.
An object with two fields:
taxainclusionstaxa.
Note that passing a single UUID is equivalent to using the Taxonomy method with supertaxa set to "all" and useUBio and subtaxa omitted.
Collects data about the sources for a name's taxonomy.
http://phylopic.org/api/a/name/{nameUID}/taxonomy/sources
nameUID
The UUID of the taxonomic name.
options
[optional]
Space-separated list of options for the result value.
An object with the following fields:
hyponymies
names
sources
synonymies
Enables or disables a taxonomic name.
http://phylopic.org/api/a/name/{nameUID}/toggle
nameUID
The UUID of the taxonomic name.
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.
Retrieves information on a set of taxonomic names.
http://phylopic.org/api/a/name/set/{nameSetUID}
nameSetUID
The UUID of a set of taxonomic names.
options
[optional]
Space-separated list of options for the result value.
http://phylopic.org/api/a/name/set/8d9a9ea3-95cc-414d-1000-4b683ce04be2?options=names+string
Adds a new name set to the database, or retrieves an existing one.
http://phylopic.org/api/a/name/set/add
options
[optional]
Space-separated list of options for the result value.
Collects taxonomic data for a set of taxonomic names.
http://phylopic.org/api/a/name/set/{nameSetUID}/taxonomy
nameSetUID
The UUID of a set of taxonomic names.
options
[optional]
Space-separated list of options for the result value.
http://phylopic.org/api/a/name/set/8d9a9ea3-95cc-414d-1000-4b683ce04be2/taxonomy?options=string
An object with two fields:
taxainclusionstaxa.
Adds a synonymy.
http://phylopic.org/api/a/synonymy/{conservedUID}/{suppressedUID}/add
conservedUID
The UUID of the conserved (preferred) name.
suppressedUID
The UUID of the suppressed name.
true
Flips a synonymy, so that the name that was conserved is now suppressed, and vice versa.
http://phylopic.org/api/a/synonymy/{nameAUID}/{nameBUID}/flip
nameAUID
The UUID of one of the names.
nameBUID
The UUID of one the other name.
options
[optional]
Space-separated list of options for the result value.
Enables or disables a synonymy.
http://phylopic.org/api/a/synonymy/{conservedUID}/{suppressedUID}/toggle
conservedUID
The UUID of the conserved (preferred) name.
suppressedUID
The UUID of the suppressed name.
enabled
[optional]
A value of "true" or "false".
If neither, or not provided, simply uses the opposite of the current value.
Updates data for a classification node from uBio.
http://phylopic.org/api/a/ubio/{classificationbankID}/update
classificationbankID
The identifier for a node in uBio Classificationbank.
true
Retrieves information on a taxonomic name that is in uBio Namebank.
http://phylopic.org/api/a/ubio/name/{namebankID}
namebankID
The identifier for a name in uBio Namebank.
options
[optional]
Space-separated list of options for the result value.
Finds uBio Classificationbank nodes for a uBio Namebank name.
http://phylopic.org/api/a/ubio/name/{namebankID}/classification/search
namebankID
The identifier for a name in uBio Namebank.
true
Updates the data for a uBio name.
http://phylopic.org/api/a/ubio/name/{namebankID}/update
namebankID
The identifier for a name in uBio Namebank.
true