Log in
Before you start accessing our API you must log in using the credentials provided by Hozint.
You can find the instructions in the Log-in API documentation.
Horizon Reports API
Description
This API endpoint retrieves a list of Horizon reports. The reports contain detailed information about various incidents, including location, country, category, impact, victims, and sources. You can filter reports based on various parameters or retrieve all reports without any filtering.
Endpoint
GET /api/report/horizon/
Request
curl -X ‘GET’
‘https://admin.hozint.ai/api/report/horizon/’
-H ‘accept: application/json’
-H ‘Authorization: Bearer <your_access_token>’
Data Returned by Horizon Reports API
- count: The total number of reports available.
- total_pages: The total number of pages of reports.
- next: The URL for the next page of reports (if available).
- previous: The URL for the previous page of reports (if available).
- results: A list of reports with detailed information.
Each report includes:
- report_id: The unique identifier for the report.
- report_title: The title of the report.
- content: The content or description of the report.
- location: A list containing the location details.
- latitude: Latitude of the incident location.
- longitude: Longitude of the incident location.
- address: Address of the incident location.
- country: A list containing the country details.
- region: The region of the country.
- name: Name of the region.
- id: The unique identifier of the region.
- countries: A list of countries within the region. Each country includes:
- id: The unique identifier for the country.
- name: The name of the country.
- region: The region of the country.
- event_date: The date of the event (if available).
- event_time: The time of the event (if available).
- event_end_date: The end date of the event (if available).
- event_end_time: The end time of the event (if available).
- published_datetime: The date and time when the report was published.
- Example: “2024-05-27T13:05:46Z”
- modified_datetime: The date and time when the report was last modified.
- Example: “2024-08-03T18:00:41.620048Z”
- category: A list containing the category details.
- main_category: The main category of the report.
- name: Name of the main category.
- id: The unique identifier of the category.
- subcategories: A list of subcategories within the main category. Each subcategory includes:
- id: The unique identifier for the subcategory.
- name: The name of the subcategory.
- main_category: The main category of the report.
- report_type: The type of report.(“Incident”,“Information”)
- impact: The impact level of the incident.( “Low”,”Medium”,”High”,”Extreme”)
- victims: Details about the victims of the incident.
- dead: Number of dead victims.
- wounded: Number of wounded victims.
- hostages: Number of hostages taken.
- missing: Number of missing people.
- arrested: Number of arrested individuals.
- source: A list of sources providing information about the report. Each source includes:
- url: The URL of the source.
How to query Horizon Reports API
You should be initially logged in providing access tokens.
The user should have a valid subscription subscribed to Horizon Reports API.
Then execute the get request and retrieve the Horizon Reports.
Additionally, you can filter the reports based on the following query parameters:
| Parameter | Type | Description |
| auto_date_range | string (query) | Filter reports by either auto date range or custom date range. Options: ‘Today’, ‘Past 7 days’, ‘Next 7 days’, ‘Past 30 days’, ‘Next 30 days’, ‘Custom timeframe’. For ‘Custom timeframe’, event_start_date and event_end_date must be present. |
| category | string (query) | Filter by category ID(s). Can be a single ID or a comma-separated list of IDs. Accepts both main category and subcategory IDs. |
| country | string (query) | Filter by country ID(s). Can be a single ID or a comma-separated list of IDs. Accepts both country and region IDs. |
| event_end_date | string (query) | Filter reports by event dates up to this date. The auto_date_range parameter should be set to ‘Custom timeframe’ for this field to apply. Format: YYYY-MM-DD. |
| event_start_date | string (query) | Filter reports by event dates starting from this date. The auto_date_range parameter should be set to ‘Custom timeframe’ for this field to apply. Format: YYYY-MM-DD. |
| geofeature_coordinates | string (query) | Pass base64 encoded GeoJSON containing geo feature(s). For GeoJSON samples refer to the examples section. |
| impact | string (query) | Filter reports by impact level(s). Can be a single value or a comma-separated list of values. |
| keyword | string (query) | Pass base64 encoded keyword JSON containing keywords with logical operators. |
| page | string (query) | Specify the page you want to access. 200 reports per page are returned by default. |
| page_size | integer (query) | Number of reports to return per page. The maximum number of reports per page is 200. |
| published_since_seconds | integer (query) | Filter reports by the number of seconds since they were published. |
| report_type | string (query) | Filter reports by type(s). Can be a single value or a comma-separated list of values. |
Examples
Keywords Json Example
[
{
"keywords": [
{
"type": "AND",
"keyword": "terminal"
},
{
"type": "OR",
"keyword": "new"
},
{
"type": "EXCL",
"keyword": "help"
}
]
}
]
Feature Collection GeoJson Example
[
{
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"geometry": {
"type": "Polygon",
"coordinates": [
[
[
29.606263327173277,
29.351260360166037
],
[
34.99803198126308,
31.068731175074266
],
[
38.10037765807652,
38.10601547327829
],
[
34.0451281074395,
42.78661881981615
],
[
29.26101553505825,
41.37872180435707
],
[
29.4745114657443,
29.280882894726226
],
[
29.606263327173277,
29.351260360166037
]
]
]
},
"properties": {}
},
{
"type": "Feature",
"geometry": {
"type": "Point",
"coordinates": [
49.34280616465017,
8.705301330275688
]
},
"properties": {
"radius": "50",
"radius_unit": "miles"
}
},
{
"type": "Feature",
"geometry": {
"type": "LineString",
"coordinates": [
[
49.04556838804626,
8.086304761387936
],
[
49.010813048877765,
9.201322655465617
],
[
49.69274116024698,
9.621584068853792
]
]
},
"properties": {
"radius": "50",
"radius_unit": "miles"
}
}
]
}
]
Polygon GeoJson Example
[
{
"type": "Feature",
"geometry": {
"type": "Polygon",
"coordinates": [
[
[
29.606263327173277,
29.351260360166037
],
[
34.99803198126308,
31.068731175074266
],
[
38.10037765807652,
38.10601547327829
],
[
34.0451281074395,
42.78661881981615
],
[
29.26101553505825,
41.37872180435707
],
[
29.4745114657443,
29.280882894726226
],
[
29.606263327173277,
29.351260360166037
]
]
]
},
"properties": {}
}
]
Point GeoJson Example
[
{
"type": "Feature",
"geometry": {
"type": "Point",
"coordinates": [
49.34280616465017,
8.705301330275688
]
},
"properties": {
"radius": "50",
"radius_unit": "miles"
}
}
]
LineString GeoJson Example
[
{
"type": "Feature",
"geometry": {
"type": "LineString",
"coordinates": [
[
49.04556838804626,
8.086304761387936
],
[
49.010813048877765,
9.201322655465617
],
[
49.69274116024698,
9.621584068853792
]
]
},
"properties": {
"radius": "50",
"radius_unit": "miles"
}
}
]
Radius GeoJson Example
[
{
"type": "Feature",
"properties": {},
"geometry": {
"type": "Polygon",
"coordinates": [
[
[
49.395560890974714,
8.725988463242857
],
[
49.39431735512934,
8.709860145978645
],
[
49.39335813285867,
8.70463945564245
],
[
49.39213504391037,
8.699550732207248
],
[
49.39065564842198,
8.694625418953907
],
[
49.388929090054425,
8.689893941489448
],
[
49.38696603905746,
8.685385518697936
],
[
49.38477862585549,
8.68112798142023
],
[
49.38238036557867,
8.677147600009462
],
[
49.379786074021744,
8.67346892184647
],
[
49.37701177556626,
8.670114619829551
],
[
49.374074603651984,
8.667105352776481
],
[
49.37099269442947,
8.664459638594485
],
[
49.367785074266884,
8.662193740986464
],
[
49.364471541821445,
8.660321570369952
],
[
49.361072545417876,
8.65885459958994
],
[
49.395560890974714,
8.725988463242857
]
]
]
}
}
]
Validation Error messages
Subscription Errors
No active subscription found for this organization.
- Reason: Raised if no active subscription is found for the organization.
- Solution: Ensure the organization has an active subscription.
Your active subscription does not have access to this endpoint.
- Reason: Raised if the active subscription does not have access to the endpoint.
- Solution: Upgrade the subscription to gain access to the endpoint.
Category Filter Errors
Invalid value for category parameter.
- Reason: Raised if any category ID is not an integer.
- Solution: Ensure all category IDs are integers. Use only valid numeric category IDs.
No main-category or sub-category found for given id: {category_id}.
- Reason: Raised if no category or subcategory exists for the given ID.
- Solution: Verify that the provided category ID exists. Use existing category or subcategory IDs.
Country Filter Errors
Invalid value for country parameter.
- Reason: Raised if any country ID is not an integer.
- Solution: Ensure all country IDs are integers. Use only valid numeric country IDs.
No country or region found for given id: {country_id}.
- Reason: Raised if no country or region exists for the given ID.
- Solution: Verify that the provided country ID exists. Use existing country or region IDs.
Published Since Seconds Errors
Invalid value for published_since_seconds. Must be a valid integer.
- Reason: Raised if the published_since_seconds is not an integer.
- Solution: Ensure that published_since_seconds is a valid integer.
Event Date Errors
Invalid value for event_start_date. Must be in YYYY-MM-DD format.
- Reason: Raised if event_start_date is not in the correct date format and event_end_date is missing.
- Solution: Ensure event_start_date is provided in the YYYY-MM-DD format.
Invalid value for event_end_date. Must be in YYYY-MM-DD format.
- Reason: Raised if event_end_date is not in the correct date format and event_start_date is missing.
- Solution: Ensure event_end_date is provided in the YYYY-MM-DD format.
Invalid value for event_start_date or event_end_date. Must be in YYYY-MM-DD format.
- Reason: Raised if both event_start_date and event_end_date are not in the correct date format.
- Solution: Ensure both event_start_date and event_end_date are provided in the YYYY-MM-DD format.
GeoJSON Errors
Invalid geometry.
- Reason: Raised if the “geometry” of the geo feature is incorrect (e.g., “{}” or “[]”).
- Solution: Ensure the “geometry” field of the geo feature is correctly formatted.
Invalid geofeature type.
- Reason: Raised if the “type” of the geometry of the geo feature is neither a “Polygon” nor “Point” nor “LineString”.
- Solution: Ensure the “type” field of the “geometry” is either “Polygon”, “Point”, or “LineString”.
Invalid coordinates provided.
- Reason: Raised if the “coordinates” of the “geometry” of the geo feature are incorrect.
- Solution: Ensure the “coordinates” field of the “geometry” is correctly formatted.
Radius or radiusUnit not provided for LineString.
- Reason: Raised if the “type” is “LineString” and neither the “radius” nor the “radius_unit” exist.
- Solution: Provide both “radius” and “radius_unit” for LineString features.
Invalid geoJSON format.
- Reason: Raised if the geoJSON format is incorrect.
- Solution: Ensure the geoJSON format adheres to the correct specifications.
Invalid geofeature.
- Reason: Raised if any error occurs that is not captured in previous validations.
- Solution: Ensure all fields and formats are correct as per the geoJSON specification.
Unsupported radius_unit: {radius_unit}. Supported units are ‘kilometers’ and ‘miles’.
- Reason: Raised if the radius_unit is neither “kilometers” nor “miles”.
- Solution: Use “kilometers” or “miles” as the radius unit.
Radius or radius_unit not provided for Point.
- Reason: Raised if the “radius” or “radius_unit” is null for a Point.
- Solution: Provide both “radius” and “radius_unit” for Point features.
Keywords Validation Errors
Invalid keyword parameter. Please ensure you are sending a valid JSON encoded.
- Reason: Keywords should be in the correct keyword JSON format.
- Solution: Ensure keywords are formatted correctly in the JSON request body.
Auto Date Range Errors
Invalid auto_date_range value.
- Reason: Raised if the auto_date_range value is not among the accepted values (‘Today’, ‘Past 7 days’, ‘Next 7 days’, ‘Past 30 days’, ‘Next 30 days’, ‘Custom timeframe’).
- Solution: Use a valid auto_date_range value from the accepted list.
For the ‘Custom timeframe’ filter, event_start_date and event_end_date must be present.
- Reason: Raised if auto_date_range is ‘Custom timeframe’ and either event_start_date or event_end_date is missing.
- Solution: Provide both event_start_date and event_end_date for the ‘Custom timeframe’ filter.
Limitations
There is a limitation of 1000 requests per user per day and the API is paginated for retrieving reports. Each paginated page can contain a maximum of 200 reports.
Lookout Reports API
Description
This API endpoint retrieves a list of lookout reports.
Endpoint
GET /api/report/lookout/
Request
curl -X ‘GET’
‘https://admin.hozint.ai/api/report/lookout/’
-H ‘accept: application/json’
-H ‘Authorization: Bearer <your_access_token>’
Data Returned by Lookout Reports API
- count: The total number of reports available.
- total_pages: The total number of pages of reports.
- next: The URL for the next page of reports (if available).
- previous: The URL for the previous page of reports (if available).
- results: A list of reports with detailed information.
Each report includes:
- report_id: The unique identifier for the report.
- report_title: The title of the report.
- content: The content or description of the report.
- location: A list containing the location details.
- latitude: Latitude of the incident location.
- longitude: Longitude of the incident location.
- address: Address of the incident location.
- country: A list containing the country details.
- region: The region of the country.
- name: Name of the region.
- id: The unique identifier of the region.
- countries: A list of countries within the region. Each country includes:
- id: The unique identifier for the country.
- name: The name of the country.
- region: The region of the country.
- event_date: The date of the event (if available).
- event_time: The time of the event (if available).
- event_end_date: The end date of the event (if available).
- event_end_time: The end time of the event (if available).
- published_datetime: The date and time when the report was published.
- Example: “2024-05-27T13:05:46Z”
- modified_datetime: The date and time when the report was last modified.
- Example: “2024-05-27T13:05:46Z”
- category: A list containing the category details.
- main_category: The main category of the report.
- name: Name of the main category.
- id: The unique identifier of the category.
- subcategories: A list of subcategories within the main category. Each subcategory includes:
- id: The unique identifier for the subcategory.
- name: The name of the subcategory.
- main_category: The main category of the report.
- report_type: The type of report.(“Incident”,“Information”)
- impact: The impact level of the incident.( “Low”,”Medium”,”High”,”Extreme”)
- victims: Details about the victims of the incident.
- dead: Number of dead victims.
- wounded: Number of wounded victims.
- hostages: Number of hostages taken.
- missing: Number of missing people.
- arrested: Number of arrested individuals.
- source: A list of sources providing information about the report. Each source includes:
- url: The URL of the source.
How to query Lookout Reports API
You should be initially logged in providing access tokens.
The user should have a valid subscription which is subscribed to the Lookout reports API.
Then execute the get request and retrieve the Lookout Reports.
Additionally, you can filter the reports based on the following query parameters:
| Parameter | Type | Description |
| auto_date_range | string (query) | Filter reports by either auto date range or custom date range. Options: ‘Today’, ‘Past 7 days’, ‘Next 7 days’, ‘Past 30 days’, ‘Next 30 days’, ‘Custom timeframe’. For ‘Custom timeframe’, event_start_date and event_end_date must be present. |
| category | string (query) | Filter by category ID(s). Can be a single ID or a comma-separated list of IDs. Accepts both main category and subcategory IDs. |
| country | string (query) | Filter by country ID(s). Can be a single ID or a comma-separated list of IDs. Accepts both country and region IDs. |
| event_end_date | string (query) | Filter reports by event dates up to this date. The auto_date_range parameter should be set to ‘Custom timeframe’ for this field to apply. Format: YYYY-MM-DD. |
| event_start_date | string (query) | Filter reports by event dates starting from this date. The auto_date_range parameter should be set to ‘Custom timeframe’ for this field to apply. Format: YYYY-MM-DD. |
| geofeature_coordinates | string (query) | Pass base64 encoded GeoJSON containing geo feature(s). For GeoJSON samples refer to the examples section. |
| impact | string (query) | Filter reports by impact level(s). Can be a single value or a comma-separated list of values. |
| keyword | string (query) | Pass base64 encoded keyword JSON containing keywords with logical operators. |
| page | string (query) | Specify the page you want to access.200 reports per page is returned by default. |
| page_size | integer (query) | Specify the page you want to access.200 reports per page are returned by default. |
| published_since_seconds | integer (query) | Filter reports by the number of seconds since they were published. |
| report_type | string (query) | Filter reports by type(s). Can be a single value or a comma-separated list of values. |
Examples
Keywords Json Example
[
{
"keywords": [
{
"type": "AND",
"keyword": "terminal"
},
{
"type": "OR",
"keyword": "new"
},
{
"type": "EXCL",
"keyword": "help"
}
]
}
]
Feature Collection GeoJson Example
[
{
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"geometry": {
"type": "Polygon",
"coordinates": [
[
[
29.606263327173277,
29.351260360166037
],
[
34.99803198126308,
31.068731175074266
],
[
38.10037765807652,
38.10601547327829
],
[
34.0451281074395,
42.78661881981615
],
[
29.26101553505825,
41.37872180435707
],
[
29.4745114657443,
29.280882894726226
],
[
29.606263327173277,
29.351260360166037
]
]
]
},
"properties": {}
},
{
"type": "Feature",
"geometry": {
"type": "Point",
"coordinates": [
49.34280616465017,
8.705301330275688
]
},
"properties": {
"radius": "50",
"radius_unit": "miles"
}
},
{
"type": "Feature",
"geometry": {
"type": "LineString",
"coordinates": [
[
49.04556838804626,
8.086304761387936
],
[
49.010813048877765,
9.201322655465617
],
[
49.69274116024698,
9.621584068853792
]
]
},
"properties": {
"radius": "50",
"radius_unit": "miles"
}
}
]
}
]
Polygon GeoJson Example
[
{
"type": "Feature",
"geometry": {
"type": "Polygon",
"coordinates": [
[
[
29.606263327173277,
29.351260360166037
],
[
34.99803198126308,
31.068731175074266
],
[
38.10037765807652,
38.10601547327829
],
[
34.0451281074395,
42.78661881981615
],
[
29.26101553505825,
41.37872180435707
],
[
29.4745114657443,
29.280882894726226
],
[
29.606263327173277,
29.351260360166037
]
]
]
},
"properties": {}
}
]
Point GeoJson Example
[
{
"type": "Feature",
"geometry": {
"type": "Point",
"coordinates": [
49.34280616465017,
8.705301330275688
]
},
"properties": {
"radius": "50",
"radius_unit": "miles"
}
}
]
LineString GeoJson Example
[
{
"type": "Feature",
"geometry": {
"type": "LineString",
"coordinates": [
[
49.04556838804626,
8.086304761387936
],
[
49.010813048877765,
9.201322655465617
],
[
49.69274116024698,
9.621584068853792
]
]
},
"properties": {
"radius": "50",
"radius_unit": "miles"
}
}
]
Radius GeoJson Example
[
{
"type": "Feature",
"properties": {},
"geometry": {
"type": "Polygon",
"coordinates": [
[
[
49.395560890974714,
8.725988463242857
],
[
49.39431735512934,
8.709860145978645
],
[
49.39335813285867,
8.70463945564245
],
[
49.39213504391037,
8.699550732207248
],
[
49.39065564842198,
8.694625418953907
],
[
49.388929090054425,
8.689893941489448
],
[
49.38696603905746,
8.685385518697936
],
[
49.38477862585549,
8.68112798142023
],
[
49.38238036557867,
8.677147600009462
],
[
49.379786074021744,
8.67346892184647
],
[
49.37701177556626,
8.670114619829551
],
[
49.374074603651984,
8.667105352776481
],
[
49.37099269442947,
8.664459638594485
],
[
49.367785074266884,
8.662193740986464
],
[
49.364471541821445,
8.660321570369952
],
[
49.361072545417876,
8.65885459958994
],
[
49.395560890974714,
8.725988463242857
]
]
]
}
}
]
Validation Error messages
Subscription Errors
No active subscription found for this organization.
- Reason: Raised if no active subscription is found for the organization.
- Solution: Ensure the organization has an active subscription.
Your active subscription does not have access to this endpoint.
- Reason: Raised if the active subscription does not have access to the endpoint.
- Solution: Upgrade the subscription to gain access to the endpoint.
Category Filter Errors
Invalid value for category parameter.
- Reason: Raised if any category ID is not an integer.
- Solution: Ensure all category IDs are integers. Use only valid numeric category IDs.
No main-category or sub-category found for given id: {category_id}.
- Reason: Raised if no category or subcategory exists for the given ID.
- Solution: Verify that the provided category ID exists. Use existing category or subcategory IDs.
Country Filter Errors
Invalid value for the country parameter.
- Reason: Raised if any country ID is not an integer.
- Solution: Ensure all country IDs are integers. Use only valid numeric country IDs.
No country or region found for given id: {country_id}.
- Reason: Raised if no country or region exists for the given ID.
- Solution: Verify that the provided country ID exists. Use existing country or region IDs.
Published Since Seconds Errors
Invalid value for published_since_seconds. Must be a valid integer.
- Reason: Raised if the published_since_seconds is not an integer.
- Solution: Ensure that published_since_seconds is a valid integer.
Event Date Errors
Invalid value for event_start_date. Must be in YYYY-MM-DD format.
- Reason: Raised if event_start_date is not in the correct date format and event_end_date is missing.
- Solution: Ensure event_start_date is provided in the YYYY-MM-DD format.
Invalid value for event_end_date. Must be in YYYY-MM-DD format.
- Reason: Raised if event_end_date is not in the correct date format and event_start_date is missing.
- Solution: Ensure event_end_date is provided in the YYYY-MM-DD format.
Invalid value for event_start_date or event_end_date. Must be in YYYY-MM-DD format.
- Reason: Raised if both event_start_date and event_end_date are not in the correct date format.
- Solution: Ensure both event_start_date and event_end_date are provided in the YYYY-MM-DD format.
GeoJSON Errors
Invalid geometry.
- Reason: Raised if the “geometry” of the geo feature is incorrect (e.g., “{}” or “[]”).
- Solution: Ensure the “geometry” field of the geo feature is correctly formatted.
Invalid geofeature type.
- Reason: Raised if the “type” of the “geometry” of the geo feature is neither a “Polygon” nor “Point” nor “LineString”.
- Solution: Ensure the “type” field of the “geometry” is either “Polygon”, “Point”, or “LineString”.
Invalid coordinates provided.
- Reason: Raised if the “coordinates” of the “geometry” of the geo feature are incorrect.
- Solution: Ensure the “coordinates” field of the “geometry” is correctly formatted.
Radius or radiusUnit not provided for LineString.
- Reason: Raised if the “type” is “LineString” and neither the “radius” nor the “radius_unit” exist.
- Solution: Provide both “radius” and “radius_unit” for LineString features.
Invalid geoJSON format.
- Reason: Raised if the geoJSON format is incorrect.
- Solution: Ensure the geoJSON format adheres to the correct specifications.
Invalid geofeature.
- Reason: Raised if any error occurs that is not captured in previous validations.
- Solution: Ensure all fields and formats are correct as per the geoJSON specification.
Unsupported radius_unit: {radius_unit}. Supported units are ‘kilometers’ and ‘miles’.
- Reason: Raised if the radius_unit is neither “kilometers” nor “miles”.
- Solution: Use “kilometers” or “miles” as the radius unit.
Radius or radius_unit not provided for Point
- Reason: Raised if the “radius” or “radius_unit” is null for a Point.
- Solution: Provide both “radius” and “radius_unit” for Point features.
Keywords Validation Errors
Invalid keyword parameter. Please ensure you are sending a valid JSON encoded.
- Reason: Raised if keywords are not in the correct keyword JSON format.
- Solution: Ensure keywords are formatted correctly in the JSON request body.
Auto Date Range Errors
Invalid auto_date_range value.
- Reason: Raised if the auto_date_range value is not among the accepted values (‘Today’, ‘Past 7 days’, ‘Next 7 days’, ‘Past 30 days’, ‘Next 30 days’, ‘Custom timeframe’).
- Solution: Use a valid auto_date_range value from the accepted list.
For ‘Custom timeframe’ filter, event_start_date and event_end_date must be present.
- Reason: Raised if auto_date_range is ‘Custom timeframe’ and either event_start_date or event_end_date is missing.
- Solution: Provide both event_start_date and event_end_date for the ‘Custom timeframe’ filter.
Limitations
There is a limitation of 1000 requests per user per day and the API is paginated for retrieving reports. Each paginated page can contain a maximum of 200 reports.