Australia's Leading Digital Marketing Experts. T. 1300 235 433  |  Aggregation Enquires Welcome

State Library of South Australia Photograph Collection API

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.

id

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.

1
Array
2
(
3
    [code] => 200
4
    [status] => 200
5
    [message] => OK
6
    [source] => State Library of South Australia
7
    [page] => 1
8
    [number] => 10
9
    [pages] => 17
10
    [total] => 169
11
    [search] => Array
12
        (
13
            [type] => tag
14
            [term] => police
15
        )
16
 
17
    [results] => Array
18
        (
19
            [0] => Array
20
                (
21
                    [itemid] => b20185066
22
                    [title] => Heavitree Gap, Alice Springs
23
                    [date] => 1900
24
                    [summary] => Old Police Station south side of Heavitree Gap
25
                    [category_string] => police stations,northern territory,alice springs
26
                    [image] => Array
27
                        (
28
                            [nlsa] => http://images.slsa.sa.gov.au/mpcimg/22500/B22483.jpg
29
                            [local] => 1900/B22483.jpg
30
                        )
31
 
32
                )
33
 
34
            [1] => Array
35
                (
36
                    [itemid] => b20185170
37
                    [title] => Police Station Heavitree Gap
38
                    [date] => 1900
39
                    [summary] => Police station, Heavitree Gap
40
                    [category_string] => police stations,northern territory,alice springs region
41
                    [image] => Array
42
                        (
43
                            [nlsa] => http://images.slsa.sa.gov.au/mpcimg/22000/B21911.jpg
44
                            [local] => 1900/B21911.jpg
45
                        )
46
 
47
                )
48
 
49
        )
50
 
51
)

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:

1
Array
2
(
3
    [code] => 200
4
    [status] => 200
5
    [message] => OK
6
    [source] => State Library of South Australia
7
    [results] => Array
8
        (
9
            [itemid] => b21250984
10
            [title] => Old Gum Tree at Glenelg
11
            [date] => 1910
12
            [summary] => Mrs C.F. Rischbieth with Mary and her mother, Mrs W.I. Newman, pictured at the old Gum Tree at Glenelg
13
            [year] =>
14
            [category] => Array
15
                (
16
                    [category_string] => old gum tree (glenelg, s. aust.),south australia,glenelg
17
                    [category_array] => Array
18
                        (
19
                            [0] => Array
20
                                (
21
                                    [0] => Old Gum Tree (Glenelg, S. Aust.)
22
                                )
23
 
24
                            [1] => Array
25
                                (
26
                                    [0] => Historic trees
27
                                    [1] => South Australia
28
                                    [2] => Glenelg
29
                                )
30
 
31
                        )
32
 
33
                )
34
 
35
            [geo] => Array
36
                (
37
                    [latitude] => -34.98
38
                    [longitude] => 138.51
39
                )
40
 
41
            [image] => Array
42
                (
43
                    [nlsa] => http://images.slsa.sa.gov.au/mpcimg/38250/B38035A.jpg
44
                    [local] => 1910/B38035A.jpg
45
                )
46
 
47
            [reference] => Array
48
                (
49
                    [recordid] => b2125098
50
                    [xmlid] => b21250984
51
                    [photodetails] => Photograph  15.2 cm x 20.3 cm (image)  24.8 cm x 30 cm
52
                )
53
 
54
        )
55
 
56
)

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

1
<?php 
2
/*
3
 State Library of South Australia Photograph Collection API
4
 https://www.beliefmedia.com.au/south-australia-history-api
5
*/
6
 
7
function beliefmedia_slsa_sa_photos($page = '', $number = '', $type = false, $search = false, $apikey = 'xxxxxxxxxx') {
8
 
9
  if ($page == '') $page = '1';
10
  if ($number == '') $number = '20';
11
  $type = ($type == 'browse') ? 'browse' : 'type=' . $type . '&search=' . str_replace(' ', '+', $search);
12
 
13
  $data = @file_get_contents('http://api.beliefmedia.com/australia/sa/sa.json?apikey=' . $apikey . '&pg=' . $page . '&number=' . $number . '&' . $type);
14
  if ($data === false) return false;
15
 
16
  $data = json_decode($data, true);
17
  if ($data === false) return false;
18
 
19
  /* Likely return array of errors with code & message */
20
  if ($data['code'] != '200') return $data['message'];
21
 
22
 return (array) $data;
23
}

Returning Single Result

1
<?php 
2
/*
3
 State Library of South Australia Photograph Collection API
4
 https://www.beliefmedia.com.au/south-australia-history-api
5
*/
6
 
7
function beliefmedia_slsa_sa_photo_detail($id, $apikey = 'xxxxxxxxxx') {
8
 
9
  $data = @file_get_contents('http://api.beliefmedia.com/australia/sa/sa.json?apikey=' . $apikey . '&id=' . $id);
10
  if ($data === false) return false;
11
 
12
  $data = json_decode($data, true);
13
  if ($data === false) return false;
14
 
15
  /* Likely return array of errors with code & message */
16
  if ($data['code'] != '200') return $data['message'];
17
 
18
 /* Do something with data */
19
 return (array) $data;
20
}

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 650-page guide on Finance Marketing. We'll show you exactly how we generate Billions in volume for our clients.

  AUS Eastern Standard Time (Virginia)

  Want to have a chat?
 

Like this article?

Share on facebook
Share on Facebook
Share on twitter
Share on Twitter
Share on linkedin
Share on Linkdin
Share on pinterest
Share on Pinterest

Leave a comment