codebook.md

Codebook: geo_CBP_apprehensions.csv

Final geocoded output of the CBP apprehensions geocoding pipeline. Each row corresponds to one apprehension record.

Input variables

These variables originate from the raw CBP apprehensions dataset and are passed through to the final output.

Variable	Type	Description
rID	string	Unique record identifier. Format: FY{year}_{sequential_number} (e.g., "FY2010_1"). Present in the full dataset only (not in test extracts).
FY	string	US federal fiscal year of the apprehension (e.g., "FY2018"). The fiscal year runs from October 1 to September 30.
year	integer	Calendar year of the apprehension.
month	string	Calendar month of the apprehension (e.g., "January").
appr_date	string	Apprehension date in ISO 8601 format (e.g., "2018-01-20T00:00:00Z").
age	integer	Age of the apprehended individual at the time of apprehension.
citizenship	string	Country of citizenship (e.g., "GUATEMALA", "MEXICO").
city_birth	string	Self-reported city of birth. Cleaned during processing: "CD"/"CD." prefix expanded to "Ciudad"; "DEP"/"DEP." departamento suffix removed; "DISTRITO FEDERAL (DE MEXICO)" relabeled to "MEXICO CITY"; "UNKNOWN" values set to missing. May be missing (NA).
state_birth	string	Self-reported state/department of birth. Cleaned during processing: parenthetical country names removed; "EL" prefix removed (except for EL PARAISO and EL PROGRESO); "DISTRITO FEDERAL" entries relabeled. May be missing (NA).
country_birth	string	Country of birth (e.g., "GUATEMALA", "HONDURAS", "MEXICO", "EL SALVADOR").
iso2c_birth	string	ISO 3166-1 alpha-2 country code for the country of birth (e.g., "GT", "HN", "MX", "SV"). Used as the country_codes parameter in Nominatim queries.
demographic	string	Demographic category of the apprehended individual. Values: "Single Adults", "FMUA" (Family Unit Members/Adults), "UC" (Unaccompanied Children). "UC" is reported for all fiscal years; "Single Adults" and "FMUA" are only distinguished from FY2012 onward. Non-UC records in FY2010–FY2011 are NA.
N_subject_event	integer	Number of subjects in the apprehension event. May be missing (NA).
N_subject_fmu	integer	Number of subjects in the family unit. Only populated for FMUA records (range: 1–11). NA otherwise.

Geocoding query variables

Structured query strings constructed during processing and used to query the OpenStreetMap Nominatim API.

Variable	Type	Description
osmLoc	string (JSON)	Primary geocoding query at the city level. Format: {"city":"<city_birth>","state":"<state_birth>","country":"<country_birth>"}. Set to NA if city_birth or state_birth is missing (or if state_birth equals "OTHER - FOR COUNTRIES OTH").
osmAdmin	string (JSON)	Geocoding query at the admin-1 (state/department) level. Format: {"state":"<state_birth>","country":"<country_birth>"}. Set to NA if state_birth is missing or equals "OTHER - FOR COUNTRIES OTH".
osmLoc_noAdmin	string (JSON)	Alternative city-level query used only when city_birth is present but state_birth is missing. Format: {"city":"<city_birth>","country":"<country_birth>"}. Set to NA otherwise.

Geocoding result variables

Coordinates

Variable	Type	Description
lat	float	Latitude of the geocoded location (WGS 84). NA if geocoding was unsuccessful. When multiple candidate locations are returned, one is selected randomly with probability proportional to the Nominatim importance score.
lon	float	Longitude of the geocoded location (WGS 84). NA if geocoding was unsuccessful. Selected jointly with lat.

Geocoding level

Variable	Type	Description
geo_lvl	string	Indicates the level at which the record was geocoded. Possible values:
		- "city": Geocoded at the city/village/town/hamlet level with state information available.
		- "city_noState": Geocoded at the city level without state/admin-1 information (query used osmLoc_noAdmin).
		- "state": Geocoded at the admin-1 (state/department) level only; city-level geocoding failed.
		- "country": Only country of birth was available, or the record could not be geocoded at any sub-national level. Coordinates are NA.
		- NA: Geocoder encountered an unrecoverable error (geocoder_failure = 1).

Geocoding status flags

Binary indicator variables (1/0/NA) tracking the outcome at each stage of the geocoding cascade.

Variable	Type	Description
noAdmin	binary (0/1)	1 if geocoded at the city level without state/admin-1 information (i.e., via osmLoc_noAdmin). 0 if geocoded with state info or at admin-1 level. NA if not geocoded.
admin_only	binary (0/1)	1 if geocoded at the admin-1 (state) level only, after city-level geocoding failed. 0 otherwise. NA if not geocoded.
country_only	binary (0/1)	1 if only the country of birth was provided (both city_birth and state_birth missing or insufficient). No geocoding was attempted. 0 otherwise.
notLocated	binary (1/NA)	1 if the record had sub-national location information but could not be geocoded at any level (city, county, street, or state). NA otherwise.
notLocatedCity	binary (1/NA)	1 if city-level geocoding failed (when state/admin-1 was available). The algorithm then attempted admin-1 level geocoding. NA otherwise.
notLocatedAdmin	binary (1/NA)	1 if admin-1 (state) level geocoding also failed after city-level failure. NA otherwise.
notLocatedCityOnly	binary (1/NA)	1 if city-level geocoding failed when no admin-1/state information was available (query used osmLoc_noAdmin). NA otherwise.
geocoder_failure	binary (0/1)	1 if the Nominatim geocoder raised an unrecoverable exception (after 3 retry attempts) for this record. 0 otherwise.

Query reformulation flags

Binary indicator variables (1/0/NA) tracking whether alternative query strategies were used to achieve geocoding. These are NA when the record was not geocoded (lat is NA).

Variable	Type	Description
county_Q	binary (0/1)	1 if the record was geocoded using a county-reformulated query (the city field in the Nominatim query was replaced with county), or if multiple city-level results mapped to the same county. 0 otherwise. NA if not geocoded.
street_Q	binary (0/1)	1 if the record was geocoded using a street/neighborhood-level query (filtering for borough, quarter, suburb, or neighbourhood address types in OSM). 0 otherwise. NA if not geocoded.
lang_Q	binary (0/1)	1 if the record was geocoded after applying phonetic letter inversion to the city name (e.g., Z/S, C/S, J/G, Y/LL, V/B, I/Y). 0 otherwise. NA if not geocoded.
multi_R	integer	Number of candidate locations returned by the Nominatim API for the matched query. When greater than 1, the final coordinates were selected randomly with probability proportional to the normalized Nominatim importance score. NA if not geocoded.