> For the complete documentation index, see [llms.txt](https://api-v2-docs.disasteraware.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://api-v2-docs.disasteraware.com/osint-hazards/requesting-osint-hazards.md). # Requesting OSINT Hazards OSINT hazards are hazard events detected through proprietary processing of open-source intelligence — news articles, social network feeds, and other authoritative sources of information. Where the hazards returned by [Requesting Active Hazards](/hazards/requesting-active-hazards.md) originate from a single authoritative reporting agency (USGS for earthquakes, NHC for cyclones, and so on), OSINT hazards are detected by analysing and correlating open reporting, then resolving each event to a specific location and time. The result is a hazard feed covering event types that authoritative agencies do not routinely publish as structured hazard data — civil unrest, combat, terrorism, active-shooter incidents, and infrastructure and transport disruptions — alongside floods reported in the press. To request the list of current active OSINT hazards please use the route defined here: {% openapi src="/files/wYQaKpPZEdPb68ZWOF6w" path="/osint-hazards-query" method="get" %} [openapi.yaml](https://3664004773-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FbwQ2AvqpbIy1hD3QFTQG%2Fuploads%2Fgit-blob-ad3207376652be88415648e56d649a656e8df8f6%2Fopenapi.yaml?alt=media) {% endopenapi %} {% hint style="info" %} See [Authorizing Requests](/authentication/authorizing-requests.md#get-accesstoken-and-refreshtoken) page to get your accessToken. {% endhint %} {% hint style="warning" %} **This endpoint requires a specific role on your credentials.** It is not enabled by default, and credentials that work against the other hazard endpoints will not necessarily work here. If your token is valid elsewhere but this endpoint returns `403 Forbidden`, your credentials are missing the required role. Contact your sales contact or to have it added. {% endhint %} ## Response Format The API returns a **302 redirect** to a pre-signed S3 URL. Follow the `Location` header, then decompress the body: the object is **gzipped NDJSON** (newline-delimited JSON), with one complete hazard object per line. This is the same pattern used by [Requesting Active Hazards](/hazards/requesting-active-hazards.md), and it applies to both filtered and unfiltered requests. The pre-signed URL expires after 5 minutes. ## Feed Membership and Expiry This endpoint returns *active* hazards, so it is worth being precise about how long a hazard stays in the feed and how that relates to the event actually being over. These are three different things, and they are reported by three different fields. **How long a hazard stays in the feed** depends on whether its end has been determined: * **The end is known.** The hazard leaves the feed at `endedAt` plus a short linger period — **24 hours** for the discrete-event types (`TERRORISM`, `ACTIVESHOOTER`, `COMBAT`, `INCIDENT`), which are usually only reported after they have concluded, and **6 hours** for `CIVILUNREST` and `FLOOD`. Continued news coverage of an event that has already concluded does not extend its stay in the feed. * **The end is not known.** The hazard remains until a period passes with no new information about it: **96 hours** for most types, **168 hours** for `COMBAT` (active fronts can go quiet for days without being over), and **24 hours** for `ACTIVESHOOTER`. {% hint style="warning" %} **`endedAt` is always the detected end of the event, never the expiry time.** The linger period above is not added to it. Because a hazard can therefore appear in the active feed with an `endedAt` already in the past, decide relevance from `endedAt` rather than from the hazard's presence in the response. {% endhint %} The related fields, and what each one actually tells you: | Field | Question it answers | | ------------------------------ | --------------------------------------------------------------------------------- | | **endedAt** | When did the event end? | | **n2h.is\_ongoing** | Is the real-world event still unfolding? Independent of feed membership. | | **incident.properties.status** | The record's lifecycle state. `ACTIVE` on every record returned by this endpoint. | ## Hazard Types OSINT hazards are published under six types. | Type | Description | | ----------------- | --------------------------------------------------------------------------------- | | **CIVILUNREST** | Protests, strikes, riots, and demonstrations. | | **FLOOD** | Flood events reported in open sources. | | **COMBAT** | Military strikes and operations against military or state targets. | | **TERRORISM** | Attacks on civilian targets by non-state actors. | | **ACTIVESHOOTER** | Active-shooter incidents. | | **INCIDENT** | Infrastructure and transport disruptions — roads, rail, power, water, industrial. | Every OSINT hazard represents an observed event, so records are published with a `severity` of `WARNING` and a `category` of `EVENT`. The `severity` and `category` query parameters are accepted for consistency with `/active-hazards-query`, but they are not useful filters on this endpoint. ### Sub-types The `hazard_sub_type` field further classifies the hazard, and can be filtered with the `sub_type` query parameter. It is **guaranteed non-empty for every type except FLOOD**, which has no sub-type system and is always an empty string. Each type defines a **default** sub-type, shown in bold below, which is used when the reporting does not identify anything more specific. | Type | Sub-type values (default in **bold**) | | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | **CIVILUNREST** | **`PROTEST`**, `STRIKE`, `RIOT` | | **FLOOD** | — (always `""`) | | **COMBAT** | `AIRSTRIKE`, `MISSILESTRIKE`, `DRONESTRIKE`, `BOMBING`, `ARTILLERY`, **`GROUNDCOMBAT`**, `INVASION`, `NAVAL`, `IED`, `AMBUSH` | | **TERRORISM** | `BOMBING`, `SUICIDE_BOMBING`, `IED`, `VEHICLE_RAMMING`, `MASS_SHOOTING`, `KNIFE_ATTACK`, `HOSTAGE`, `ASSASSINATION`, `ARSON`, **`OTHER`** | | **ACTIVESHOOTER** | `MASS_SHOOTING`, `DRIVEBY`, `STANDOFF`, `SNIPER`, **`SHOOTING`**, `OTHER` | | **INCIDENT** | `ROAD_CLOSURE`, `BRIDGE`, `RAIL`, `PIPELINE`, `POWER`, `INDUSTRIAL`, `WATER`, **`OTHER`** | {% hint style="warning" %} **There is no `PORT` or `AIRPORT` sub-type.** A strike that shuts a port or an airport is typed by the *event* — a dockworkers' strike is `CIVILUNREST` / `STRIKE`, not an `INCIDENT` / `PORT`. The affected infrastructure is carried by the [supply-chain fields](#supply-chain-fields) instead. To find port and airport disruptions, filter with `supply_chain=true` and read `SupplyChainInfrastructure` — not `sub_type`. {% endhint %} ## Query Parameters The endpoint accepts the same parameters as `/active-hazards-query` — with the exception of `comment`, which is not supported — plus several parameters specific to OSINT hazards. All parameters are optional; when none are supplied, the full set of active OSINT hazards is returned. **Inherited from `/active-hazards-query`:** `name`, `type`, `severity`, `category`, `country`, `started_at`, `ended_at`, `created_at`, `updated_at`, `latitude`, `longitude`, and `uuid`. The four timestamp parameters take the format `YYYY-MM-DD HH:MM:SS`; `latitude` and `longitude` take a `min,max` range. Some of these behave differently here: `country` is considerably more permissive (covered below), while `severity` and `category` are constant across every OSINT hazard and so make poor filters. ### The `country` parameter The `country` parameter on this endpoint is more flexible than its counterpart on `/active-hazards-query`. It accepts three interchangeable forms, and the form is selected by the **length of the value you supply**: | Value length | Matching behaviour | Example | | -------------------- | ------------------------------------------------------- | -------------------------------------------------- | | 2 characters | Exact match on the ISO 3166-1 **alpha-2** country code. | `US` | | 3 characters | Exact match on the ISO 3166-1 **alpha-3** country code. | `USA` | | 4 or more characters | **Substring** match against the full country name. | `United States` matches `United States of America` | Because the 4-or-more case is a substring match, you do not have to supply the country's full canonical name. `United States` will match `United States of America`, and `Korea` will match both Korean entries — so use a longer, more specific string when you need to disambiguate. Comma-separated lists are supported, and the forms can be mixed: `country=US,JPN,United Kingdom`. {% hint style="info" %} This is a deliberate difference from [Requesting Active Hazards](/hazards/requesting-active-hazards.md), where the `country` parameter requires the full country name and does not accept ISO codes. {% endhint %} ### OSINT-specific parameters | Parameter | Description | | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **sub\_type** | Filter by `hazard_sub_type`. Pairs naturally with `type`. See [Sub-types](#sub-types) for the valid values of each type. Comma-separated list for multiple values. Filtering `FLOOD` by `sub_type` returns nothing, as floods carry no sub-type. | | **since** | Return only hazards whose `updatedAt` is at or after this timestamp. Intended as a watermark for incremental polling: store the highest `updatedAt` you have seen and pass it back on the next request. | | **bbox** | Filter to hazards whose centroid falls inside a bounding box, given as `minLon,minLat,maxLon,maxLat` (WGS84). | | **min\_precision** | Filter on the geographic precision of the resolved location (`n2h.location_level`). One of `point`, `city`, `county`, `corridor`, `river_corridor`, `chokepoint`, or `region` — `point` is the most precise and `region` the least. | | **supply\_chain** | When `true`, return only hazards that disrupt transport or shipping infrastructure — port strikes, canal closures, rail suspensions, airport shutdowns. | ## Response Fields Each hazard object follows the same shape as an active hazard, with the additions and exceptions noted below. | Field | Type | Description | | ---------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **uuid** | String | A unique universal identifier for the hazard. Stable across updates, so it can be used to correlate successive versions of the same event. | | **name** | Array | An array of objects, each defining the hazard name in a specific locale formatted according to RFC 5646 (e.g., "en" for US English). Each object contains `locale` and `value` keys. | | **description** | Array | An array of objects providing localized descriptions of the hazard, including a summary of the event and the publications it was drawn from. Each object contains `locale` (RFC 5646 format) and `value` keys. | | **severity** | String | Always `WARNING` for OSINT hazards. See [Requesting Hazard Severities](/hazards/requesting-active-hazards/requesting-hazard-severities.md) for the complete reference. | | **category** | String | Always `EVENT` for OSINT hazards. See [Requesting Hazard Categories](/hazards/requesting-active-hazards/requesting-hazard-categories.md) for the complete reference. | | **type** | String | The hazard type: `CIVILUNREST`, `FLOOD`, `COMBAT`, `TERRORISM`, `ACTIVESHOOTER`, or `INCIDENT`. | | **hazard\_sub\_type** | String | Sub-classification of the hazard type (e.g., `MISSILESTRIKE` for a COMBAT hazard, `RAIL` for an INCIDENT hazard). Guaranteed non-empty for every type except `FLOOD`, which is always an empty string. See [Sub-types](#sub-types). | | **comment** | String/Null | Optional comment. Currently not populated; reserved for future use. | | **createdAt** | Integer | Unix timestamp (seconds since epoch) indicating when the hazard object was first logged in the system. | | **startedAt** | Integer | Unix timestamp recording when the underlying event began. | | **updatedAt** | Integer | Unix timestamp capturing the last time the hazard object was updated. As additional reporting arrives, an event's casualty counts, geometry, and summary may all be revised. Use this field with the `since` parameter for incremental polling. | | **endedAt** | Integer | Unix timestamp of the **detected end** of the event. Never padded — a hazard lingers in the feed briefly after this time, but the value always reports when the event actually concluded. See [Feed Membership and Expiry](#feed-membership-and-expiry). | | **latitude** | Float | Geographic latitude of the event (WGS84 projection). | | **longitude** | Float | Geographic longitude of the event (WGS84 projection). | | **version** | Integer | Version counter, incremented each time the hazard object is modified. | | **creator** | String | The system that produced the record. | | **relatedHazards** | Array | A placeholder for future use. Currently returns an empty array. | | **incident** | Object | Details of the detected event. Contains **uuid**, **sourceRecordId**, **sourceId**, **type**, and **properties** — a dictionary of flat, query-friendly attributes describing the event. See [Incident Object](#incident-object) below. | | **source** | Object | Identifies the detection pipeline that produced the hazard, rather than a reporting agency. The publications an individual hazard was drawn from are listed in `n2h.sources`. | | **locationDetails** | Object | The administrative hierarchy resolved from the event's coordinates: `country`, `country_code` (ISO-2), `country_code_3` (ISO-3), `state_province`, `state_code`, `county`, `continent`, `subregion`, and `location_type`. | | **n2h** | Object | OSINT-specific detail — contributing articles, event-specific counters, and location precision. Present only on OSINT hazards. See [The n2h Object](#the-n2h-object) below. | | **alertGeometry** | Object | A GeoJSON FeatureCollection delineating an area for notification purposes, intended to intersect with user areas of interest for early warning. Intentionally larger than the actual impact area. | | **features** | Object | A GeoJSON FeatureCollection containing an `INCIDENT` point at the event location and a `SMART_ALERT` polygon defining the alert boundary. | | **exposureAreas** | Null | Not computed for OSINT hazards. Always null. | | **exposureAssessment** | Null | Not computed for OSINT hazards. Always null. | {% hint style="info" %} **Exposure data is not available on this endpoint.** `exposureAreas` and `exposureAssessment` are always null for OSINT hazards. The population and infrastructure exposure modelling described in [Requesting Active Hazards](/hazards/requesting-active-hazards.md#exposure-assessment) applies to hazards from authoritative agency sources only. {% endhint %} ## Field Details ### Incident Object The `incident.properties` object holds a flat set of attributes describing the detected event. Because it is flat and consistently named, it is the most convenient place to read event detail from. Fields present on every OSINT hazard: * `Country_Name` — the full country name in canonical form (e.g., `United States of America`) * `Country_Code` — ISO 3166-1 alpha-2 country code (e.g., `US`) * `Country_Code_3` — ISO 3166-1 alpha-3 country code (e.g., `USA`) * `Province_District_Town` — the most specific place name resolved for the event * `Incident_Type` — human-readable event type (e.g., `Civil Unrest`, `Combat`) * `Incident_Severity` — severity classification: `H` (high), `M` (medium), `L` (low) * `Scope_of_Incident` — geographic scope (e.g., `Local`, `Regional`) * `Event_Summary` — a short summary of the event * `Total_Fatalities` / `Total_Wounded` — casualty rollup * `Civilian_Fatalities` / `Civilian_Wounded`, `Police_Military_Fatalities` / `Police_Military_Wounded`, `Terrorist_Insurgent_Fatalities` / `Terrorist_Insurgent_Wounded` — casualty breakdown by affected group * `casualties` — a JSON string with the killed/injured breakdown * `status` — lifecycle state of the record * `sourceName` / `Source` — the publication the record was first raised from * `rawMessage` — the text of the source article * `bufferSize` — buffer distance in metres used to build the alert geometry {% hint style="warning" %} The country location fields describe **where the event happened, not who reported it**. They are derived from the event's resolved coordinates, so a strike in Ukraine reported by a newspaper in Hong Kong carries `Country_Code: "UA"`. {% endhint %} Additional fields appear depending on the hazard type — for example `Aggressor`, `Target`, and `Weapons_Used` on COMBAT hazards, or `Participants` and `Arrests` on CIVILUNREST hazards. These are documented on the individual sample pages. ### Supply-Chain Fields When an event physically disrupts the movement of goods, people, or energy through critical infrastructure, `incident.properties` carries an additional set of supply-chain fields. These are the fields behind the `supply_chain` query parameter, and they are how you find port, airport, canal, and chokepoint disruptions — **not** the sub-type, which describes the event rather than the infrastructure. Each field draws from a controlled vocabulary: | Field | Values | | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | **SupplyChainImpact** | `true`. The field is **only ever true** — it is absent from hazards that do not disrupt supply chains, rather than being set to false. | | **SupplyChainInfrastructure** | A comma-joined subset of `PORT`, `AIRPORT`, `RAIL`, `HIGHWAY`, `CANAL`, `STRAIT`, `BORDER`, `OIL_TERMINAL`, `PIPELINE`, `POWER_GRID`. | | **SupplyChainDisruptionType** | One of `STRIKE`, `CLOSURE`, `DELAYS`, `DAMAGE`, `BLOCKADE`, `SEIZURE`. | | **NamedChokepoint** | One of `HORMUZ`, `SUEZ`, `BAB_EL_MANDEB`, `MALACCA`, `PANAMA`, `BOSPHORUS`, `DARDANELLES`, `TAIWAN_STRAIT`, `ENGLISH_CHANNEL`, `KERCH_STRAIT`. | Two behaviours are worth knowing when you consume these fields: * **Impact is sticky.** Once a hazard is marked as supply-chain impacting, later reporting never clears it. A thin follow-up article that does not mention the disruption will not cause the flags to disappear. * **A named chokepoint changes the geometry.** When `NamedChokepoint` is set, the hazard's geometry is snapped to that waterway's polygon rather than being a buffer around a point. Expect `alertGeometry` to follow the shape of the strait or canal. Because `SupplyChainImpact` is absent rather than false when a hazard has no supply-chain dimension, test for the field's presence — do not test it for equality with `false`. ### The n2h Object The `n2h` object carries the detail specific to open-source detection. It is an extension to the core hazard shape and appears only on OSINT hazards. | Field | Type | Description | | ---------------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **hazard\_id** | String | A human-readable identifier for the event (e.g., `COMBAT-UKR-KYIV-2026-07`). | | **hazard\_sub\_type** | String | Sub-classification of the hazard type. Mirrors the top-level field. | | **summary** | String | A short summary of the event, synthesised from the contributing articles. | | **is\_ongoing** | Boolean | Whether the underlying real-world event is still unfolding. This is distinct from whether the record is still in the active feed — a hazard can remain active after the event itself has concluded. | | **start\_date\_iso** | String | The date the event began (ISO 8601 date). | | **end\_date\_iso** | String/Null | The date the event concluded, or null if it is still ongoing. | | **location\_level** | String | The geographic precision of the resolved location. One of `point`, `city`, `county`, `corridor`, `river_corridor`, `chokepoint`, or `region` — `point` is the most precise and `region` the least. Hazards are never published at country-level precision or coarser. This is the field behind the `min_precision` query parameter. | | **location\_specific** | String | The most specific place name resolved for the event. | | **country** | String | The country the event occurred in. | | **article\_count** | Integer | The number of articles that contributed to this hazard. A higher count indicates the event was more widely reported and therefore more strongly corroborated. | | **quantitative** | Object | Counters extracted from the reporting. **The keys vary by hazard type** — `participants` and `arrests` for civil unrest, `missiles_fired` and `drones_intercepted` for combat, `flood_depth_ft` and `homes_flooded` for flood. Treat this as an open map and read only the keys you need; do not assume a fixed set. | | **sources** | Array | The contributing articles. Each entry carries the publisher `name`, article `title`, `url`, feed `type`, `published_at`, and a `body` extract. Well-corroborated events can carry hundreds of entries. | | **extra** | Object | Internal pipeline diagnostics. Reserved for internal use — the contents are not part of the public contract and may change without notice. | {% hint style="info" %} `n2h.sources` is the audit trail for the hazard. Every OSINT hazard is derived from published reporting, and this array links back to the articles it was built from, so any record can be traced to its origin. {% endhint %} ### Features OSINT hazards include a `features` FeatureCollection with two `featureType` values: * **INCIDENT** — a point geometry at the event location, carrying event and casualty detail. * **SMART\_ALERT** — the alert boundary polygon. ## Hazard Samples A full sample response is provided for each of the six OSINT hazard types: * [Civil Unrest Sample](/osint-hazards/requesting-osint-hazards/civilunrest-sample.md) * [Flood Sample](/osint-hazards/requesting-osint-hazards/flood-sample.md) * [Combat Sample](/osint-hazards/requesting-osint-hazards/combat-sample.md) * [Terrorism Sample](/osint-hazards/requesting-osint-hazards/terrorism-sample.md) * [Active Shooter Sample](/osint-hazards/requesting-osint-hazards/activeshooter-sample.md) * [Incident Sample](/osint-hazards/requesting-osint-hazards/incident-sample.md)