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

Example Interest Rates: Home Loan Variable: 2.54% (2.74%*) • Home Loan Fixed: 3.74% (3.8%*) • Fixed: 2.48% (2.94%*) • Variable: 2.54% (2.74%*) • Investment IO: 2.3% (3.76%*) • Investment PI: 2.04% (3.8%*)

History API

History API

For a long time we've maintained a 'This Day in History' database for use by clients and partners. The purpose of this article is to provide a cursory introduction to the History API available via RESTful HTTP requests or from within our client area.

The very basic resource and API we previously maintained at Hiztory.org will soon be retired. While the Hiztory API is key-free and rather complete, we returned XML and RSS data which is now a little obsolete. The Hiztory data is no longer maintained and the website itself will be retired in the next few months.

While there's a large number of categories that we've added to our database, the only categories currently available to our partners are aviation history, rail history, Australian history, births, deaths, and events. We try and maintain the data-source by updating once a year, thus keeping the information fresh.

The Result

Returning a single result or browsing results is done so without a great deal of complexity. Searching the data, however, introduces a few parameters to filter results. For the purpose of all examples we'll be using the default Aviation History source.

Endpoint: https://api.beliefmedia.com/platform/sources/history/history.json.

To alter the source for all examples below (australia, aviation, rail, birth, death, event), use source=australia (where australia is your chosen source). All results may be paginated with pg and number.

Individual Results

If an item ID is known the details for that individual result may be returned. Requesting history.json?apikey=xxx&id=j8Qz returns the following:

1
Array
2
(
3
    [code] => 200
4
    [status] => 200
5
    [message] => OK
6
    [source] => BeliefMedia
7
    [data_version] => 0.2
8
    [data] => Array
9
        (
10
            [id] => j8Qz
11
            [history] => Boeing Airplane Co. subsidiary Stearman Aircraft, located in Wichita, Kan., delivers its first Stearman Kaydet to the military. It will become the most common preliminary trainer in service, and 10,346 Kaydets will be built during World War II.
12
            [date] => Array
13
                (
14
                    [mysql] => 1934-12-18
15
                    [stamp] => 19341218
16
                    [long] => 18th December 1934
17
                )
18
 
19
            [image] => Array
20
                (
21
                    [filename] => aviation-history/1934/12/18/j8Qz.jpg
22
                    [size] => 44.1K
23
                    [width] => 610
24
                    [height] => 264
25
                )
26
 
27
        )
28
 
29
)

Additional data may be returned for individual results depending upon your access.

Browsing Results

To browse all results, use history.json?apikey=xxx. As with all queries, an optional source may be defined.

Today's Results (or Results From Any Day)

For 'Today in History' results, use history.json?apikey=xxx&type=today. This returns results for 'today' based on Australian Eastern Standard Time. To alter for your own timezone, construct a 4-figure time group and add offset=MMDD to your query URL (where MM is the month and DD is the date). You can query the results for any day in the same way; for example, the results for 26th September can be returned with history.json?apikey=xxx&type=today&offset=0926.

Searching Results

When searching the database there are a few parameters that may be used to filter results. The parameter of type=search must be used (otherwise browsing is assumed). Requesting history.json?apikey=xxx&type=search&search=boeing returns the following:

1
Array
2
(
3
    [code] => 200
4
    [status] => 200
5
    [message] => OK
6
    [source] => BeliefMedia
7
    [data_version] => 0.2
8
    [page] => 1
9
    [number] => 30
10
    [pages] => 30
11
    [total] => 892
12
    [search] => Array
13
        (
14
            [type] => search
15
            [term] => boeing
16
            [params] => Array
17
                (
18
                )
19
 
20
        )
21
 
22
    [results] => Array
23
        (
24
            [0] => Array
25
                (
26
                    [id] => 797B
27
                    [history] => British Airways Flight 2276 rejected takeoff due to an engine failure, the aircraft came to a stop and all passengers and crew evacuated safely with only 14 minor injuries, the aircraft, a Boeing 777-236ER was badly damaged in the incident.
28
                    [date] => Array
29
                        (
30
                            [mysql] => 2015-09-08
31
                            [stamp] => 20150908
32
                            [long] => 8th September 2015
33
                        )
34
 
35
                    [image] => Array
36
                        (
37
                            [filename] => aviation-history/2015/09/08/797B.jpg
38
                            [size] => 48.4K
39
                            [width] => 610
40
                            [height] => 264
41
                        )
42
 
43
                )
44
 
45
            [1] => Array
46
                (
47
                    [id] => OgjY
48
                    [history] => First Flight of the Boeing 787-9 N789ZB at Paine Field in Everett, Washington, United States.
49
                    [date] => Array
50
                        (
51
                            [mysql] => 2013-09-17
52
                            [stamp] => 20130917
53
                            [long] => 17th September 2013
54
                        )
55
            [.. SNIP ..]

Searching by a date range may be achieved in one of two ways. A set of numeric URL parameters is an older means of filtering but it's still used in a few applications and will continue to be supported.

sy: The start year.
ey: The end year.
sm: The start month.
em: The end month.
sd: The start day of month.
ed: The end day of month.

You may optionally (and preferably) search results via an 8-figure time group or human-readable string. For an 8-figure start date, use the following: 20161227 (YYYYMMDD), or use a string in the following exact format: 27-december-2016. The end date is applied in the same way.

search: The search term is used in a free text search.

Ordering results may be altered with order=desc or order=asc.

An example response from a slightly more complex search is as follows: history.json?apikey=xxx&type=search&search=airbus&start=20100215&end=20121015. The result:

1
Array
2
(
3
    [code] => 200
4
    [status] => 200
5
    [message] => OK
6
    [source] => BeliefMedia
7
    [data_version] => 0.2
8
    [page] => 1
9
    [number] => 30
10
    [pages] => 1
11
    [total] => 14
12
    [search] => Array
13
        (
14
            [type] => search
15
            [term] => airbus
16
            [params] => Array
17
                (
18
                    [start] => 2010-02-15
19
                    [end] => 2012-10-15
20
                )
21
 
22
        )
23
 
24
    [results] => Array
25
        (
26
            [0] => Array
27
                (
28
                    [id] => 28nW
29
                    [history] => As part of an arms embargo against Syria, Turkish Air Force F-16 Fighting Falcons intercept Syrian Air Flight RB442, an Airbus A320 suspected of carrying Russian-made weapons, in Turkish airspace during its flight from Vnukovo International Airport in Moscow to Damascus International Airport in Damascus, Syria, and force it to land at Esenbo?a International Airport outside Ankara, Turkey. Inspectors confiscate military communications equipment and items "thought to be missile parts" found aboard the plane.
30
                    [date] => Array
31
                        (
32
                            [mysql] => 2012-10-10
33
                            [stamp] => 20121010
34
                            [long] => 10th October 2012
35
                        )
36
 
37
                    [image] => Array
38
                        (
39
                            [filename] => aviation-history/2012/10/10/28nW.jpg
40
                            [size] => 79.0K
41
                            [width] => 610
42
                            [height] => 396
43
                        )
44
 
45
                )
46
 
47
            [1] => Array
48
                (
49
                    [id] => A6kP
50
                    [history] => After takeoff from Damascus International Airport in Damascus, Syria, a Syrian Air Airbus A320 collides in mid-air with a Syrian Mil Mi-17 (NATO reporting name "Hip") helicopter. The helicopter crashes, while the A320 returns to the airport safely despite a damaged tail.
51
                    [date] => Array
52
                        (
53
                            [mysql] => 2012-09-20
54
                            [stamp] => 20120920
55
                            [long] => 20th September 2012
56
                        )
57
 
58
                    [image] => Array
59
                        (
60
                            [filename] => aviation-history/2012/09/20/A6kP.jpg
61
                            [size] => 49.9K
62
                            [width] => 610
63
                            [height] => 286
64
                        )
65
 
66
                )
67
            [.. SNIP ..]

Images

For each history record in our database we've manufactured a branded image in a 'This Day in History' format. While you may download each collection from the client area, you may also create images in real time via our Image Factory API. If you'd like us to build them for you, please get in touch.

Considerations

  • For a long time we scheduled each history image to Facebook individually over the course of a day. We've since learned that posting an album with all images once a day tends to attract more engagement. Individual images to Twitter remains the most appropriate means to share the content.
  • We wrote a very simple "This Day in History" WordPress plugin a number of years ago. That plugin consumed the old XML API and is now a little tired and in need of a serious update. We'll be porting that plugin over to the new BeliefMedia API in the next few months before retiring the old Hiztory website entirely.

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

  Want to have a chat?
 

RELATED READING

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