API, Blog, PHP

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:

Array

(

[code] => 200

[status] => 200

[message] => OK

[source] => BeliefMedia

[data_version] => 0.2

[data] => Array

(

[id] => j8Qz

[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.

[date] => Array

(

[mysql] => 1934-12-18

[stamp] => 19341218

[long] => 18th December 1934

)

=> Array

(

[filename] => aviation-history/1934/12/18/j8Qz.jpg

[size] => 44.1K

[width] => 610

[height] => 264

)

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:

Array

(

[code] => 200

[status] => 200

[message] => OK

[source] => BeliefMedia

[data_version] => 0.2

[page] => 1

[number] => 30

[pages] => 30

[total] => 892

[search] => Array

(

[type] => search

[term] => boeing

[params] => Array

(

)

[results] => Array

(

[0] => Array

(

[id] => 797B

[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.

[date] => Array

(

[mysql] => 2015-09-08

[stamp] => 20150908

[long] => 8th September 2015

)

=> Array

(

[filename] => aviation-history/2015/09/08/797B.jpg

[size] => 48.4K

[width] => 610

[height] => 264

)

[1] => Array

(

[id] => OgjY

[history] => First Flight of the Boeing 787-9 N789ZB at Paine Field in Everett, Washington, United States.

[date] => Array

(

[mysql] => 2013-09-17

[stamp] => 20130917

[long] => 17th September 2013

)

[.. 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:

Array

(

[code] => 200

[status] => 200

[message] => OK

[source] => BeliefMedia

[data_version] => 0.2

[page] => 1

[number] => 30

[pages] => 1

[total] => 14

[search] => Array

(

[type] => search

[term] => airbus

[params] => Array

(

[start] => 2010-02-15

[end] => 2012-10-15

)

[results] => Array

(

[0] => Array

(

[id] => 28nW

[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.

[date] => Array

(

[mysql] => 2012-10-10

[stamp] => 20121010

[long] => 10th October 2012

)

=> Array

(

[filename] => aviation-history/2012/10/10/28nW.jpg

[size] => 79.0K

[width] => 610

[height] => 396

)

[1] => Array

(

[id] => A6kP

[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.

[date] => Array

(

[mysql] => 2012-09-20

[stamp] => 20120920

[long] => 20th September 2012

)

=> Array

(

[filename] => aviation-history/2012/09/20/A6kP.jpg

[size] => 49.9K

[width] => 610

[height] => 286

)

[.. 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.