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
`event_date`	date	Date when the event occurred (YYYY-MM-DD)
`event_category`	string	Category ID (e.g., “conflict”, “cyber”)
`event_type`	string	Type ID within category
`event_subtype`	string	Subtype ID within type
`country`	string	Country where event occurred
`location`	string	Specific location/city
`latitude`	float	Latitude coordinate (nullable)
`longitude`	float	Longitude coordinate (nullable)
`source_url`	string	URL to source article (nullable)
`created_at`	datetime	When record was created

Example JSON

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "title": "Cyber attack targets financial institutions",
  "description": "A sophisticated ransomware attack affected multiple banks...",
  "event_date": "2026-02-15",
  "event_category": "cyber",
  "event_type": "cyber_attack",
  "event_subtype": "ransomware",
  "country": "United States",
  "location": "New York",
  "latitude": 40.7128,
  "longitude": -74.0060,
  "source_url": "https://example.com/article",
  "created_at": "2026-02-15T14:30:00Z"
}

EventDetailResponse

Extended event object with actors and category-specific metadata. Includes all fields from EventResponse plus:

Field	Type	Description
`actors`	ActorInEvent[]	List of actors involved in the event
`metadata`	object	Category-specific metadata fields

ActorInEvent Structure

Field	Type	Description
`id`	UUID	Actor unique identifier
`canonical_name`	string	Actor’s canonical name
`actor_type`	string	Actor type classification
`position`	string	Actor’s role: PRINCIPAL, SECONDARY, SUB_PRINCIPAL, SUB_SECONDARY, SUPPORTING_PRINCIPAL, SUPPORTING_SECONDARY

Metadata by Category

The metadata field contains category-specific fields. See each category’s taxonomy page for field definitions. Example for Conflict event:

{
  "id": "...",
  "title": "Armed clash between government and rebel forces",
  "event_category": "conflict",
  "event_type": "battles",
  "event_subtype": "armed_clash",
  "actors": [
    {
      "id": "actor-uuid-1",
      "canonical_name": "National Army",
      "actor_type": "military",
      "position": "PRINCIPAL"
    },
    {
      "id": "actor-uuid-2",
      "canonical_name": "Rebel Group X",
      "actor_type": "rebel_group",
      "position": "SECONDARY"
    }
  ],
  "metadata": {
    "disorder_type": "Political violence",
    "fatalities": 15,
    "injuries": 23,
    "civilian_targeting": false
  }
}

ActorResponse

The standard actor object returned by list endpoints.

Fields

Field	Type	Description
`id`	UUID	Unique actor identifier
`canonical_name`	string	Actor’s canonical/standardized name
`actor_type`	string	Actor type classification
`aliases`	string[]	Alternative names/spellings (nullable)
`created_at`	datetime	When record was created

Example JSON

{
  "id": "660e8400-e29b-41d4-a716-446655440000",
  "canonical_name": "National Liberation Front",
  "actor_type": "rebel_group",
  "aliases": ["NLF", "Liberation Front"],
  "created_at": "2026-01-10T09:00:00Z"
}

ActorDetailResponse

Extended actor object with statistics and relationships. Includes all fields from ActorResponse plus:

Field	Type	Description
`event_count`	integer	Number of events this actor is involved in
`first_event_date`	date	Date of first associated event (nullable)
`last_event_date`	date	Date of most recent event (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
`page_size`	integer	Number of items per page
`total_pages`	integer	Total number of pages

Example JSON

{
  "items": [...],
  "total": 1234,
  "page": 1,
  "page_size": 50,
  "total_pages": 25
}

PaginatedActorsResponse

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

CountryAggregation

Country with event count.

Field	Type	Description
`country`	string	Country name
`event_count`	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
`event_count`	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/corpus/metadata/event-categories
/v1/corpus/metadata/event-types
/v1/corpus/metadata/event-subtypes
/v1/corpus/metadata/actor-types

Export Formats

The /v1/corpus/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.

Flat Format

Denormalized JSON with one object per event-actor combination, suitable for spreadsheet import. ← Back to Taxonomy Overview

GET STARTED

EVENT TAXONOMY

REFERENCE

Data Models Reference

Data Models

EventResponse

Fields

Example JSON

EventDetailResponse

ActorInEvent Structure

Metadata by Category

ActorResponse

Fields

Example JSON

ActorDetailResponse

PaginatedEventsResponse

Example JSON

PaginatedActorsResponse

CountryAggregation

RegionAggregation

MetadataValueCount

Export Formats

CSV Format

JSON Format

GeoJSON Format

ACLED Format

Flat Format

GET STARTED

EVENT TAXONOMY

REFERENCE

​Data Models

​EventResponse

​Fields

​Example JSON

​EventDetailResponse

​ActorInEvent Structure

​Metadata by Category

​ActorResponse

​Fields

​Example JSON

​ActorDetailResponse

​PaginatedEventsResponse

​Example JSON

​PaginatedActorsResponse

​CountryAggregation

​RegionAggregation

​MetadataValueCount

​Export Formats

​CSV Format

​JSON Format

​GeoJSON Format

​ACLED Format

​Flat Format

Data Models

EventResponse

Fields

Example JSON

EventDetailResponse

ActorInEvent Structure

Metadata by Category

ActorResponse

Fields

Example JSON

ActorDetailResponse

PaginatedEventsResponse

Example JSON

PaginatedActorsResponse

CountryAggregation

RegionAggregation

MetadataValueCount

Export Formats

CSV Format

JSON Format

GeoJSON Format

ACLED Format

Flat Format