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.
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.
To alter the source for all examples below (
australia is your chosen source). All results may be paginated with
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:
Additional data may be returned for individual results depending upon your access.
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
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:
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:
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
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:
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.
- 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.