Advanced use

If the Embed Arkive content feature does not work for your website, you may be able to use the information below to get Arkive content into your website.

The Wordpress approach below should work for other blogging or content management systems but we have only tested on Wordpress so you may need the help of your website technical administrator.

Wordpress users

Wordpress places restrictions on the use of inline Javascript within the content of posts, and is therefore incompatible with the default method of embedding Arkive content.

The workaround is to place most of the Javascript in a separate file and insert additional HTML into your posts to reference this file.

HTML code

Place this in every page in which you want to embed Arkive content. Make sure you update the script element src attribute with the path to the JS file on your server.

You also need to update the var definitions with: your API key, the details of the species to be displayed, and the configuration options that achieve the size and layout you want. You can explore the available options by reading the technical details below or by experimenting with the normal embed code generator and inspecting the generated code.

<!-- Replace the first 3 values with your own API key and the details       -->
<!-- for the species you want to display.                                   -->
<!-- Set the 4 configuration options according to your needs.               -->
<script type="text/javascript">
    var arkiveApiKey = 'YOUR KEY HERE',
    arkiveApiSpeciesName = 'Scientific%20name', // note spaces replaced by %20
    //arkiveApiSpeciesId = '00000000-0000-0000-0000-000000000000', 
        // optional, but recommended

    arkiveApiWidth = 320,
    arkiveApiHeight = 355,
    arkiveApiImages = false, // whether to include thumbnails
    arkiveApiText = false; // whether to include species facts / description
</script>
<!-- ensure the src attribute in the following script tag points to your JS file -->
<script type="text/javascript" src="arkive-api-embed.js"></script>
<div id="arkiveIframe"></div>
                    

Setting arkiveApiSpeciesId will ensure that your embedded Arkive content will continue to work even if the species' scientific name is officially changed in the future. There is more detail about this in the technical documentation below.

Javascript code

Place this in a Javascript file and upload it to a web-accessible location on your server.

function arkiveEmbedCallback(data) {
	var iframeCreation = '<iframe id="frame" name="widget" src ="#" 
                                width="100%" height="1" marginheight="0" 
                                    marginwidth="0" frameborder="no"></iframe>';
	var iframe = window.location.protocol + "//" + (data.results[0].url);
	if (data.error != 'null') {
  	    document.getElementById("arkiveIframe").innerHTML = iframeCreation;
	    var iframeAttr = parent.document.getElementById("frame");
	    iframeAttr.height = arkiveApiHeight;
	    iframeAttr.width = arkiveApiWidth + 22;
	    iframeAttr.src = iframe;
    }
}
(function () {
    function async_load() {
        var s = document.createElement('script'); 
        s.type = 'text/javascript';
        s.async = true;
        s.src = 'https://api.arkive.org/v2/embedScript/species/scientificName/' + arkiveApiSpeciesName 
        + '?key=' + arkiveApiKey + (arkiveApiSpeciesId ? '&id=' + arkiveApiSpeciesId : '') + '&mtype=all&w=' 
        + arkiveApiWidth + '&h=' + arkiveApiHeight + '&tn=' + (arkiveApiImages ? 1 : 0) + '&text=' 
        + (arkiveApiText ? 1 : 0) + '&callback=arkiveEmbedCallback';
        var x = document.getElementsByTagName('script')[0];
        x.parentNode.insertBefore(s, x);
    }
    if (window.attachEvent)
        window.attachEvent('onload', async_load);
    else
        window.addEventListener('load', async_load, false);
})();
                    

Technical information

The Arkive API embeds content into your website in two stages.

  1. Javascript request
  2. Iframe request

Configuration parameters are passed to the Arkive API in the Javascript request URL. Javascript that is included in your page will then use the data retrieved from the first request to create an iframe which embeds the Arkive content into your page.

You select the species you want to embed by including its scientific name in the URL as highlighted below.

https://api.arkive.org/v2/embedScript/species/scientificName/<species scientific name>?<Configuration parameters>

The following parameters can be configured:

NameRequiredTypeDescription
keyYesstringYour website's API key. This must be created on our "Add a website" page and the hostname must match the hostname in the referral header submitted by your visitors' web browser
idNostring (UUID)Arkive's unique species ID (a 128bit UUID). If you supply a valid species ID, we can ensure that your embedded content keeps working even if we change the scientific name of the species. If the unique species ID becomes invalid (for example due to two species being merged) we will still try to find a suitable species from the scientific name you supply. Please contact us for more information about our unique IDs and the best ways to discover them.
mtypeYesenum ("all")The type of media to include. Currently only "all" media types are supported which, hopefully temporarilly, includes only images.
wYesintegerWidth in pixels of the iframe you want to create
hYesintegerHeight in pixels of the iframe you want to create
tnYesinteger (0 or 1)Whether to include thumbnails (1) or not (0). Note that thumbnails will never be included if the w parameter is less than 320
textYesinteger (0 or 1)Whether to include species text / facts (1) or not (0)
callbackYesstringThe name of the Javascript function you would like to handle the returned data. This function should create a suitable iframe as demonstrated in the arkiveEmbedCallback function above

You select the species you want to embed by including its scientific name in the URL as highlighted below.
• https://api.arkive.org/v2/embedScript/species/scientificName/<species scientific name>?<Configuration parameters>

And you select the video you want to embed by including its Arkive ‘Vault’' GUID in the URL as highlighted below.
• https://api.arkive.org/v2/embedScript/video/vaultGuid/<GUID>?<Configuration parameters>

The following parameters can be configured:

NameRequiredTypeDescription
keyYesstringYour website's API key. This must be created on our "Add a website" page and the hostname must match the hostname in the referral header submitted by your visitors' web browser
idNo

n/a for videos
string (UUID)Arkive's unique species ID (a 128bit UUID). If you supply a valid species ID, we can ensure that your embedded content keeps working even if we change the scientific name of the species. If the unique species ID becomes invalid (for example due to two species being merged) we will still try to find a suitable species from the scientific name you supply. Please contact us for more information about our unique IDs and the best ways to discover them.
mtypeYesenum ("all")The type of media to include. Currently only "all" media types are supported which, hopefully temporarily, includes only images.
wYesintegerWidth in pixels of the iframe you want to create
hYesintegerHeight in pixels of the iframe you want to create
tnYesinteger (0 or 1)Whether to include thumbnails (1) or not (0). Note that thumbnails will never be included if the w parameter is less than 320
textYesinteger (0 or 1)Whether to include species text / facts (1) or not (0)
callbackYesstringThe name of the Javascript function you would like to handle the returned data. This function should create a suitable iframe as demonstrated in the arkiveEmbedCallback function above

If the first request results in an error, the iframe will not be inserted into your page. Reasons for this include:

  • API key mismatch with site referrer
  • Required parameters not supplied
  • No matching Arkive content found
  • General server errors

If your API key has been suspended, a HTTP status 403 response will be issued and the iframe will not be inserted into your page.

The iframe can display an error page if the species requested is not available (or if the iframe request is made a long time after the Javascript request). It is highly unlikely that either of these situations will arise in normal use.

For an example of dynamically configuring your requests to the Arkive API, please see the Wordpress sample code above. For more advanced usage, please contact us.

Using the information above you should be able to dynamically insert relevant Arkive content for many different species but if you are considering such an approach, please first contact us so that we can disucss if there are more suitable ways to help you embed content.

In particular, alternative approaches may allow you to resolve problems resulting from mismatched scientific names, allow greater flexibility in your site layout and reduce load on our servers.

NB: It is technically possible to directly modify the iframe src attribute to change the configuration without the use of JavaScript but such a modification will only be valid for a short time so is unsuitable for publication.