This codebook defines the fields of the K4R-NGA dataset: a standardised, media-derived record of kidnap-for-ransom incidents in Nigeria, with geocoding, outcome coding, and GRID3 infrastructure and socioeconomic-vulnerability context. Each row is one incident. The dataset covers media-visible incidents only and is not a census of all kidnapping in Nigeria; figures should be read as the reported record. The dataset ships as CSV, Parquet and JSON with a Frictionless datapackage.json, and is queryable through a read-only public API.
Forty-four fields in six groups. Controlled vocabularies are listed under “Allowed values”; a bullet (●) marks the required primary key.
| Field | Type | Definition | Allowed values |
|---|---|---|---|
| incident_id ● | string | Stable unique identifier, K4R-NGA-{version}-{running number}. | — |
| dataset_version | string | Semantic version of the release this row belongs to. | — |
| last_updated | date | Date the release was generated. | — |
| Field | Type | Definition | Allowed values |
|---|---|---|---|
| kidnap_date | date | Date of the abduction (ISO 8601). Null when not stated. | — |
| date_precision | integer | 1 exact day; 2 day stated or inferred; 3 month/year only. | 1, 2, 3 |
| kidnap_time | string | Time of day if reported. Not populated in v1.0.0 (reserved for future releases). | — |
| kidnap_state | string | Nigerian state of the abduction. | Abia, Adamawa, Akwa Ibom, Anambra, Bauchi, Bayelsa, Benue, Borno, Cross River, Delta, Ebonyi, Edo, Ekiti, Enugu, FCT, Gombe, Imo, Jigawa, Kaduna, Kano, Katsina, Kebbi, Kogi, Kwara, Lagos, Nasarawa, Niger, Ogun, Ondo, Osun, Oyo, Plateau, Rivers, Sokoto, Taraba, Yobe, Zamfara |
| kidnap_lga | string | Local Government Area (from point-in-polygon on GRID3 boundaries). | — |
| kidnap_location | string | Named place of the abduction. | — |
| kidnap_location_type | string | Setting class of the abduction site. | Church, Farm, Filling Station, Highway, Home, Hotel, House, Market, Mosque, Railway, Road, School, Town |
| location_setting | string | Immediate setting (e.g. Car for road/highway). | — |
| latitude | number | WGS84 latitude of the geocoded location (town centroid). | — |
| longitude | number | WGS84 longitude of the geocoded location (town centroid). | — |
| geo_precision | integer | 2 town centroid; 3 state-level only. | 2, 3 |
| zone | string | North or South Nigeria. | North, South |
| Field | Type | Definition | Allowed values |
|---|---|---|---|
| perpetrator_type | string | Coarse actor category inferred from report language. | insurgent_group, bandit_group, criminal_gang, unspecified_armed_group |
| perpetrator_count | number | Number of perpetrators if stated. Not populated in v1.0.0 (reserved for future releases). | — |
| total_kidnapped | number | Number of victims abducted in the incident. | — |
| victim_gender_profile | string | Group-level gender inferred from report language. | Male, Female, Mixed, Unknown |
| victim_name | string | Withheld from the public release. Names of identifiable crime victims are personal data and are not published. The field is retained for schema stability and is always empty. See SECURITY.md. | — (always empty) |
| victim_ethnicity | string | Ethnicity if reported. Not populated in v1.0.0 (reserved for future releases). | — |
| victim_occupation | string | Occupation if reported. Not populated in v1.0.0 (reserved for future releases). | — |
| victim_residence_state | string | Home state of the victim if reported. Not populated in v1.0.0 (reserved for future releases). | — |
| Field | Type | Definition | Allowed values |
|---|---|---|---|
| ransom_demanded | string | Whether a ransom was demanded. | yes, no, unknown |
| ransom_demanded_amount | number | Amount demanded, in ransom_currency. | — |
| ransom_currency | string | Currency of ransom amounts (default NGN). | — |
| ransom_paid | string | Whether a ransom was paid. | yes, no, unknown |
| ransom_paid_amount | number | Amount paid, in ransom_currency. | — |
| release | string | Whether the victim(s) were released. | yes, no, unknown |
| release_status | string | Condition at resolution. | Alive, Deceased, Unknown |
| kidnap_duration_days | number | Days in captivity if derivable. Not populated in v1.0.0 (reserved for future releases). | — |
| total_released | number | Number released if stated. Not populated in v1.0.0 (reserved for future releases). | — |
| fatalities | number | Deaths attributed to the incident (conservative). | — |
| redemptor | string | Party that mobilised/paid the ransom, if reported. Not populated in v1.0.0 (reserved for future releases). | — |
| Field | Type | Definition | Allowed values |
|---|---|---|---|
| news_sources | string | Reporting outlet(s). | — |
| source_urls | string | Article URL(s). | — |
| publication_date | date | Date of the underlying report. | — |
| extraction_confidence | number | 0–1 confidence of the automated extraction. Not populated in v1.0.0 (reserved for future releases). | — |
| coding_method | string | How the row was coded. | automated_nlp, hand_coded |
| needs_review | boolean | Flagged for manual verification. | — |
| Field | Type | Definition | Allowed values |
|---|---|---|---|
| nearest_police_km | number | Distance to nearest police station (OpenStreetMap; indicative). | — |
| nearest_major_road_km | number | Distance to nearest trunk/primary road (GRID3). | — |
| lga_vulnerability_band | integer | GRID3 socioeconomic vulnerability band (1–5) of the incident LGA. | 1, 2, 3, 4, 5 |
| buildings_within_5km | number | Building count within 5 km (GRID3 settlement extents); built-up intensity. | — |
coding_method = automated_nlp), each carrying an extraction_confidence and a needs_review flag. Spatial context fields are joins to external layers (OpenStreetMap police; GRID3 roads, settlements and LGA vulnerability) and inherit those layers’ limitations; incident coordinates are town centroids (geo_precision = 2), so distances are indicative rather than metre-accurate.