> ## 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. # Export Events > Bulk export events in CSV, JSON, GeoJSON, ACLED, or flat format 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."` header. Clients must write the response body directly to disk or a buffer — do not call `.json()` on the response. ```python theme={null} 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:** ```bash theme={null} 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:** ```json theme={null} [ { "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:** ```json theme={null} { "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:** ```bash theme={null} 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:** ```json theme={null} [ { "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:** ```bash theme={null} 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:** ```json theme={null} [ { "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:** ```bash theme={null} 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 1. **Principal/Secondary (actor1/actor2)**: Main actors in the event 2. **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 3. **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. ## See Also * [List Events](/api-reference/corpus/events/list-events) - Paginated event listing * [Get Event](/api-reference/corpus/events/get-event) - Single event details * [Data Models](/guides/corpus-api/taxonomy/data-models) - Complete field specifications * [Actor Types](/guides/corpus-api/taxonomy/actor-types) - Actor classification reference