Data Models

This page documents the complete data structures returned by the Corpus Product API.

EventResponse

The standard event object returned by list endpoints.

Fields

Field	Type	Description
`id`	UUID	Unique event identifier
`title`	string	Event title/headline
`description`	string	Detailed event description (nullable)
`eventCategory`	string	Category ID (e.g., “conflict”, “cyber”)
`eventType`	string	Type ID within category
`eventSubtype`	string	Subtype ID within type (nullable)
`eventDate`	date	Date when the event occurred, YYYY-MM-DD (nullable)
`eventDateEnd`	date	End date for multi-day events (nullable)
`location`	string	Specific location name (nullable)
`locationCountry`	string	ISO country code (nullable)
`locationCoordinates`	object	Coordinates object with `lat` and `lng` (nullable)
`fatalities`	integer	Number of reported fatalities (nullable)
`injuries`	integer	Number of reported injuries (nullable)
`abductions`	integer	Number of reported abductions (nullable)
`civilianTargeting`	boolean	Whether civilians were deliberately targeted (nullable)
`admin1`	string	First-level administrative division, e.g. state/province (nullable)
`admin2`	string	Second-level administrative division, e.g. district/county (nullable)
`admin3`	string	Third-level administrative division, e.g. commune/ward (nullable)
`geoPrecision`	integer	Geographic precision level (nullable). See Geo Precision Levels
`salienceScore`	float	Confidence score indicating how reliably the event has been verified (nullable). See Salience Score
`salienceRationale`	string	Human-readable explanation of the confidence assessment (nullable)
`articleCount`	integer	Number of source articles
`actorCount`	integer	Number of actors involved
`sourceDomains`	string[]	List of source domain URLs (nullable)
`createdAt`	datetime	When record was created
`updatedAt`	datetime	When record was last updated

Geo Precision Levels

The geoPrecision field follows ACLED convention for indicating the precision of location coordinates.

Value	Label	Description
1	Exact / rooftop	Coordinates correspond to a specific building, intersection, or precise point
2	District / city	Coordinates correspond to a named populated place such as a city or district centre
3	Approximate / country	Coordinates are approximate, typically placed at a regional or country centroid

Salience Score

The salienceScore field is a confidence score indicating how reliably the event has been verified. Scores below 0.75 are not included in the dataset.

Score	Label	Description
1.0	Confirmed	The event definitely happened. Reporting is consistent, independently corroborated across multiple credible channels, or comes from an authoritative monitoring system with a strong verification process.
0.94–0.99	High Confidence	The event almost certainly happened. It is sourced from established outlets or accounts with direct access to the situation, and the details align with other verifiable facts and known patterns in the area.
0.90–0.93	Credible	The event very likely happened. It is reported by a verified source with a known affiliation and is broadly consistent with the established pattern of activity in the region.
0.87–0.89	Probable	The event very likely happened, though the level of independent corroboration is more limited. It is often based on a single credible report or a small number of supporting signals, but still fits the broader context and pattern of activity in the area.
0.82–0.86	Likely	The event very likely happened, and the core claim appears solid. Confidence is slightly lower mainly because some details remain unclear, incomplete, or only partially verified, not because the event itself appears unlikely.
0.75–0.81	Unconfirmed	The event likely happened, but important details are still unconfirmed or only partially verified. This is a common confidence range in immediate monitoring, where the core event appears credible but reporting on the specifics may still be incomplete, inconsistent, or developing.
< 0.75	Plausible	The event may have happened, but the reporting is too limited, vague, or weakly sourced to meet the threshold for inclusion in the dataset.

Example JSON

{
  "id": "ad8b3d2a-353f-41fd-908d-780615f31673",
  "title": "353 killed, 60 kidnapped in violent attacks across Nigeria in June",
  "description": "A total of 353 people were killed and 60 were kidnapped in violent attacks across Nigeria in June.",
  "eventCategory": "crime",
  "eventType": "violence",
  "eventSubtype": null,
  "eventDate": "2026-06-01",
  "eventDateEnd": null,
  "location": "Nigeria",
  "locationCountry": "NG",
  "locationCoordinates": null,
  "fatalities": 353,
  "injuries": null,
  "abductions": 60,
  "civilianTargeting": true,
  "admin1": "Borno",
  "admin2": null,
  "admin3": null,
  "geoPrecision": 3,
  "salienceScore": null,
  "salienceRationale": null,
  "articleCount": 0,
  "actorCount": 0,
  "sourceDomains": null,
  "createdAt": "2026-02-13T22:29:32.845037Z",
  "updatedAt": "2026-02-13T22:29:32.845037Z"
}

EventDetailResponse

Extended event object with category-specific data. Includes all fields from EventResponse plus:

Field	Type	Description
`categorySpecificData`	object	Category-specific metadata fields (nullable)
`actorRolesBreakdown`	object	Breakdown of actors by role (nullable)

Category-Specific Data

The categorySpecificData field contains metadata fields defined by the event’s category. See each category’s taxonomy page for the specific fields available. Example for Conflict event:

{
  "id": "...",
  "title": "Armed clash between government and rebel forces",
  "eventCategory": "conflict",
  "eventType": "battles",
  "eventSubtype": "armed_clash",
  "eventDate": "2026-02-10",
  "eventDateEnd": null,
  "location": "Donetsk",
  "locationCountry": "UA",
  "locationCoordinates": {
    "lat": 48.0159,
    "lng": 37.8029
  },
  "fatalities": 15,
  "injuries": 23,
  "abductions": 0,
  "civilianTargeting": false,
  "admin1": "Donetsk Oblast",
  "admin2": "Donetsk",
  "admin3": null,
  "geoPrecision": 2,
  "salienceScore": 0.85,
  "salienceRationale": null,
  "articleCount": 3,
  "actorCount": 2,
  "sourceDomains": ["reuters.com", "bbc.co.uk"],
  "createdAt": "2026-02-10T14:30:00Z",
  "updatedAt": "2026-02-10T14:30:00Z",
  "categorySpecificData": {
    "disorder_type": "Political violence"
  },
  "actorRolesBreakdown": null
}

ActorResponse

The standard actor object returned by list endpoints.

Fields

Field	Type	Description
`id`	UUID	Unique actor identifier
`canonicalName`	string	Actor’s canonical/standardized name
`aliases`	string[]	Alternative names/spellings (nullable)
`description`	string	Description of the actor (nullable)
`articleCount`	integer	Number of articles mentioning this actor
`eventCount`	integer	Number of events involving this actor
`sourceDomains`	string[]	List of source domains (nullable)
`firstMentionDate`	date	Date of first mention (nullable)
`lastMentionDate`	date	Date of most recent mention (nullable)
`createdAt`	datetime	When record was created
`updatedAt`	datetime	When record was last updated

Note: The actor type/category is not included in the response object. To filter actors by type, use the actor_type query parameter when calling /v1/actors, and use the /v1/metadata/actor-types endpoint to discover available types.

Example JSON

{
  "id": "5a9c2a21-e326-4563-b425-a6490d4ccbe0",
  "canonicalName": "3M",
  "aliases": null,
  "description": "The mention of '3M' refers to the corporation, a large multinational conglomerate known for its diverse range of products.",
  "articleCount": 6,
  "eventCount": 0,
  "sourceDomains": [
    "www.boston25news.com",
    "www.facebook.com",
    "www.kimt.com",
    "www.local10.com"
  ],
  "firstMentionDate": null,
  "lastMentionDate": null,
  "createdAt": "2026-02-04T00:26:46.088359Z",
  "updatedAt": "2026-02-04T00:28:15.278086Z"
}

ActorDetailResponse

Extended actor object with relationship breakdowns. Includes all fields from ActorResponse plus:

Field	Type	Description
`eventTypesBreakdown`	object	Breakdown of events by type (nullable)
`rolesBreakdown`	object	Breakdown of actor roles across events (nullable)

PaginatedEventsResponse

Wrapper for paginated event listings.

Field	Type	Description
`items`	EventResponse[]	Array of events
`total`	integer	Total number of matching events
`page`	integer	Current page number
`pageSize`	integer	Number of items per page
`totalPages`	integer	Total number of pages

Example JSON

{
  "items": [...],
  "total": 49,
  "page": 1,
  "pageSize": 50,
  "totalPages": 1
}

PaginatedActorsResponse

Same structure as PaginatedEventsResponse but with items as ActorResponse[].

CountryAggregation

Country with event count.

Field	Type	Description
`country`	string	Country name
`eventCount`	integer	Number of events in this country

RegionAggregation

Location/region with event count.

Field	Type	Description
`location`	string	City/region name
`country`	string	Country name (nullable)
`eventCount`	integer	Number of events in this location

MetadataValueCount

Generic metadata value with count.

Field	Type	Description
`value`	string	The metadata value
`count`	integer	Number of occurrences

Used in responses from:

/v1/metadata/event-categories
/v1/metadata/event-types
/v1/metadata/event-subtypes
/v1/metadata/actor-types

Source Reliability

Sources attached to events carry a reliability_tier field that classifies the origin of the source material. This value is auto-assigned by the ingestion pipeline based on the scraper type that collected the article.

Value	Description
`news_outlet`	Established news organization (wire service, newspaper, broadcaster)
`social_media`	Social media platform post (Twitter/X, Facebook, Telegram, etc.)
`ai_generated`	Content produced by an AI model or automated summarisation pipeline
`unknown`	Source type could not be determined

Export Formats

The /v1/events/export endpoint supports multiple output formats:

CSV Format

Standard comma-separated values with headers. Includes all event fields plus actor information.

JSON Format

Array of EventDetailResponse objects with full metadata and actors.

GeoJSON Format

Geographic data format suitable for mapping applications:

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [-74.0060, 40.7128]
      },
      "properties": {
        "id": "...",
        "title": "...",
        "event_category": "...",
        ...
      }
    }
  ]
}

ACLED Format

Compatible with ACLED (Armed Conflict Location & Event Data Project) schema. Only available for conflict category events.

Key Actor Fields

Field	Type	Description
`actor1`	string	Principal (primary) actor in the conflict event
`assoc_actor_1`	string	Associated actors (internal sub-units of actor1), semicolon-separated
`supporting_actor_1`	string	External supporting actors for actor1, comma-separated
`inter1`	string	Inter-group code for actor1 (1=state, 2=rebel, 3=political militia, etc.)
`actor2`	string	Secondary (opposing) actor in the conflict event
`assoc_actor_2`	string	Associated actors (internal sub-units of actor2), semicolon-separated
`supporting_actor_2`	string	External supporting actors for actor2, comma-separated
`inter2`	string	Inter-group code for actor2
`interaction`	string	Interaction code combining inter1 and inter2 (e.g., “1-2” for state vs rebel)

Example:

{
  "event_id_cnty": "NGA12345678",
  "event_date": "2026-02-10",
  "event_type": "Battles",
  "sub_event_type": "Armed clash",
  "actor1": "Nigerian Army",
  "assoc_actor_1": "7th Division; 3rd Battalion",
  "supporting_actor_1": "French Air Force, U.S. Military Advisors",
  "inter1": "1",
  "actor2": "Boko Haram",
  "assoc_actor_2": "Shekau Faction",
  "supporting_actor_2": null,
  "inter2": "2",
  "interaction": "1-2",
  "location": "Maiduguri",
  "country": "Nigeria",
  "fatalities": 15
}

Flat Format

Denormalized JSON with actor positions as explicit columns, suitable for spreadsheet import and tabular analysis.

Actor Position Fields

Field	Type	Description
`principal_actor`	string	Principal (primary) actor name
`principal_actor_category`	string	Category of principal actor (state_forces, rebel_group, etc.)
`sub_principal_actors`	string	Internal sub-units of principal actor, semicolon-separated
`supporting_principal_actor`	string	External actors supporting principal, comma-separated
`secondary_actor`	string	Secondary (opposing) actor name
`secondary_actor_category`	string	Category of secondary actor
`sub_secondary_actors`	string	Internal sub-units of secondary actor, semicolon-separated
`supporting_secondary_actor`	string	External actors supporting secondary, comma-separated

Actor Position Hierarchy:

Principal/Secondary: Main actors in the event (actor1/actor2 in ACLED)
Sub-Principal/Sub-Secondary: Internal sub-units, factions, or branches within the same organization (e.g., “3rd Battalion” within “Nigerian Army”)
Supporting Principal/Supporting Secondary: External organizations providing support (e.g., “U.S. Special Forces” providing training to “Colombian Army”)

Example:

{
  "id": "ad8b3d2a-353f-41fd-908d-780615f31673",
  "title": "Armed clash between Nigerian forces and insurgents",
  "event_category": "conflict",
  "event_type": "battles",
  "event_subtype": "armed_clash",
  "event_date": "2026-02-10",
  "location": "Maiduguri, Borno State",
  "location_country": "NG",
  "principal_actor": "Nigerian Army",
  "principal_actor_category": "state_forces",
  "sub_principal_actors": "7th Division; 3rd Battalion",
  "supporting_principal_actor": "French Air Force, U.S. Military Advisors",
  "secondary_actor": "Boko Haram",
  "secondary_actor_category": "rebel_group",
  "sub_secondary_actors": "Shekau Faction",
  "supporting_secondary_actor": null,
  "salience_score": 0.85,
  "created_at": "2026-02-10T14:30:00Z",
  "updated_at": "2026-02-10T14:30:00Z"
}

← Back to Taxonomy Overview

GET STARTED

EVENT TAXONOMY

REFERENCE

Data Models Reference

Data Models

EventResponse

Fields

Geo Precision Levels

Salience Score

Example JSON

EventDetailResponse

Category-Specific Data

ActorResponse

Fields

Example JSON

ActorDetailResponse

PaginatedEventsResponse

Example JSON

PaginatedActorsResponse

CountryAggregation

RegionAggregation

MetadataValueCount

Source Reliability

Export Formats

CSV Format

JSON Format

GeoJSON Format

ACLED Format

Key Actor Fields

Flat Format

Actor Position Fields

GET STARTED

EVENT TAXONOMY

REFERENCE

​Data Models

​EventResponse

​Fields

​Geo Precision Levels

​Salience Score

​Example JSON

​EventDetailResponse

​Category-Specific Data

​ActorResponse

​Fields

​Example JSON

​ActorDetailResponse

​PaginatedEventsResponse

​Example JSON

​PaginatedActorsResponse

​CountryAggregation

​RegionAggregation

​MetadataValueCount

​Source Reliability

​Export Formats

​CSV Format

​JSON Format

​GeoJSON Format

​ACLED Format

​Key Actor Fields

​Flat Format

​Actor Position Fields

Data Models

EventResponse

Fields

Geo Precision Levels

Salience Score

Example JSON

EventDetailResponse

Category-Specific Data

ActorResponse

Fields

Example JSON

ActorDetailResponse

PaginatedEventsResponse

Example JSON

PaginatedActorsResponse

CountryAggregation

RegionAggregation

MetadataValueCount

Source Reliability

Export Formats

CSV Format

JSON Format

GeoJSON Format

ACLED Format

Key Actor Fields

Flat Format

Actor Position Fields