API, Blog, PHP

State Library of Queensland Photograph Collection API

Back in 2013, and then updated in 2015, the State Library of Queensland made around 50,000 copyright-expired images available via a 'Picture Queensland' collection. We took the fairly comprehensive CSV and XML data and created our own archive (of pre-1954 photographs) with a full-featured API to browse, search, and retrieve images. While the database is part of another one of our fairly broad projects, the collection in isolation is excellent, and its one we make available to all of our current and former clients. A WordPress plugin available via our client area creates a full library of the images with a search function on your own website.

The Result

Access to data is via the following endpoint: http://api.beliefmedia.com/australia/qld/qld.json. A number of parameters determine what information is returned.

If returning details for a single image, the image itemid is required along with your API Key. If an ID is passed via the URL, all other parameters will be ignored.

type & search

The type can be browse or search. If no type is defined and no id is present in the URL (to return a single result), browse will be used. If the type is search, a search term must be provided.

pg & number

The pg parameter determined the page to be returned. number determines how many results will be shown.

■ ■ ■

The first result shows how our JSON unfolds when searching a specific term or browsing results. A basic search, or simply browsing all paginated results, returns data in a similar manner. Request made was as follows: qld.json?apikey=xxx&pg=1&number=10&search=soldier.

Array

(

[code] => 200

[status] => 200

[message] => OK

[source] => State Library of Western Australia

[page] => 1

[number] => 30

[pages] => 14

[total] => 421

[search] => Array

(

[type] => search

[term] => soldier

)

[results] => Array

(

[0] => Array

(

[itemid] => VM

[title] => Japanese General Adachi disembarking from a plane in Wewak, ready to surrender to the Australian Army, 1945

[creator] => Unidentified

[year] => 1945

[subject] => soldiers aeroplanes Japanese military uniforms World War II

[description] => Lieutenant General Hatazo Adachi (Commander Japanese 18th Army) arriving to meet with Major General Horace Robertson (GOC 6th Australian Division) where he handed over his sword and signed paperwork for the unconditional surrender of his forces in New Guinea, Cape Wom 13th September 1945. (Information taken from: Internet database 2005, retreived April 2005, from )

[location] => Wewak, New Guinea

=> Array

(

[full] => http://bishop.slq.qld.gov.au:80/webclient/DeliveryManager?pid=100129&custom_att_3=NLA

[thumbnail] => http://bishop.slq.qld.gov.au:80/webclient/DeliveryManager?pid=100130

[local_image] => 1945/VM.jpg

[local_thumbnail] => 1945/VM-t.jpg

)

[.. SNIP ..]

[29] => Array

(

[itemid] => AWj

[title] => Pen for scrap aluminium donations to the war cause, Brisbane, 1942

[creator] => Unidentified

[year] => 1942

[subject] => soldiers men's clothing and accessories children's clothing hats enclosures military uniforms World War II - Brisbane, 1942 Brisbane (Qld.)

[description] => Soldiers and a young boy are studying the donations inside the wooden pen. A well dressed gentleman stands to one side.

[location] => Brisbane, Queensland

=> Array

(

[full] => http://bishop.slq.qld.gov.au:80/webclient/DeliveryManager?pid=102827&custom_att_3=NLA

[thumbnail] => http://bishop.slq.qld.gov.au:80/webclient/DeliveryManager?pid=102829

[local_image] => 1942/AWj.jpg

[local_thumbnail] => 1942/AWj-t.jpg

)

To return details for a single result we provide only our apikey and the itemid. So, qld.json?apikey=xxxx&id=k5 returns the following:

Array

(

[code] => 200

[status] => 200

[message] => OK

[source] => State Library of Queensland

[data] => Array

(

[itemid] => k5

[title] => Staged photograph taken at the Trocadero

[alternative_title] =>

[creator] => Unidentified

[subject] => evening clothes backdrops Social, 1930 - 1940 Brisbane (Qld.)

[description] => Staged photograph of three couples leaning over the bow of a boat, part of the evening festivities at the Trocadero in South Brisbane.

[publisher] => John Oxley Library, State Library of Queensland

[contributor] =>

[date] => ca. 1940

[year] => 1940

=> Array

(

[full] => http://bishop.slq.qld.gov.au:80/webclient/DeliveryManager?pid=100001&custom_att_3=NLA

[thumbnail] => http://bishop.slq.qld.gov.au:80/webclient/DeliveryManager?pid=100002

[local_image] => images/1940/k5.jpg

[local_thumbnail] => images/1940/k5-t.jpg

[digiviewer] => 67079

[identifier] => 79937

[format] => Array

(

[type] => Digital format: image/jpeg

[details] => Original format: copy print : b&w

)

[geo] => Array

(

[location] => Brisbane, Queensland

[latitude] => -27.46888

[longitude] => 153.022827

)

[reference] => Array

(

[related] => Array

(

)

=> Array

(

[0] => Picture Queensland

[1] => State Library of Queensland : digital image collection

)

[category_string] => picture queensland,state library of queensland : digital image collection

)

[rights] => Copyright expired. For further information http://www.slq.qld.gov.au/home/copyright

)

Reference Data

The reference array key provides details of the record as hosted on the SLQLD server. The related array, for example, provides links to related material or 'see more' galleries. Other data associated with the image is documented in more details in our client area. The digiviewer value, for example, is associated with the DigiToolViewer used to view high quality scans (http://hdl.handle.net/10462/deriv/{digiviewer}), and the identifier is usually a Negative number.

Image Data

The image links provided by the SLQLD are of reasonable web quality. Linking to the permanent record as described above provides access to the full resolution version.

We've copied all images locally, and each image reference on our own server is returned in the JSON data. A zip file containing all the images and thumbnails may be downloaded via our client area (22.45GB). Our image structure is as follows: images/{year}/{itemid.jpg}, and this structure is retained in the download file.

Sample PHP Functions

The following are the most basic of functions necessary to retrieve data. An API Key is provided to all clients and is available to others upon request.

Browsing or Searching Results

<?php

State Library of Queensland Photograph Collection API

https://www.beliefmedia.com.au/slqld-photograph-api

function beliefmedia_slqld_photos($page = '', $number = '', $type = false, $search = false, $apikey = 'xxxxx') {

if ($page == '') $page = '1';

if ($number == '') $number = '20';

if ($type === false) $type = 'browse';

$type = ($type == 'browse') ? 'browse' : 'type=' . $type . '&search=' . str_replace(' ', '+', $search);

$data = @file_get_contents('http://api.beliefmedia.com/australia/qld/qld.json?apikey=' . $apikey . '&pg=' . $page . '&number=' . $number . '&' . $type);

if ($data === false) return false;

$data = json_decode($data, true);

if ($data === false) return false;

/* Likely return array of errors with code & message */

if ($data['code'] != '200') return $data['message'];

return (array) $data;

}

Returning Single Result

<?php

State Library of Queensland Photograph Collection API

https://www.beliefmedia.com.au/slqld-photograph-api

function beliefmedia_slqld_photos_detail($id, $apikey = 'xxxxx') {

$data = @file_get_contents('http://api.beliefmedia.com/australia/qld/qld.json?apikey=' . $apikey . '&id=' . $id);

if ($data === false) return false;

$data = json_decode($data, true);

if ($data === false) return false;

/* Likely return array of errors with code & message */

if ($data['code'] != '200') return $data['message'];

/* Do something with data */

return (array) $data;

}

If the code returns anything other than 200 an error has occurred. The most common error is 404 (not found), and this applies when a request is made for an image record or paginated result that doesn't exist.

Considerations

A large number of results are geo-tagged. You may search results within a specific radius of a latitude and longitude with the type of geo (type=geo&lat=xxx&lng=xxx). Documentation available in our client area.
We'll be modifying the subject field soon than later (the default field is a little bit of a mess). If you plan on using this data in an application we suggest you hold off for a couple of weeks.