> ## Documentation Index > Fetch the complete documentation index at: https://docs.corpus.intrace.ai/llms.txt > Use this file to discover all available pages before exploring further. # Data Models Reference > Complete field structures and schemas for events, actors, and locations # 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](#geo-precision-levels) | | `salienceScore` | float | Confidence score indicating how reliably the event has been verified (nullable). See [Salience Score](#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 ```json theme={null} { "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:** ```json theme={null} { "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 ```json theme={null} { "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 ```json theme={null} { "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: ```json theme={null} { "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:** ```json theme={null} { "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:** ```json theme={null} { "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](/guides/corpus-api/taxonomy)