API v1 Help

Page

HORIZON APIv1

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

Who can access the API

Hozint API keys are available in both commercial and non-commercial licences.

Non-commercial licence

Information imported through the API is meant exclusively for the internal use of the organization.

Commercial license

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.

Data returned by the API

The APIv1 returns 5 types of information :

  • Help
  • Categories
  • 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

Help

A text containing Help and examples of how to use the API. Actually this very current document you are reading. Formatted in Markdown.

Categories

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.

Country

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

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.

Reports

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 :

IDa unique identifier for the Report 
datethe date on which the reported event occured. Date is local to the geographical location of the event. Formatted as 'j M Y' 
date_ymdthe date on which the reported event occured. Date is local to the geographical location of the event. Formatted as 'Y-m-d'
date_ymthe month on which the reported event occured. Date is local to the geographical location of the event. Formatted as 'Y-m'
permalinkthe absolute URL of the Report on the HORIZON web platform 
slugthe unique alpha identifier of this Report. Mostly human readable.
categoriesan array of the Categories checked for this Report, formatted as text 
categories_idan array of the ids of the Categories checked for this Report 
categoriesAsTexta text of the Categories checked for this Report 
impactthe impact of the Report assessed in a scale of Low, Medium, High and Extreme
countryan array of the Countries checked for this Report, textual 
countries_iso2an array of the Countries checked for this Report, formatted as iso2
latitudethe latitude the event occured 
longitudethe longitude the event occured 
locationsarray of Locations the event occured. Contains latitude, longitude and address
deadthe reported number of deaths on this Report
killedalias of `dead`, the reported number of killed on this Report
woundedthe reported number of wounded on this Report
hostagesthe reported number of hostages on this Report
missingthe reported number of missing persons on this Report
arrestedthe reported number of arrested persons on this Report
posttypethe type of this Report as text : possible values are Alert, Analysis, Forecast, Incident, Information 
posttype_idthe type of this Report as numerical identifier : 1 = Alert, 2 = Analysis, 3 = Forecast, 10 = Incident, 20 = Information 
titlethe title of this Report 
contentthe redacted text of this Report in HTML 
publication_ymdhmsthe publication date and time of the Report. Formatted as 'Y-m-d h:m:s' format, Brussels time 
publication_tsthe publication unix timestamp 
modification_ymdhmsthe last modification date and time of the Report. Formatted as 'Y-m-d h:m:s' format, Brussels time 
modification_tsthe last modification unix timestamp 
breakingsinceunix timestamp of the moment HORIZON declared this Report as Breaking, if it ever was

How to query the API

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 :

    • help
    • categories
    • countries
    • reports

If an invalid or empty value for &giveme is passed, 'reports' is assumed.

https://horizon.hozint.com/api-v1/?&apikey=YOUR-API-KEY&giveme=help
https://horizon.hozint.com/api-v1/?&apikey=YOUR-API-KEY&giveme=categories
https://horizon.hozint.com/api-v1/?&apikey=YOUR-API-KEY&giveme=countries

Limitations

Help is accessible without a valid API key. All other requests must contain a valid &apikey.

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.

Selecting Reports

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.

Pass the &publishedsince argument to receive the Reports published since the last call. The value should be the latest publication_ts you have received.

https://horizon.hozint.com/api-v1/?&giveme=reports&publishedsince=1461370888

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.

Pass the 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.

https://horizon.hozint.com/api-v1/?&giveme=reports&modifiedsince=1461370888

Categories

Limit the list of Reports to chosen Categories with the &c argument, passing ids of the relevant Categories seperated by comas :

https://horizon.hozint.com/api-v1/?&giveme=reports&c=8,318,216,232,215,390,219,363

Countries

Limit the list of Reports to chosen Countries and Regions with the &a argument, passing ids of the relevant areas seperated by comas :

https://horizon.hozint.com/api-v1/?&giveme=reports&a=12,88

Type

Limit the list of Reports to one Type with the &rt argument. HORIZON has 3 types of Reports :

  • Incident &rt=10

  • Information &rt=20

  • Forecast &rt=3

https://horizon.hozint.com/api-v1/?&giveme=reports&rt=20

Impact

Limit the list of Reports to Impact with the &i argument. HORIZON has 4 types of Impacts :

  • Extreme &i=8

  • High &i=5

  • Medium &i=3

  • Low &i=2

https://horizon.hozint.com/api-v1/?&giveme=reports&i=8,5,3

Period

Limit the list of Reports to a specific period with the &ts and &te arguments, corresponding to Time Start and Time End. Expected values are dates formatted as YYYY-MM-DD.

https://horizon.hozint.com/api-v1/?&giveme=reports&ts=2016-02-01&te=2016-02-10

Text

Limit the list of Reports to a specific word or words with the &txt argument. Only Reports containing that word will be returned.

https://horizon.hozint.com/api-v1/?&giveme=reports&txt=zika