Home API History API

History API

0

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.

Shortt URL for this post: http://shor.tt/1Z1f

LEAVE A REPLY

Please enter your comment!
Please enter your name here