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 2019-08-22.

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 may return the following types of information :

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

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
    • one-report
    • 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.

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.

Help

give-me=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

give-me=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

give-me=countries

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.

One Report

give-me=one-report

A secondary parameter needs to be given to identify the requested Report :

  • reportid if the Report ID is known
  • slug if 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 :

IDunique identifier for the Report 
datedate on which the reported event occured. Date is local to the geographical location of the event. Formatted as 'j M Y' 
date_ymddate on which the reported event occured. Date is local to the geographical location of the event. Formatted as 'Y-m-d'
date_ymmonth on which the reported event occured. Date is local to the geographical location of the event. Formatted as 'Y-m'
permalinkabsolute URL of the Report on the HORIZON web platform 
slugunique alpha identifier of this Report. Mostly human readable.
categoriesarray of the Categories checked for this Report, formatted as text 
categories_idarray of the ids of the Categories checked for this Report 
categoriesAsTexttext of the Categories checked for this Report 
impactimpact of the Report assessed in a scale of Low, Medium, High and Extreme
countryarray of the Countries checked for this Report, textual 
countries_iso2array of the Countries checked for this Report, formatted as iso2
latitudelatitude the event occured 
longitudelongitude the event occured 
locationsarray of Locations the event occured. Contains latitude, longitude and address
killedreported number of killed on this Report
deadalias of `killed`
woundedreported number of wounded on this Report
hostagesreported number of hostages on this Report
missingreported number of missing persons on this Report
arrestedreported number of arrested persons on this Report
posttypetype of this Report as text : possible values are Alert, Analysis, Forecast, Incident, Information 
posttype_idtype of this Report as numerical identifier : 1 = Alert, 2 = Analysis, 3 = Forecast, 10 = Incident, 20 = Information 
titletitle of this Report 
contentredacted text of this Report in HTML 
publication_ymdhmspublication date and time of the Report. Formatted as 'Y-m-d h:m:s' format, Brussels time 
publication_tspublication unix timestamp 
modification_ymdhmslast modification date and time of the Report. Formatted as 'Y-m-d h:m:s' format, Brussels time 
modification_tslast modification unix timestamp 
breakingsinceunix timestamp of the moment HORIZON declared this Report as Breaking, if it ever was
spotterservice which spotted and generated this Report
relevancyrelevancy 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

give-me=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 :

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

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

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

Offset/Paged request

Get the list of matching Reports from an offset when matching Reports number is above the limit of 200.

The offset argument specifies the number of Reports to jump/offset.

The pagen argument specifies the page number. offset is then calculated as pagen * 200.

https://horizon.hozint.com/api-v1/?&giveme=reports&offset=400
https://horizon.hozint.com/api-v1/?&giveme=reports&pagen=2

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

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

Spotter

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) :

  • HORIZON, human-based &spotter=hozint_horizon

  • Lookout, AI &spotter=hozint_lookout

https://horizon.hozint.com/api-v1/?&giveme=reports&spotter=hozint_horizon

Relevancy

Limit the list of Reports on Relevancy score with the &rlv argument. Relevancy is a score ranging from 0 to 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.

https://horizon.hozint.com/api-v1/?&giveme=reports&rlv=90

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

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