Export Events

Export all matching events in the specified format. Returns a streaming file download, not a JSON envelope. The response includes a Content-Disposition: attachment; filename="events.<ext>" header. Clients must write the response body directly to disk or a buffer — do not call .json() on the response.

response = requests.get(url, headers=headers, params=params, stream=True)
response.raise_for_status()
with open("events.csv", "wb") as f:
    for chunk in response.iter_content(chunk_size=8192):
        f.write(chunk)

Query Parameters

Parameter	Type	Required	Description
`format`	string	No	Export format: `csv` (default), `json`, `geojson`, `acled`, or `flat`
`event_category`	string[]	No	Filter by event category (repeatable)
`event_type`	string[]	No	Filter by event type within category (repeatable)
`event_subtype`	string[]	No	Filter by event subtype (repeatable)
`country`	string[]	No	Filter by country code (repeatable)
`date_from`	string	No	Start date (YYYY-MM-DD, inclusive)
`date_to`	string	No	End date (YYYY-MM-DD, inclusive)
`search`	string	No	Full-text search across title and description
`salience_score_min`	float	No	Minimum salience score
`salience_score_max`	float	No	Maximum salience score
`article_count_min`	integer	No	Minimum number of source articles (≥ 0)
`article_count_max`	integer	No	Maximum number of source articles (≥ 0)
`actor_count_min`	integer	No	Minimum number of actors involved (≥ 0)
`actor_count_max`	integer	No	Maximum number of actors involved (≥ 0)
`sort_by`	string	No	Sort column: `event_date` (default), `salience_score`, `article_count`, `title`, `created_at`
`sort_order`	string	No	Sort direction: `asc` or `desc` (default: `desc`)

Export Formats

CSV Format

Standard comma-separated values with headers. Includes all event fields plus flattened actor information. Use case: Import into Excel, Google Sheets, or data analysis tools Content-Type: text/csv; charset=utf-8 File extension: .csv Example Request:

curl -H "X-API-Key: your-api-key" \
  "https://api.corpus.intrace.ai/v1/events/export?format=csv&event_category=conflict&country=NG" \
  -o events.csv

JSON Format

Array of complete EventDetailResponse objects with full metadata and nested actors. Use case: Programmatic processing, full data fidelity, custom analysis Content-Type: application/json File extension: .json Response Structure:

[
  {
    "id": "ad8b3d2a-353f-41fd-908d-780615f31673",
    "title": "Armed clash between government and rebel forces",
    "description": "Detailed event description...",
    "eventCategory": "conflict",
    "eventType": "battles",
    "eventSubtype": "armed_clash",
    "eventDate": "2026-02-10",
    "location": "Maiduguri",
    "locationCountry": "NG",
    "fatalities": 15,
    "injuries": 23,
    "abductions": 0,
    "civilianTargeting": false,
    "admin1": "Borno",
    "admin2": "Maiduguri",
    "admin3": null,
    "geoPrecision": 1,
    "categorySpecificData": {
      "disorder_type": "Political violence"
    },
    "actorRolesBreakdown": {
      "perpetrator": ["Nigerian Army"],
      "subject": ["Boko Haram"]
    },
    "salienceScore": 0.85,
    "articleCount": 3,
    "actorCount": 2,
    "createdAt": "2026-02-10T14:30:00Z",
    "updatedAt": "2026-02-10T14:30:00Z"
  }
]

GeoJSON Format

RFC 7946 compliant GeoJSON FeatureCollection suitable for mapping applications. Use case: Mapping applications, GIS tools, Leaflet, Mapbox, OpenLayers Content-Type: application/geo+json File extension: .geojson Response Structure:

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [13.4302, 11.8311]
      },
      "properties": {
        "id": "ad8b3d2a-353f-41fd-908d-780615f31673",
        "title": "Armed clash between government and rebel forces",
        "event_category": "conflict",
        "event_type": "battles",
        "event_subtype": "armed_clash",
        "event_date": "2026-02-10",
        "location": "Maiduguri",
        "location_country": "NG",
        "admin1": "Borno",
        "admin2": "Maiduguri",
        "admin3": null,
        "geo_precision": 1,
        "salience_score": 0.85,
        "fatalities": 15
      }
    }
  ]
}

Example Request:

curl -H "X-API-Key: your-api-key" \
  "https://api.corpus.intrace.ai/v1/events/export?format=geojson&event_category=conflict&date_from=2026-01-01" \
  -o conflict_map.geojson

ACLED Format

Compatible with ACLED (Armed Conflict Location & Event Data Project) schema. Only available for conflict category events. Use case: Integration with existing ACLED workflows, research tools expecting ACLED format Content-Type: application/json File extension: .json

ACLED Field Mapping

Field	Type	Description
`event_id_cnty`	string	Event ID with country code prefix (e.g., “NGA12345678”)
`event_date`	string	Event date (YYYY-MM-DD)
`year`	integer	Event year
`time_precision`	integer	1=day, 2=week, 3=month (per ACLED standard)
`disorder_type`	string	Disorder classification (e.g., “Political violence”)
`event_type`	string	ACLED event type (e.g., “Battles”, “Violence against civilians”)
`sub_event_type`	string	ACLED sub-event type (e.g., “Armed clash”, “Attack”)
`actor1`	string	Principal (primary) actor name
`assoc_actor_1`	string	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 name
`assoc_actor_2`	string	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-inter2 (e.g., “1-2” for state vs rebel)
`civilian_targeting`	string	”Civilians targeted” or empty
`iso`	integer	ISO 3166-1 numeric country code
`region`	string	ACLED region name
`country`	string	Country name
`admin1`	string	First-level administrative division
`admin2`	string	Second-level administrative division
`admin3`	string	Third-level administrative division
`location`	string	Specific location name
`latitude`	float	Latitude coordinate
`longitude`	float	Longitude coordinate
`geo_precision`	integer	Geographic precision level: 1=exact/rooftop, 2=district/city, 3=approximate/country
`source`	string	Source names, semicolon-separated
`notes`	string	Event description/notes
`fatalities`	integer	Number of reported fatalities
`timestamp`	integer	Unix timestamp of event creation

Additional Non-ACLED Fields:

salience_score: Relevance/importance score (0.0-1.0)
salience_rationale: Explanation of salience score
dedup_key: Deduplication identifier
event_date_end: End date for multi-day events

Example Response:

[
  {
    "event_id_cnty": "NGA12345678",
    "event_date": "2026-02-10",
    "year": 2026,
    "time_precision": 1,
    "disorder_type": "Political violence",
    "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",
    "civilian_targeting": "",
    "iso": 566,
    "region": "Western Africa",
    "country": "Nigeria",
    "admin1": "Borno",
    "admin2": "Maiduguri",
    "admin3": null,
    "location": "Maiduguri",
    "latitude": 11.8311,
    "longitude": 13.4302,
    "geo_precision": 1,
    "source": "BBC News; Reuters",
    "notes": "Clashes erupted between Nigerian military and insurgent forces...",
    "fatalities": 15,
    "timestamp": 1707577200,
    "salience_score": 0.85,
    "salience_rationale": "Significant engagement in ongoing conflict",
    "dedup_key": "nigerian-army-boko-haram-maiduguri-clash",
    "event_date_end": null
  }
]

Example Request:

curl -H "X-API-Key: your-api-key" \
  "https://api.corpus.intrace.ai/v1/events/export?format=acled&event_category=conflict&country=NG&date_from=2026-01-01&date_to=2026-01-31" \
  -o nigeria_conflict_acled.json

Flat Format

Denormalized JSON with actor positions as explicit columns, suitable for spreadsheet import and tabular analysis. Use case: Spreadsheet import where actor relationships need to be explicit, business intelligence tools Content-Type: application/json File extension: .json

Flat Format Actor Fields

Field	Type	Description
`principal_actor`	string	Principal (primary) actor name
`principal_actor_category`	string	Category of principal (state_forces, rebel_group, etc.)
`sub_principal_actors`	string	Internal sub-units of principal, 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, semicolon-separated
`supporting_secondary_actor`	string	External actors supporting secondary, comma-separated

Example Response:

[
  {
    "id": "ad8b3d2a-353f-41fd-908d-780615f31673",
    "title": "Armed clash between Nigerian forces and insurgents",
    "description": "Clashes erupted...",
    "event_category": "conflict",
    "event_type": "battles",
    "event_subtype": "armed_clash",
    "event_date": "2026-02-10",
    "event_date_end": null,
    "date_precision": "day",
    "location": "Maiduguri, Borno State",
    "location_country": "NG",
    "location_coordinates": {
      "lat": 11.8311,
      "lng": 13.4302
    },
    "fatalities": 15,
    "injuries": 23,
    "abductions": 0,
    "civilian_targeting": false,
    "admin1": "Borno",
    "admin2": "Maiduguri",
    "admin3": null,
    "geo_precision": 1,
    "category_specific_data": {
      "disorder_type": "Political violence"
    },
    "salience_score": 0.85,
    "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,
    "created_at": "2026-02-10T14:30:00Z",
    "updated_at": "2026-02-10T14:30:00Z"
  }
]

Example Request:

curl -H "X-API-Key: your-api-key" \
  "https://api.corpus.intrace.ai/v1/events/export?format=flat&event_category=conflict&date_from=2026-01-01" \
  -o events_flat.json

Actor Position Hierarchy

Understanding the actor position fields in ACLED and Flat formats:

Position Types

Principal/Secondary (actor1/actor2): Main actors in the event
Sub-Principal/Sub-Secondary (assoc_actor_1/assoc_actor_2): Internal organizational units
- Same organization as the main actor
- Examples: military divisions, regional branches, internal factions
Supporting Principal/Supporting Secondary (supporting_actor_1/supporting_actor_2): External support
- Different organizations providing assistance
- Examples: foreign military support, allied groups, coalition partners

Example Scenarios

Military operation with foreign support:

actor1: "Nigerian Army"
assoc_actor_1: "7th Division; 3rd Battalion"
supporting_actor_1: "French Air Force, U.S. Military Advisors"

Rebel coalition:

actor1: "Free Syrian Army"
assoc_actor_1: "Southern Front; Damascus Brigade"
supporting_actor_1: "Turkish Armed Forces"

actor2: "Syrian Arab Army"
assoc_actor_2: "4th Armored Division; Republican Guard"
supporting_actor_2: "Russian Aerospace Forces, Hezbollah"

Response Codes

Code	Description
200	Success - returns data in requested format
400	Bad Request - invalid format or filter parameters
401	Unauthorized - missing or invalid API key
422	Validation Error - filter values failed validation
500	Server Error - contact support if persistent

Rate Limits

100 requests per minute per API key
10,000 requests per day per API key

Contact support for higher limits if needed for your use case.

Events

Actors

Locations

Metadata

Query Parameters

Export Formats

CSV Format

JSON Format

GeoJSON Format

ACLED Format

ACLED Field Mapping

Flat Format

Flat Format Actor Fields

Actor Position Hierarchy

Position Types

Example Scenarios

Response Codes

Rate Limits

See Also

Events

Actors

Locations

Metadata

​Query Parameters

​Export Formats

​CSV Format

​JSON Format

​GeoJSON Format

​ACLED Format

​ACLED Field Mapping

​Flat Format

​Flat Format Actor Fields

​Actor Position Hierarchy

​Position Types

​Example Scenarios

​Response Codes

​Rate Limits

​See Also

Query Parameters

Export Formats

CSV Format

JSON Format

GeoJSON Format

ACLED Format

ACLED Field Mapping

Flat Format

Flat Format Actor Fields

Actor Position Hierarchy

Position Types

Example Scenarios

Response Codes

Rate Limits

See Also