> 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-2e1a036a6f2b8e6525a79c7089f3afec78a9419e%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 %} {% hint style="info" %} **Record shape change, September 2026.** OSINT records changed shape in a coordinated cutover: the sub-type moved from a top-level `hazard_sub_type` field to `incident.properties.subType`, `locationDetails` became `location`, several legacy `incident.properties` keys were retired or renamed, and severity is now graded rather than uniformly `WARNING`. This page describes the new shape. A record published before the cutover keeps the old shape until it is next updated, so for a short period both shapes appear in the feed together. Read `incident.properties.subType` and `location`, and fall back to `hazard_sub_type` and `locationDetails` only while the transition lasts. {% 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, or will, the event end? `incident.properties.endedAtKind` says which: `observed` or `projected`. | | **n2h.is\_ongoing** | Is the real-world event still unfolding? Independent of feed membership. | | **incident.properties.status** | The record's lifecycle state. `ACTIVE` for every live record, including one whose end has been detected and that is lingering. `EXPIRED` only on merge tombstones, which always carry `supersededBy` and stay in the feed for about 24 hours after the merge. | ## 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 `category` of `EVENT`. Severity is graded per record; see [Severity](#severity). ### Severity OSINT hazards carry one of three severity tiers. They are the same values used by every other endpoint (see [Requesting Hazard Severities](/hazards/requesting-active-hazards/requesting-hazard-severities.md)); OSINT simply never emits `INFORMATION`. | Tier | Meaning | | ------------ | ----------------------------------------------------------------------------------------------------------- | | **WARNING** | Confirmed life or property impact, or a magnitude at which protective action is expected near the geometry. | | **WATCH** | Significant or growing; credible threat indicators without confirmed major impact. | | **ADVISORY** | A real event with minor or contained impact; situational awareness only. | The tier is computed in two deterministic layers. A **magnitude rule** per type turns the event's reported figures and sub-type into a base tier. A shared **confidence cap** can then demote that tier — never promote it — when the location is uncertain. A large event on a shaky location still surfaces, but it will not carry `WARNING` on a polygon that has not been verified, and `ADVISORY` is the floor: a real event is never hidden for confidence reasons. Because both layers are recomputed every time new reporting arrives, the tier moves in both directions: an event that grows crosses from `WATCH` to `WARNING`, and a casualty correction can lower a tier. Tier changes are ordinary updates and bump `updatedAt`. Records that have left the feed keep their last computed tier. #### Magnitude rules by type The thresholds below are indicative and subject to tuning. Unobserved figures count as zero — an absent casualty count is not evidence of casualties. | Type | `WARNING` | `WATCH` | `ADVISORY` | | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **FLOOD** | Any deaths, 100+ evacuees, 100+ homes flooded, or damage of $10M+ | Injuries, rescues, any evacuees or flooded homes, depth of 2 ft+, or 3+ roads closed | Street ponding or rain coverage with no human-impact figures | | **COMBAT** | Any deaths, 5+ wounded, buildings destroyed, displacement, territory captured, or the `INVASION` sub-type | 1–4 wounded, buildings damaged, or ordnance that got through defences with no casualty figures yet | Fully intercepted barrages and strikes with zero reported impact. The record's description states "intercepted" or "no reported impact" whenever this drives the tier. | | **TERRORISM** | Any deaths, hostages, or 5+ injuries | 1–4 injuries, building damage, or an attack disrupted in progress | Failed or thwarted, no casualties, no damage | | **CIVILUNREST** | Any deaths, 10+ injuries, or a `RIOT` with 50+ arrests | `RIOT` sub-type, any injuries or arrests, or 5,000+ participants | Peaceful protest or strike. **Never reaches `WARNING` on size alone.** | | **ACTIVESHOOTER** | Any deaths, injuries or hostages, **or the situation is unresolved** (no suspect yet killed or arrested), even at zero reported casualties | Resolved with nobody hit | Shots-fired reports, no injuries, resolved | | **INCIDENT** | Deaths, missing persons, 100+ evacuated, or 10,000+ households without power | Injuries, any evacuation, any household outages | Closures and disruptions with no human-impact figures | #### Confidence cap Each rule caps the tier at `WATCH`; the reason is recorded in `severityBasis.capReason`: | `capReason` | When it fires | | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **location\_level\_region** | The location resolved only to region level. A region-sized geometry is too coarse for an actionable `WARNING`. | | **geometry\_unverified** | The independent verification pass could not confirm the geometry **and** the record has fewer than ten contributing articles. Convergent coverage from many articles deliberately overrides a single verification verdict's doubt. | | **low\_location\_confidence** | Geocode confidence below 0.3 on a location coarser than a point. | Every graded record explains its tier in `incident.properties.severityBasis`, an object with three keys: | Key | Meaning | | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | **base** | The tier the event's magnitude alone would give it. | | **cap** | The tier actually emitted after the confidence cap. Present only when a cap applied. | | **capReason** | Why the cap applied: one of `location_level_region`, `geometry_unverified`, or `low_location_confidence`. Present only when a cap applied. | The `severity` query parameter is therefore a useful filter on this endpoint: `severity=WARNING` returns only confirmed-impact events. {% hint style="warning" %} **Phase-in.** The active feed was regraded in one pass on 2026-09-16. The only records without `severityBasis` are merge tombstones (`status: EXPIRED`, carrying `supersededBy`) that were created before that pass; they retain their pre-grading severity (uniform `WARNING`) and leave the feed within about 24 hours, so the ungraded tail disappears on its own and never grows. Every `ACTIVE` record is graded. Treat a record without `severityBasis` as ungraded rather than as confirmed impact. The presence of `severityBasis` is the reliable signal that a tier means what this section says. {% endhint %} ### Sub-types The sub-type further classifies the hazard. It lives at **`incident.properties.subType`** and can be filtered with the `sub_type` query parameter. The `n2h.hazard_sub_type` field mirrors it. The two axes are deliberately independent: **`type` encodes the target or actor class, `subType` encodes the mechanism.** A Russian airstrike on Kyiv is `COMBAT` / `AIRSTRIKE`; a car bomb at a market is `TERRORISM` / `BOMBING`; a workplace shooting is `ACTIVESHOOTER` / `MASS_SHOOTING`. The same mechanism can therefore appear under more than one type — `BOMBING`, `IED` and `MASS_SHOOTING` are all shared. Values are UPPERCASE, single-valued, and drawn from a closed vocabulary per type. Some types define a **default** (shown in bold) used when reporting does not identify anything more specific, so the field is always present for those types. `FLOOD` has no sub-type vocabulary, and the field is **omitted entirely** on flood records — never an empty string. A sub-type may be refined on a later update as evidence arrives (`BOMBING` becoming `SUICIDE_BOMBING`, for instance). | Type | Sub-type values (default in **bold**) | | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **CIVILUNREST** | **`PROTEST`**, `STRIKE`, `RIOT` | | **FLOOD** | — (field omitted) | | **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`** | | *WILDFIRE* | `FOREST`, `BRUSH`, `GRASS`, `URBAN_INTERFACE`, `PRESCRIBED_BURN`, `ESCAPED_PRESCRIBED_BURN` — *reserved; OSINT does not currently publish wildfires. No default: omitted when undetermined.* | | *BIOMEDICAL* | `SMOKE` — *used by other pipelines; surfaces via the historical archive, not this endpoint.* | The same vocabulary is shared with the historical archive, where it is filtered with the same `sub_type` parameter on [`/historical-hazards-query`](/hazards/requesting-historical-hazards.md). {% 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, read `supplyChainInfrastructure` on each record — do not look for them in `subType`. {% 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. Two of these behave differently here: `country` is considerably more permissive (covered below), and `category` is constant across every OSINT hazard and so makes a poor filter. `severity` is a useful filter now that OSINT records are graded. ### 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 `incident.properties.subType`. Pairs naturally with `type`. Comma-separated list for multiple values; values are case-sensitive UPPERCASE — see [Sub-types](#sub-types). Filtering `FLOOD` by `sub_type` returns nothing, as floods carry no sub-type. | | **hazard\_sub\_type** | **Deprecated** alias of `sub_type`, kept for clients written before the September 2026 cutover. Identical behaviour. Use `sub_type` in new code. | ## 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 | `ADVISORY`, `WATCH`, or `WARNING`, graded per record and explained by `incident.properties.severityBasis`. See [Severity](#severity). | | **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`. | | **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 `updated_at` 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`. | | **location** | Object | The administrative hierarchy resolved from the event's coordinates, in the same snake\_case block used by the historical archive. See [Location Block](#location-block). Replaces the pre-cutover `locationDetails`. | | **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. Keys are camelCase, with one deliberate exception: the three country fields keep their legacy names because the `country` filter is built on them. **Identity and classification** * `subType` — the sub-type; see [Sub-types](#sub-types). Omitted on `FLOOD`. * `recordOrigin` — where the record came from: always `live` for OSINT (the pipeline emits records as events are detected). Other values in the shared vocabulary, `backfill` and `converted-v1`, identify historical-archive records and never appear on this endpoint. * `status` — lifecycle state. `ACTIVE` for live records. `EXPIRED` on tombstones, which remain in the feed for about 24 hours so that consumers see the merge rather than a vanished uuid; every `EXPIRED` record in the feed carries `supersededBy`. * `supersededBy` — present only on a tombstone: when two records are found to describe the same event and are merged, the losing record's final update carries the surviving record's `uuid` here, and its `status` becomes `EXPIRED`. A uuid never silently disappears from the feed. Follow `supersededBy` to the keeper and drop the tombstone. **Location** * `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`) * `locationDescription` — the place description as written up (e.g., `Amritsar, Punjab, India`) * `provinceDistrictTown` — the most specific place name resolved for the event **Timing** * `eventDate`, `reportDate`, `createdTime` — ISO 8601, `Z` suffix * `incidentDuration` — duration in days * `endedAtKind` — present, with the value `projected`, whenever the event is still ongoing and the top-level `endedAt` is the pipeline's projection of when it will age out. **Omitted when the end was observed.** An `endedAt` without `endedAtKind` is therefore a real, reported end. See [Feed Membership and Expiry](#feed-membership-and-expiry). **Impact** * `totalFatalities` / `totalWounded`, `civilianFatalities` / `civilianWounded` — casualty counts as reported. **Null when not observed, never `0`.** An absent figure means the reporting did not state one, not that there were none. * `severityBasis` — the object explaining the record's tier; see [Severity](#severity). Present on every `ACTIVE` record; absent only on pre-cutover tombstones. `cap` and `capReason` appear only when a cap applied. * Type-specific quantitative figures, mirrored 1:1 from `n2h.quantitative` and keeping their snake\_case names — for example `deaths`, `injuries`, `participants`, `arrests`, `flood_depth_ft`, `homes_flooded`, `roads_closed`, `evacuees`, `damage_estimate_usd`. **Provenance and text** * `sourceName` — the publication the record was first raised from * `incidentType`, `name`, `eventSummary` — human-readable type, title, and short summary * `rawMessage` — the text of the source article * `bufferSize` — buffer distance in metres used to build the alert geometry * `scopeOfIncident`, `action`, `roles`, `featureType`, `type` — platform bookkeeping fields shared with other hazard sources **Retired or renamed at the September 2026 cutover.** These keys no longer appear on new-shape records. Renamed to camelCase: `Total_Fatalities` → `totalFatalities`, `Total_Wounded` → `totalWounded`, `Civilian_*` likewise, `Event_Summary` → `eventSummary`, `Province_District_Town` → `provinceDistrictTown`, `Incident_Type` → `incidentType`, `Incident_Duration` → `incidentDuration`, `Created_Time` → `createdTime`, `SupplyChain*` → `supplyChain*`, `NamedChokepoint` → `namedChokepoint`, and the COMBAT extras `Aggressor` / `Target` / `Infrastructure_Hit` / `Weapons_Used` → `aggressor` / `target` / `infrastructureHit` / `weaponsUsed`. Removed outright: `Police_Military_*` and `Terrorist_Insurgent_*` (never extracted; were hard-coded to `0`), the JSON-string `casualties` (use the scalar fields), `Incident_Severity` (`H`/`M`/`L`, replaced by graded top-level `severity`), `Scope_of_Incident` (duplicate of `scopeOfIncident`), and `Source` (duplicate of `sourceName`). The quantitative figures in `n2h.quantitative` are unchanged. {% 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`, `infrastructureHit` and `weaponsUsed` on COMBAT hazards, or `participants` and `arrests` on CIVILUNREST hazards. These are documented on the individual sample pages. ### Location Block `location` is the reverse-geocoded administrative context of the event, in the same snake\_case block the historical archive uses (see [Requesting Historical Hazards](/hazards/requesting-historical-hazards.md#the-full-record)). OSINT populates a subset of that block's keys — its geocoder resolves to admin-1, not admin-2 — and adds `location_type`: | Key | Meaning | | ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **admin0**, **admin0\_iso2**, **admin0\_iso3** | Country name and ISO 3166-1 codes. Same values as the `Country_*` properties. | | **admin1**, **admin1\_code** | State or province, and its ISO 3166-2 code (e.g., `US-DC`). `admin1_code` is omitted when no code could be resolved; `admin0_iso3` may likewise be absent for a small number of records. | | **continent**, **subregion** | UN M49 continent and sub-region names. | | **location\_type** | `land` or `ocean`. A small number of records currently carry a nonconforming value in this key pending a pipeline fix; treat anything other than `land` or `ocean` as unknown. | | **geocode\_fallback** | Optional. `true` when the point was placed by the nearest-place fallback (within 50 km) after a polygon miss — the location is right to the named area but not to the exact point. Absent otherwise. | | **source** | The geocoder that produced the block. | The block replaces the pre-cutover `locationDetails` object, which used different key names (`country_code`, `state_province`, and so on). The `Country_*` keys in `incident.properties` are unchanged and remain the contract behind the `country` filter. ### 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. They are how you find port, airport, canal, and chokepoint disruptions — **not** the sub-type, which describes the event rather than the infrastructure. There is no server-side filter for them; filter client-side on `supplyChainImpact`. Before the September 2026 cutover these keys were `SupplyChainImpact`, `SupplyChainInfrastructure`, `SupplyChainDisruptionType` and `NamedChokepoint`. 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 | Internal mirror of `incident.properties.subType`. May be an empty string where the properties key is omitted; prefer the properties key. | | **superseded\_by** | String | On a tombstone, the surviving record's uuid. Mirror of `incident.properties.supersededBy`. | | **location\_details** | Object | The raw geocoder output the `location` block was built from. Prefer `location`. | | **enhancedAt** / **enhancer** | Integer / String | When the block was last computed (epoch seconds) and by which pipeline version. | | **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. | | **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)