CAMEO Codebook

April 20, 2026 · View on GitHub

A consolidated, machine-readable version of the CAMEO (Conflict and Mediation Event Observations) codebook used by GDELT, ACLED, and other political event data projects.

This is an unofficial derivative work. The canonical source is the CAMEO Manual 1.1b3 PDF. This repository exists because no unified JSON/YAML machine-readable version of the full codebook + data dictionary was publicly available.

.
├── data/
│   ├── cameo.json            # unified codebook (single source of truth)
│   ├── cameo.yaml            # same, YAML
│   ├── lookups/              # GDELT lookup CSVs (authoritative code→label)
│   │   ├── event_codes.csv   # 310 CAMEO event codes (with Goldstein scale)
│   │   ├── country_codes.csv # 261 country codes
│   │   ├── ethnic_groups.csv # 646 ethnic group codes
│   │   ├── known_groups.csv  # 117 known international orgs/groups
│   │   ├── religions.csv     # 31 religion top-level codes
│   │   └── actor_types.csv   # 40 actor-type role codes
│   └── tables/               # PDF-extracted tables (rich descriptions, hierarchy, regional)
├── text/                     # per-chapter raw text from the PDF manual
├── sources/
│   ├── CAMEO.Manual.1.1b3.pdf       # original manual (cached)
│   ├── CAMEO.*.txt                  # GDELT lookup files (cached)
│   └── chapters/                    # PDF split into 15 chapters
├── external/
│   └── country-codes-datasets.csv   # datasets/country-codes (ISO enrichment)
└── scripts/
    ├── extract.py            # pdftk + pdfplumber extraction
    ├── build.py              # assemble unified cameo.json
    └── probe_tables.py       # layout debugging helper

Data Dictionary

See DATA_DICTIONARY.md for field-level documentation of every section in cameo.json.

Sources

Source	URL	License
CAMEO Manual 1.1b3	http://data.gdeltproject.org/documentation/CAMEO.Manual.1.1b3.pdf	CC BY-NC-SA 3.0
GDELT CAMEO lookups	https://www.gdeltproject.org/data/lookups/	Open (GDELT terms)
datasets/country-codes	https://github.com/datasets/country-codes	ODC PDDL

Original CAMEO authors: Philip A. Schrodt, Deborah J. Gerner, Ömür Yılmaz — Penn State Event Data Project.

Extraction

Date: 2026-04-20
Method:
- PDF split into 15 chapter files using pdftk cat.
- Tables extracted with pdfplumber.extract_tables() (default settings).
- Raw per-page text via pdfplumber.Page.extract_text().
- Religious classification (file 11) fell back to regex over raw text due to merged-cell layout.
- GDELT lookup files pulled verbatim from gdeltproject.org.
- datasets/country-codes joined on ISO 3166-1 alpha-3 for country enrichment (228/261 CAMEO codes matched).
Verification: Tables in data/tables/ are derived; compare against sources/chapters/ PDFs for any suspected parse errors.

Editorial Changes from the Source

This repository applies a minimal set of modernizations to the derived outputs (data/cameo.json, data/cameo.yaml, and data/lookups/country_codes.csv). Raw sources in sources/, external/, and text/ remain verbatim.

Turkey → Türkiye (country code TUR unchanged) — reflects the 2022 UN-recognised official name.

License

Because the CAMEO manual is licensed CC BY-NC-SA 3.0, this repository (as a derivative work) is released under the same terms: non-commercial use, attribution to the original CAMEO authors, and share-alike for derivatives. See LICENSE.

Disclaimer

This is not an official release. Codes, labels, and descriptions are faithful reproductions where possible, but PDF extraction and regex fallbacks may have introduced minor errors. File an issue if you spot one.

Contents