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