This Day in History :: 22 September
Hiztory.org | Powered by BeliefMedia


The Hiztory.org API is a RESTful service that provides XML output for various types of historical events. It's very much in beta and was intended for our own applications. It'll be made more scalable/reliable in the near future. At this stage, only XML data is available.

The database and industry specific areas are growing on a daily basis. If you have specific needs, please let us know.

Rate Limiting

Because the API is free and doesn't require registration, we've mitaged the potential for abuse by rate limiting unreasonable requests and we truncate various types of output. If you're building an application and require uninterrupted access, let us know and we'll whitelist you. Registered users get full and complete access; this includes the ability to build queries by any parameter - including keywords.

XML API

The XML URL is as follows:

http://api.hiztory.org/aviation/09/26/1/15/api.xml


The URL structure is as follows:

All queries begin with: http://api.hiztory.org/

aviation - query aviation history. Must be lower case.
09 - September (two digits).
26 - 26th day of the month (always two digits).
1 - Page 1. No leading zero.
15 - Number of results per page (max 15... for now).

For the moment, you're limited to aviation, birth, death and event queries. More are available and will be made public soon.

Output looks like this:



Note that the output includes the number of pages, the number of total results, the result limit (max 15 at this stage) and the page number. The status message of 200 indicates a successful response.

Random Output

At times, sometimes it's necessary to generate a single random item for inclusion on a webpage or blog. To that end, use the following:

http://api.hiztory.org/random/birth.xml
http://api.hiztory.org/random/death.xml
http://api.hiztory.org/random/event.xml
http://api.hiztory.org/random/aviation.xml


Results are cached locally for about 10 minutes. It's expected that you would also cache the results for up to 15 minutes to avoid any rate-limiting. If you're using any of our code, we provide that functionality by default.


Note, again, the 200 response code. If you don't receive this, it's best to keep your locally cached copy until new information becomes available.

Random Output by Date

Random output doesn't take date into consideration; it literally picks anything from the data. To refine your random result by date, use the following format:

http://api.hiztory.org/date/event/09/24/api.xml


09 is the month and 24 is the date. Numbers must include the leading '0'. Of course, you'll need to replace event with whatever data source you're querying.

RSS Feeds

Limited RSS feeds are available from the main page. They can be consumed via any number of RSS readers or consumed directly into a WordPress (or other) blog via an array of available widgets and tools.



These feeds, however, are based on a timezone on the Eastern State of Australia. For feeds in your own timezone, use the following format:

http://www.hiztory.org/10/23/aviation.rss


... where 10 is the month (October) and 23 is the date. Of course, replace aviation with whatever it is you're searching (again, at this stage, only aviation, birth, death or event).

Error Codes

There are various errors that might be generated. Generally speaking, anything other than a 200 response is bad. Rate limiting also applies (code 420).

Aviation

Despite the fact we're using this information on a number of our own sites, the prime motivation was to make aviation historical information available. If you're an aviation person and need help with implementation, get in touch with us and we'll do our best to help. WordPress and other code will be available on our Flight blog.

It's in BETA

The service is considered in a very early stage of development. If you have any ideas or encounter any errors, please let us know.

Terms of Use

By using the Hiztory API, you agree to these simple terms of use. You may use the API as-is for any purpose. You alone are responsible for any damage that you or your users encounter from using services from this API. The data provided may be cached locally for performance, but for no longer than 1 day. We accept no responsibility for any downtime, damage or errors, invalid/incorrect data or the consequences of information we provide. These terms are subject to change without notice and will be updated on this page.

You must provide attribution with a link to http://www.hiztory.org/.





Home| Aviation | About | API | Twitter (powered by Viralnetics) | WordPress Plugin | BeliefMedia