This is the document for the Hozint APIs v1, services provided by Hozint - Horizon Intelligence sprl (hereinafter Hozint) on https://horizon.hozint.com
This document was last edited on 2020-01-15.
Table of Content
Hozint is currently offering two APIs :
The HORIZON API provides Reports that have been verified by a human editor.
It is available from https://horizon.hozint.com/api-v1/
The Lookout API provides Reports automatically generated by our AI crawler.
It is available from https://lookout-frontend.hozint.com/api-v1/
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 may return the following types of information :
- Countries and Regions
- List of Reports or single Report
- 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
Depending on your subscription requests should be sent to
https://lookout-frontend.hozint.com/api-v1/. This entire documentation uses HORIZON as example, so if you are subscribed to the Lookout API please replace
lookout-frontend.hozint.com in all the following examples.
The API 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.
Report queries return maximum 200 Reports per request. It is possible to make offset/paged requests but due to the rythm of publication of Hozint services, we recommend not using this feature: you could end up with duplicates or missing Reports if paged queries happen while matching Reports are being published. We also advise to refine your request as much as possible with API parameters : getting "all Reports" and filtering on the client side seems like a waste of processing power and bandwith.
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.
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.
A secondary parameter needs to be given to identify the requested Report :
reportidif the Report ID is known
slugif the Report slug is know
If no Report is found using one of these parameters, a 404 Error is returned.
Keys returned for a Report are :
|ID||unique identifier for the Report|
|date||date on which the reported event occured. Date is local to the geographical location of the event. Formatted as 'j M Y'|
|date_ymd||date on which the reported event occured. Date is local to the geographical location of the event. Formatted as 'Y-m-d'|
|date_ym||month on which the reported event occured. Date is local to the geographical location of the event. Formatted as 'Y-m'|
|permalink||absolute URL of the Report on the HORIZON web platform|
|slug||unique alpha identifier of this Report. Mostly human readable.|
|categories||array of the Categories checked for this Report, formatted as text|
|categories_id||array of the ids of the Categories checked for this Report|
|categoriesAsText||text of the Categories checked for this Report|
|impact||impact of the Report assessed in a scale of Low, Medium, High and Extreme|
|country||array of the Countries checked for this Report, textual|
|countries_iso2||array of the Countries checked for this Report, formatted as iso2|
|latitude||latitude the event occured|
|longitude||longitude the event occured|
|locations||array of Locations the event occured. Contains latitude, longitude and address|
|killed||reported number of killed on this Report|
|dead||alias of `killed`|
|wounded||reported number of wounded on this Report|
|hostages||reported number of hostages on this Report|
|missing||reported number of missing persons on this Report|
|arrested||reported number of arrested persons on this Report|
|posttype||type of this Report as text : possible values are Alert, Analysis, Forecast, Incident, Information|
|posttype_id||type of this Report as numerical identifier : 1 = Alert, 2 = Analysis, 3 = Forecast, 10 = Incident, 20 = Information|
|title||title of this Report|
|content||redacted text of this Report in HTML|
|publication_ymdhms||publication date and time of the Report. Formatted as 'Y-m-d h:m:s' format, Brussels time|
|publication_ts||publication unix timestamp|
|modification_ymdhms||last modification date and time of the Report. Formatted as 'Y-m-d h:m:s' format, Brussels time|
|modification_ts||last modification unix timestamp|
|breakingsince||unix timestamp of the moment HORIZON declared this Report as Breaking, if it ever was|
|spotter||service which spotted and generated this Report|
|relevancy||relevancy score for this Report, from 0 to 100. For Lookout spotted Reports only, as HORIZON Reports always have a score of 100.|
List of Reports
An array containing the latest Reports published by the HORIZON platform.
The number of Reports returned is limited to 200.
A list of arguments may be passed to refine the request for Reports :
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 Impact with the
&i argument. HORIZON has 4 types of Impacts :
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.
Get the list of matching Reports from an offset when matching Reports number is above the limit of 200.
offset argument specifies the number of Reports to jump/offset.
pagen argument specifies the page number.
offset is then calculated as
pagen * 200.
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
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.
Limit the list of Reports to one or many Spotters with the
&spotter argument. There are 2 types of public Spotters ( private Spotters are available upon request) :
Limit the list of Reports on Relevancy score with the
&rlv argument. Relevancy is a score ranging from
100. Selected Reports will have a Relevancy score equal or above the requested value.
Relevancy score exists only for Reports spotted by Lookout. This selector has thus no effect on Reports spotted by HORIZON.
Limit the list of Reports to a specific word or words with the
&txt argument. Only Reports containing that word will be returned.
Limit the list of Reports to one Type with the
&rt argument. HORIZON has 3 types of Reports :