# How to obtain `us_foreign_aid_complete.csv`

The largest input file (~3.75 GB) is not bundled in this replication package.
It is the full transaction-level bulk download from foreignassistance.gov
and is freely available.

## Download URL

    https://s3.amazonaws.com/files.explorer.devtechlab.com/us_foreign_aid_complete.csv

This is the same file linked from the "Data" tab on
https://foreignassistance.gov/data. It is maintained by DevTech Systems on
behalf of the U.S. State Department / USAID and updated quarterly.

## Place it here

After downloading, save it as:

    data/fa_gov_complete/us_foreign_aid_complete.csv

## Commands

From the package root:

    curl -L -o data/fa_gov_complete/us_foreign_aid_complete.csv \
        https://s3.amazonaws.com/files.explorer.devtechlab.com/us_foreign_aid_complete.csv

Expected size: about 3,749,974,097 bytes (~3.75 GB). Transfer time is
bandwidth-bound; typically 2-10 minutes.

## Schema (first row, as of the 2026-03-31 snapshot used in this package)

    "Country ID","Country Code","Country Name","Region ID","Region Name",
    "Income Group ID","Income Group Name","Income Group Acronym",
    "Managing Agency ID","Managing Agency Acronym","Managing Agency Name",
    "Managing Sub-agency or Bureau ID", ... ,
    "US Category ID","US Category Name","US Sector ID","US Sector Name",
    ... ,"Funding Agency ID","Funding Agency Name","Funding Agency Acronym",
    ... ,"Transaction Type ID","Transaction Type Name","Fiscal Year",
    "Transaction Date","Current Dollar Amount","Constant Dollar Amount",...

The fields this package uses:

- `Managing Agency Acronym` (scope filter, "USAID")
- `Fiscal Year` (2015-2025)
- `Fiscal Quarter` is not a field; we parse it from `Transaction Date`
  (format e.g. `30SEP2024`)
- `Transaction Type Name` (`Disbursements` or `Obligations`)
- `US Sector Name` (USG Sector Program Area)
- `Country Code` and `Country Name`
- `Current Dollar Amount`, `Constant Dollar Amount`

## Reproducibility note

foreignassistance.gov updates the file periodically, so numbers for the
most recent quarters may drift slightly after the fact. The snapshot used
to build the figures in this package is the one published on **2026-03-31**.
If you pull a newer copy, FY2024 should match to the dollar but FY2025
(which was still being reported at the time of publication) may differ.
