This is the document for the HORIZON APIv1, a service provided by Hozint - Horizon Intelligence sprl (hereinafter Hozint) on https://horizon.hozint.com
This document was last edited on 2018-11-02.
Table of Content
Hozint API keys are available in both commercial and non-commercial licences.
Information imported through the API is meant exclusively for the internal use of the organization.
Information imported through the API may be resold to third parties.
The API is accessible to any user who have stipulated a contract with Hozint for a paid subscription plan.
The APIv1 returns 5 types of information :
- Countries and Regions
- Reports from HORIZON
- New API key
- API key revocation confirmation
All data is returned in the JSON format suitable for modern web-enabled services. More information about JSON is available on http://www.json.org
A text containing Help and examples of how to use the API. Actually this very current document you are reading. Formatted in Markdown.
An array containing the current Categories and Subcategories used on the HORIZON platform. HORIZON files each Report under one or more Categories/Subcategories to provide Users with more tailored information.
Keys returned for each Category and Subcategory are :
id, a unique identifier ;
name, the name of the current Category or Subcategory ;
parentID, the identifier of the parent Category. For first-level Categories this value equals 0.
Countries and Regions
An array containing the current Countries and Regions used on the HORIZON platform.
Countries are political entities exercising the monopoly of the legitimate use of physical force within a given territory. Horizon consider as countries those recognized by the international community and the United Nations.
Regions are an aggregation of countries whose relations are strictly interconnected as to affect their domestic policies and international relations. Therefore, Horizon's connotation of "region" is not geographical but rather geopolitical (e.g. Asia / Pacific, Middle East & North Africa - MENA, etc.). Keys returned for each Country are :
id, a unique identifier ;
name, the name of the current Country or Region ;
parentID, the identifier of the Region the Country is situated in. For Regions this value equals 0.
An array containing the latest Reports published by the HORIZON platform.
The number of Reports returned is limited to 200.
Keys returned for each Report are :
|ID||a unique identifier for the Report|
|date||the date on which the reported event occured. Date is local to the geographical location of the event. Formatted as 'j M Y'|
|date_ymd||the date on which the reported event occured. Date is local to the geographical location of the event. Formatted as 'Y-m-d'|
|date_ym||the month on which the reported event occured. Date is local to the geographical location of the event. Formatted as 'Y-m'|
|permalink||the absolute URL of the Report on the HORIZON web platform|
|slug||the unique alpha identifier of this Report. Mostly human readable.|
|categories||an array of the Categories checked for this Report, formatted as text|
|categories_id||an array of the ids of the Categories checked for this Report|
|categoriesAsText||a text of the Categories checked for this Report|
|impact||the impact of the Report assessed in a scale of Low, Medium, High and Extreme|
|country||an array of the Countries checked for this Report, textual|
|countries_iso2||an array of the Countries checked for this Report, formatted as iso2|
|latitude||the latitude the event occured|
|longitude||the longitude the event occured|
|locations||array of Locations the event occured. Contains latitude, longitude and address|
|dead||the reported number of deaths on this Report|
|killed||alias of `dead`, the reported number of killed on this Report|
|wounded||the reported number of wounded on this Report|
|hostages||the reported number of hostages on this Report|
|missing||the reported number of missing persons on this Report|
|arrested||the reported number of arrested persons on this Report|
|posttype||the type of this Report as text : possible values are Alert, Analysis, Forecast, Incident, Information|
|posttype_id||the type of this Report as numerical identifier : 1 = Alert, 2 = Analysis, 3 = Forecast, 10 = Incident, 20 = Information|
|title||the title of this Report|
|content||the redacted text of this Report in HTML|
|publication_ymdhms||the publication date and time of the Report. Formatted as 'Y-m-d h:m:s' format, Brussels time|
|publication_ts||the publication unix timestamp|
|modification_ymdhms||the last modification date and time of the Report. Formatted as 'Y-m-d h:m:s' format, Brussels time|
|modification_ts||the last modification unix timestamp|
|breakingsince||unix timestamp of the moment HORIZON declared this Report as Breaking, if it ever was|
The HORIZON platform is only accessible through SSL, meaning all communications are encrypted both ways from client to server.
POST or GET a request to
https://horizon.hozint.com/api-v1/ with the following arguments :
&apikey: your API key. See 'Limitations' hereunder.
&giveme: the nature of the data requested. Accepted values are :
If an invalid or empty value for
&giveme is passed, 'reports' is assumed.
Help is accessible without a valid API key. All other requests must contain a valid
API requests are limited to 5 per minute per API key.
Reports queries return maximum 200 Reports per request. If you want to retrieve more Reports you should refine your request.
A list of arguments may be passed to refine the request for Reports :
Reports published since
Most systems will regularly poll the API, requesting only Reports published since the last received as there is no point to download over and over the same Reports.
&publishedsince argument to receive the Reports published since the last call. The value should be the latest
publication_ts you have received.
Reports modified since
Some systems might poll the API looking for Reports published and/or modified since a specific UNIX timestamp.
WARNING: using this selector might return Reports which had already been received before. HORIZON staff does update published Reports when necessary, to update information or to correct typos. Reports obtained through this method might thus not be all very recent.
modifiedsince argument to receive the Reports published and/or modified since the passed timestamp.
An older alias for the argument is
&modsinceTS. HORIZON might discontinue its usage in future versions of the API.
Limit the list of Reports to chosen Categories with the
&c argument, passing ids of the relevant Categories seperated by comas :
Limit the list of Reports to chosen Countries and Regions with the
&a argument, passing ids of the relevant areas seperated by comas :
Limit the list of Reports to one Type with the
&rt argument. HORIZON has 3 types of Reports :
Limit the list of Reports to Impact with the
&i argument. HORIZON has 4 types of Impacts :
Limit the list of Reports to a specific period with the
&te arguments, corresponding to Time Start and Time End. Expected values are dates formatted as
Limit the list of Reports to a specific word or words with the
&txt argument. Only Reports containing that word will be returned.