ARKive API

Code examples

Some examples of requests you can make to each method are outlined below or you can view complete code examples which indicate how to handle the JSON output from the example requests.

Method HTTP GET request URL example Description
portlet http://www.arkive.org/api/example-key/portlet/latin/megaptera novaeangliae/1 Return a thumbnail link to the landing page for the humpback whale
portlet http://www.arkive.org/api/example-key/portlet/latin/megaptera novaeangliae/0 Return a random thumbnail link to an image or video of the humpback whale
portlet http://www.arkive.org/api/example-key/portlet/latin/megaptera novaeangliae/10?media=videos&order=ARKiveDefault Return thumbnail links to the first 10 videos of the humpback whale in the same order used on the ARKive website.
portlet http://www.arkive.org/api/example-key/portlet/vaultId/B60C9E49-2D4B-4BE9-8E82-68410E220FAD/1?slideshow=yes Return a thumbnail link to a specific ARKive asset and play the ARKive slideshow when the visitor arrives at ARKive.

Complete examples

PHP

The following example requires PHP 5.2 or greater - third party scripts may assist getting this to work on earlier versions.

function arkiveAPI()
{
    /*******************************
    Define the variables you need to perform the request
    *******************************/

    /*  Map to a variable containing the species scientific name */  
    $speciesName = 'Aceros Narcondami';

    /*  This is your unique API key provided by ARKive/Wildscreen */
    $arkiveAPIKey = 'example-key';
    		
    // Quantity to search for
    // 0 = one random result
    // 1 = the overview/highlighted image
    // All other positive integers output the requested quantity in the default order
    // If there are fewer items than requested, all available items will be returned
    $quantity = 1;
    	
    $optionalParameters = "";
    	
    /*******************************
    Example code
    *******************************/

    /* construct the request */
    $requestURL = 'http://www.arkive.org/api/'.$arkiveAPIKey.'/portlet/latin/'.rawurlencode($speciesName).'/'.$quantity.$optionalParameters;

    /*  get portlet data from ARKive API */
    $myJSON = getFile($requestURL);

    // Now we can decode the JSON string to a PHP object (requires PHP 5.2 or greater)
    $decoded = json_decode($myJSON);

    // If there is any error object we will abort (you would want to fail
    // gracefully at this point). 
    if ($decoded->error !== null)
        die("Something is wrong. Maybe the species name did not match our records?");
        // detailed output may be found in $decoded->error->message

    // Some API requests can produce multiple results
    // The results variable may contain 0 or more results (or be null)
    // Only one of error or results will be a non-null value.
    // It is assumed that you will check for error first, then results

    else if ($decoded->results !== null)
    {
        echo("There are ".count($decoded->results)." results.<br/>");
        echo("This is the first result: ".$decoded->results[0]);
    }
    else
        die("All results null. Shouldn't happen but best to assume an error condition just in case.");
}

// The getFile() function can return an error if the remote file download methods are not 
// available in your PHP environment. Please see
// http://www.php-mysql-tutorial.com/wikis/php-tutorial/reading-a-remote-file-using-php.aspx for other approaches
function getFile($url)
{
    $myJSON = "";
    if (function_exists('curl_init')) {
        $curl_handle=curl_init();
        curl_setopt($curl_handle,CURLOPT_URL,$url);
        curl_setopt($curl_handle,CURLOPT_CONNECTTIMEOUT,2);
        curl_setopt($curl_handle,CURLOPT_RETURNTRANSFER,1);
        $myJSON = curl_exec($curl_handle);
        curl_close($curl_handle);
    } else
    {
        $myJSON = file_get_contents($url);
    }
    return $myJSON;
}