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

South Australian First World War Photograph Collection API

The database of photographs made available in this article are an extract from a First War collection provided by the State Library of South Australia . Content includes portraits of soldiers, marches, camps, group shots, on location in the Dardanelles, and Western front, and activities on the home front. The relatively small collection of about 2100 images are available via an API, and this article describes its basic use.

A few have asked me (including my mother) why we're making these collections available... and the answer is simple. While all databases will have an accompanying WordPress plugin to make the images available on a website, once all the relevant material is rationalized we'll import them into a common data source so all images can be scheduled to social in batches. The databases simply provides a means to share engaging and compelling content. Once the project nears completion we'll create a few standalone accounts to demonstrate the reach, appeal, and effectiveness that historical media provides. Every single thing we do is because it adds value to the marketing and social efforts of our clients.

The Result

The endpoint for all requests is as follows: https://api.beliefmedia.com/australia/sa/firstwar.json. Additional parameters are passed in the GET request to return relevant data.

To return results for a specific image ID (as obtained via a search or browse request) use firstwar.json?id=b20182235&apikey=xxxx. The returned JSON data unfolds as follows:

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] => b20182235
10
            [title] => Members of the Imperial Force at Morphettville camp
11
            [date] => [approximately 1915]
12
            [year] => 1915
13
            [summary] => GENERAL: 'For King and country' members of the Imperial Force taking the oath at Morphettville camp.
14
            [photographer] =>
15
            [image] => Array
16
                (
17
                    [series] => General Collection
18
                    [nlsa] => https://collections.slsa.sa.gov.au/resource/B+68281/download
19
                    [local] => first-war/1915/b20182235.jpg
20
                    [description] => Photograph  20 cm x 15.5 cm
21
                )
22
 
23
            [category] => Array
24
                (
25
                    [category_string] => world war, 1914-1918,south australia
26
                    [category_array] => Array
27
                        (
28
                            [0] => Array
29
                                (
30
                                    [0] => World War, 1914-1918
31
                                )
32
 
33
                            [1] => Array
34
                                (
35
                                    [0] => Soldiers
36
                                    [1] => South Australia
37
                                )
38
 
39
                        )
40
 
41
                )
42
 
43
            [reference] => Array
44
                (
45
                    [recordid] => b2018223
46
                    [xmlid] => b2018223
47
                )
48
 
49
        )
50
 
51
)

The category array returns each hierarchical menu reference as used by the State Library of South Australia. Those category string contains those same unique values to be used for internal searching and cataloging. The image array returns both the SLSA image download link and a reference to the file as made available in a downloadable zip file containing all images. The relevant reference on the SLSA website can be constructed from the record ID.

Browsing and Searching

Browsing refers to scrolling through paginated results while searching will only return rows that match a specific search term. To browse, use the following: firstwar.json?apikey=xxxx&pg=1&number=20. To search rows, you must explicitly instruct a search with type=search and add a search term; for example: firstwar.json?apikey=xxxx&type=search&search=hospital&number=30.

Both the search and browse JSON returns similar data. They both decode as follows (the following result was a search for "hospital"):

1
Array
2
(
3
    [code] => 200
4
    [status] => 200
5
    [message] => OK
6
    [source] => State Library of South Australia
7
    [page] => 2
8
    [number] => 20
9
    [pages] => 105
10
    [total] => 2103
11
    [search] => Array
12
        (
13
            [type] => browse
14
        )
15
 
16
    [results] => Array
17
        (
18
            [0] => Array
19
                (
20
                    [itemid] => b20271864
21
                    [title] => General Hospital
22
                    [date] => [approximately 1915]
23
                    [summary] => No. 7 Australian General Hospital - Red Cross Motor Transport Storerooms and the Ambulance.
24
                    [category_string] => military hospitals,south australia,keswick,hospitals
25
                    [image] => Array
26
                        (
27
                            [nlsa] => https://collections.slsa.sa.gov.au/resource/B+43342/download
28
                            [local] => first-war/1915/b20271864.jpg
29
                        )
30
 
31
                )
32
 
33
            [1] => Array
34
                (
35
                    [itemid] => b20271876
36
                    [title] => General Hospital, Keswick
37
                    [date] => [approximately 1915]
38
                    [summary] => No. 7 Australian General Hospital views, including the Governor General's visit.
39
                    [category_string] => nurses,south australia,keswick,hospitals
40
                    [image] => Array
41
                        (
42
                            [nlsa] => https://collections.slsa.sa.gov.au/resource/B+43343/download
43
                            [local] => first-war/1915/b20271876.jpg
44
                        )
45
 
46
                )
47
 
48
            [.. SNIP ..]
49
 
50
            [19] => Array
51
                (
52
                    [itemid] => b20307810
53
                    [title] => Recruits, Morphettville
54
                    [date] => 1914
55
                    [summary] => First men from Broken Hill to enlist, they became the original 10th Battalion, 1st A.I.F. (On Hawker's land).
56
                    [category_string] => australia. army. australian imperial force (1914-1921),recruiting, enlistment, etc.,world war, 1914-1918,south australia,morphettville
57
                    [image] => Array
58
                        (
59
                            [nlsa] => https://collections.slsa.sa.gov.au/resource/B+37013/download
60
                            [local] => first-war/1914/b20307810.jpg
61
                        )
62
 
63
                )
64
 
65
        )
66
 
67
)

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.

Individual Result Data

1
<?php 
2
/*
3
 South Australian First World War Photograph Collection API
4
 https://www.beliefmedia.com.au/first-world-photograph-api
5
*/
6
 
7
function beliefmedia_slsa_firstwar_photo_detail($id, $apikey = 'xxxxxxxxxx') {
8
 
9
  $data = @file_get_contents('http://api.beliefmedia.com/australia/sa/firstwar.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
}

Browsing & Searching

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

Considerations

  • Like all our recent API features, it's new. If you encounter errors, please let us know.
  • The image collection (552MB) may be downloaded form our client area. The image path is returned in our JSON data and generally follows the following format: firstwar/{year}/{itemid}.jpg.

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 (Connecticut)

  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

READY TO HAVE A CHAT? CALL US ANYTIME ON 1300 235 433