API, Blog, PHP

State Library of South Australia Photograph Collection API

The State Library of South Australia (SLSA) made a very comprehensive compilation of historical photographs and collections available some time back covering the 19th and 20th century (they advertise the collection as "photographs relating to South Australia feature localities across the state, houses and buildings, portraits, social and historical events, industry, farming, and transport").

The collection of around 81000 images provides an amazing insight into the formative years of the state. As we've done (and will continue to do) with other similar collections, we've built an API that enables the collection to be browsed, or searched via keyword or category tag. 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/sa/sa.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, search, or tag. 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 or tag, 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 via a category tag (the tags are discussed in a little more detail below). A basic search, or simply browsing all paginated results, returns data in a similar manner. Request made was as follows: sa.json?apikey=xxx&pg=1&number=10&type=tag&search=police.

Array

(

[code] => 200

[status] => 200

[message] => OK

[source] => State Library of South Australia

[page] => 1

[number] => 10

[pages] => 17

[total] => 169

[search] => Array

(

[type] => tag

[term] => police

)

[results] => Array

(

[0] => Array

(

[itemid] => b20185066

[title] => Heavitree Gap, Alice Springs

[date] => 1900

[summary] => Old Police Station south side of Heavitree Gap

[category_string] => police stations,northern territory,alice springs

=> Array

(

[nlsa] => http://images.slsa.sa.gov.au/mpcimg/22500/B22483.jpg

[local] => 1900/B22483.jpg

)

[1] => Array

(

[itemid] => b20185170

[title] => Police Station Heavitree Gap

[date] => 1900

[summary] => Police station, Heavitree Gap

[category_string] => police stations,northern territory,alice springs region

=> Array

(

[nlsa] => http://images.slsa.sa.gov.au/mpcimg/22000/B21911.jpg

[local] => 1900/B21911.jpg

)

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

Array

(

[code] => 200

[status] => 200

[message] => OK

[source] => State Library of South Australia

[results] => Array

(

[itemid] => b21250984

[title] => Old Gum Tree at Glenelg

[date] => 1910

[summary] => Mrs C.F. Rischbieth with Mary and her mother, Mrs W.I. Newman, pictured at the old Gum Tree at Glenelg

[year] =>

=> Array

(

[category_string] => old gum tree (glenelg, s. aust.),south australia,glenelg

[category_array] => Array

(

[0] => Array

(

[0] => Old Gum Tree (Glenelg, S. Aust.)

)

[1] => Array

(

[0] => Historic trees

[1] => South Australia

[2] => Glenelg

)

[geo] => Array

(

[latitude] => -34.98

[longitude] => 138.51

)

=> Array

(

[nlsa] => http://images.slsa.sa.gov.au/mpcimg/38250/B38035A.jpg

[local] => 1910/B38035A.jpg

)

[reference] => Array

(

[recordid] => b2125098

[xmlid] => b21250984

[photodetails] => Photograph 15.2 cm x 20.3 cm (image) 24.8 cm x 30 cm

)

Categories and Tags

Searching by tag is actually searching for a category item. The manner in which the categories are manufactured (as shown above) is as a hierarchical structure. For example, the above item is indexed via Historic trees -> South Australia -> Glenelg. We took all the menu items and flatten them as tags - this works nicely to connect all associated images.

Reference Data

The reference array key provides details of the record as hosted on the SLSA server. The image record may be returned via http://www.catalog.slsa.sa.gov.au/record={recordid}, and XML data can be retrieved via http://www.catalog.slsa.sa.gov.au/xrecord={xmlid}.

Image Data

The links provided by the SLSA are for a low quality image. Linking to the permanent record as described above provides access to the full resolution version. A copyright may apply.

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 lowish quality images may be downloaded via our client area (22GB). Our image structure is as follows: {date}/{basename(nlsa_image.jpg)} and is retained in the download file.

Sample PHP Functions

The following functions are examples only and do nothing other than return a resulting array.

Browsing or Searching Results

<?php

State Library of South Australia Photograph Collection API

https://www.beliefmedia.com.au/south-australia-history-api

function beliefmedia_slsa_sa_photos($page = '', $number = '', $type = false, $search = false, $apikey = 'xxxxxxxxxx') {

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

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

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

$data = @file_get_contents('http://api.beliefmedia.com/australia/sa/sa.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 South Australia Photograph Collection API

https://www.beliefmedia.com.au/south-australia-history-api

function beliefmedia_slsa_sa_photo_detail($id, $apikey = 'xxxxxxxxxx') {

$data = @file_get_contents('http://api.beliefmedia.com/australia/sa/sa.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

Only limited results include geo-tagging. We did build in a function to return results relative to a location but the dataset isn't large enough to make it effective.
Around 100 image results returned a 404 error. A number of other results relate to a gallery hosted on the NLSA website, and they don't reference any particular image. We've removed these records from our database making 80000 images available. Various databases are available from our client area; some include the erroneous entries while others exclude them.
More detailed documentation is available from within our client areas.
Additional South Australian sources will be made available soon. Most of the material made available via the SLSA are exceptional.

■ ■ ■

Download our complimentary 650-page guide on marketing for mortgage brokers. We'll show you exactly how we generate billions in volume for our clients.