Arkive API

Method: portlet


Retrieve a graphical image link to Arkive species, photos and videos.

Terms and conditions

Please read the API terms of use and these conditions:

  • The displayed thumbnail may be used as a link from your website to Arkive's online content for private, scientific, conservation or educational purposes only. Portlets may NOT be used within Apps.


Required parameters have a fixed location in the request URL and optional parameters are named in the query string:{searchBy}/{searchFor}/{quantity}?{optional name 1}={optional value 1}&{optional name 2}={optional value 2}...

All parameters and values are case sensitive unless specified.

Required parameters
Name Values Description
searchBy latin, vaultId The field to search by.
searchFor any search string What to search for. This parameter is case insensitive.
When searchBy = latin: use a species' scientific name.
When searchBy = vaultId: use a specific asset's GUID, found in the path to the asset image.
quantity any integer greater than or equal to 0 The number of portlets required.
0 = A single random portlet from the matching collection of portlets.
n = n portlets, determined by optional ordering parameter below.
Ignored when searchBy = vaultId.

Optional parameters

Name Values Valid when Default Description
outputFormat json, text always json json: Return a JSON encapsulated result
text: Return a single chunk of text (XHTML) - not recommended - exceptional circumstances can result in JSON error messages being returned instead.
media all, images, videos always all Limit the results to a particular type of media item
images returns Arkive photos
slideshow yes, no always no Automatically display the appropriate Arkive photo slideshow when visitors click on the portlet
linkTarget any string always no target attribute is output Set the anchor target attribute for the link back to Arkive
encapsulation span, div, table, none outputFormat=text none Whether to surround each portlet in a particular HTML structure
hMargin any positive integer, n outputFormat=text no specific margin is set Set the left and right margins on the chosen encapsulating element to n
vMargin any positive integer, n outputFormat=text no specific margin is set Set the top and bottom margins on the chosen encapsulating element to n
cellPadding any positive integer, n outputFormat=text
no specific cellPadding is set Set the cell padding on the encapsulating table to n
itemsPerTableRow any positive integer, n outputFormat=text
3 Display a maximum of n items per table row
layout inline, block outputFormat=text
encapsulation=div or span
no specific layout is set Allows one to change the style of the encapsulating div or span to a non-standard value


An array of 0 or more portlets.