USAID Foreign Aid Data: The Federal Database Behind $40 Billion in Annual US Development Assistance

The United States spends roughly $40 billion per fiscal year on foreign assistance—development programs, global health initiatives, food security, democracy promotion, and humanitarian response across more than 100 countries. Every dollar of it is tracked in a public database. ForeignAssistance.gov is the primary transparency portal, built around the International Aid Transparency Initiative (IATI) standard; USASpending.gov carries USAID's awards within the broader federal spending picture. Understanding what these databases contain, how they relate to each other, and how to query them programmatically is essential for development economists, NGO analysts, foreign policy researchers, congressional oversight staff, and journalists covering the US foreign assistance system.

USAID: mission, legal authority, and scale

The United States Agency for International Development was created on November 3, 1961, when President John F. Kennedy signed Executive Order 10924 establishing the agency and directing it to consolidate previously fragmented US foreign assistance programs under a single civilian lead. The 1961 Foreign Assistance Act is the primary statutory authority; it has been amended dozens of times since and provides the legal basis for most USAID programming. USAID sits within the US foreign affairs apparatus alongside the Department of State, though it maintains its own administrator and operational independence on program implementation.

In fiscal year 2022 USAID managed approximately $40 billion in total budgetary resources, though the precise figure varies significantly by how interagency transfers and emergency supplementals are counted. USAID's core annual appropriation runs roughly $25 to $28 billion; the remainder comes from supplemental appropriations (particularly for Ukraine after February 2022), transfers from the President's Emergency Plan for AIDS Relief (PEPFAR), and funding from other agencies that USAID implements through interagency agreements. The agency operates in more than 100 countries through a network of country missions staffed by both direct-hire Foreign Service Officers and Foreign Service Nationals.

USAID organizes its programming around six mission areas, each managed through a dedicated bureau:

• Global Health: the largest mission area by budget, encompassing PEPFAR HIV/AIDS programs, malaria prevention and treatment (through the President's Malaria Initiative, PMI), maternal and child health, family planning, tuberculosis, pandemic preparedness, and health systems strengthening. The Bureau for Global Health manages the technical portfolio; USAID country missions implement through contracts and grants with implementing partners.
• Food Security and Agriculture: centered on Feed the Future, the US government's global food security initiative launched in 2010, which operates in 20 focus countries across Sub-Saharan Africa and Asia. Programs cover agricultural productivity, market access, nutrition, resilience, and policy reform. USAID also funds the Food for Peace program (Title II of the Agricultural Trade Development and Assistance Act), which provides emergency and development food assistance, primarily as in-kind commodity transfers managed through WFP and NGO implementing partners.
• Democracy, Human Rights, and Governance: supports elections, civil society, anti-corruption, rule of law, and legislative strengthening. Programs work through both international NGOs and domestic civil society organizations in recipient countries. The National Endowment for Democracy (NED), while not part of USAID, receives a significant portion of its funding through State Department and USAID appropriations.
• Economic Growth and Trade: covers private sector development, financial sector reform, trade facilitation, workforce development, and investment promotion. The Development Finance Corporation (DFC), a separate US government agency created by the BUILD Act of 2018 to replace OPIC, provides equity investments and loan guarantees for private investment in developing countries, often coordinating with USAID country programs.
• Humanitarian Assistance: USAID's Bureau for Humanitarian Assistance (BHA) responds to natural disasters and complex emergencies globally. BHA is one of the largest humanitarian donors in the world, funding WFP, UNHCR, UNICEF, ICRC, and a large network of NGO implementing partners for food, shelter, water, sanitation, health, and protection programs in crisis contexts.
• Climate and Environment: a growing portfolio covering climate adaptation, clean energy transition, biodiversity, and forest conservation. The USAID Climate Strategy 2022–2030 committed to integrating climate considerations across all mission areas.

ForeignAssistance.gov: the transparency portal

ForeignAssistance.gov launched in 2010 under the Obama administration as part of the US government's commitments under the International Aid Transparency Initiative (IATI). IATI is a multilateral standard established in 2008 at the Accra Agenda for Action, under which donor governments and implementing organizations agree to publish timely, comprehensive, and comparable data on their aid activities in a common XML format. ForeignAssistance.gov is the US government's primary IATI-compliant public disclosure platform.

The portal covers foreign assistance spending from multiple US government agencies, not just USAID. Major reporting agencies include: USAID, the Department of State (through its bilateral economic and security assistance accounts), the Millennium Challenge Corporation (MCC), the Peace Corps, the Department of Defense (security assistance programs), the Department of Agriculture (food assistance), the Centers for Disease Control (global health programs outside PEPFAR), and the Department of the Treasury (technical assistance). This whole-of-government scope makes ForeignAssistance.gov the most complete public record of US foreign assistance obligations, though coverage quality varies by agency.

The data structure on ForeignAssistance.gov organizes awards along four dimensions:

• Agency: the US government agency reporting the obligation. USAID accounts for roughly 55 to 60 percent of total reported obligations in most fiscal years; State Department accounts for another 25 to 30 percent.
• Country: the recipient country or region. The portal uses standard ISO country codes and OECD Development Assistance Committee (DAC) geographic classifications. Some programs are reported as “global” or “regional” when they operate across multiple countries through a single award mechanism.
• Sector: using OECD DAC sector codes, a standardized five-digit classification system covering 50+ sectors. Major groupings include social infrastructure (education, health, population, water/sanitation), economic infrastructure (transport, energy, communications), production sectors (agriculture, industry, trade), multi-sector/cross-cutting (environment, gender), commodity aid, and humanitarian. The five-digit codes provide precision: code 12220 is primary health care specifically, while 12110 is health policy and administrative management.
• Implementing partner: the organization receiving USAID funds to deliver programs. This may be a for-profit contractor, a US nonprofit, an international NGO, a university, a multilateral organization such as WFP or UNICEF, or a host-country government entity receiving direct government-to-government assistance.

The ForeignAssistance.gov API is publicly accessible at https://foreignassistance.gov/api/v1/. The primary endpoint is/resources.json, which returns award-level records filterable by fiscal year, agency name, recipient country, sector code, and implementing partner. Records include obligation amounts (the formal commitment of funds) and disbursement amounts (funds actually transferred to implementing partners). The gap between obligations and disbursements—which can be substantial for multi-year programs—is an important indicator of implementation pace.

USAID award types and procurement mechanisms

USAID uses five primary award mechanisms, each appropriate for different program types and policy objectives.

Contracts are used when USAID knows precisely what it wants and can write a detailed statement of work. Contracts are typically awarded to for-profit entities and are subject to the Federal Acquisition Regulation (FAR) and USAID's Automated Directives System (ADS) supplementary regulations. Contractors are paid for delivering specified outputs and bear performance risk—if they fail to deliver, USAID can terminate for cause and re-compete. Contracts are appropriate for technical assistance programs with measurable deliverables, infrastructure construction, and program support services.

Grants provide financial assistance to nonprofits, universities, and in limited cases for-profit entities when the primary purpose is to support the recipient's own programmatic work rather than to acquire a service for USAID. Grants are governed by 2 CFR Part 200 (the Uniform Guidance) rather than the FAR. The recipient organization contributes its own resources and expertise; USAID is not purchasing a service. Research grants, civil society support, and capacity development awards are common grant types.

Cooperative agreements occupy the middle ground. Like grants, they provide financial assistance to nonprofits and universities. Unlike grants, they involve “substantial involvement” by USAID in program implementation—USAID approves key personnel, reviews work plans, and may redirect program activities. Cooperative agreements are the dominant mechanism for large USAID field programs run by international NGOs and global health implementing partners.

Interagency agreements (IAAs) are used when USAID transfers funds to another US government agency to implement programs. Common IAA partners include the CDC (global health programs), Department of Agriculture (food security technical assistance), Peace Corps (volunteer programs), and Treasury (financial sector reform). IAAs appear in ForeignAssistance.gov data but may have lower implementing partner detail, since the receiving agency tracks sub-implementing arrangements in its own systems.

Development Credit Authority (DCA) guarantees, now managed through the DFC, are partial credit guarantees that encourage local financial institutions to lend to underserved borrowers in developing countries. DCA guarantees are technically contingent liabilities—they appear as obligations only if the guarantee is called—but are tracked in USAID's development finance portfolio. The face value of guaranteed loan portfolios is substantially larger than the actual USAID budget exposure.

PEPFAR: the largest global health initiative in history

The President's Emergency Plan for AIDS Relief was launched by President George W. Bush in his 2003 State of the Union address and authorized by the United States Leadership Against HIV/AIDS, Tuberculosis, and Malaria Act of 2003 (the PEPFAR legislation). It represents the single largest commitment by any nation to address a disease in history. As of FY2023, the United States has invested more than $110 billion in PEPFAR since its inception.

PEPFAR funding flows primarily through USAID and the Department of State's Office of the Global AIDS Coordinator (OGAC), which coordinates the US government's HIV/AIDS response across 12 implementing agencies including CDC, Department of Defense, Department of Labor, and Peace Corps. In FY2022 the total PEPFAR appropriation was approximately $6.9 billion. USAID implements the majority of PEPFAR programs in focus countries; CDC implements most laboratory and surveillance activities.

PEPFAR's programmatic results are exceptional by any measure: as of 2023, more than 20 million people were receiving antiretroviral therapy (ARVs) through PEPFAR-supported programs. PEPFAR has supported testing of more than 60 million people, enabled more than 3.5 million babies to be born HIV-free to HIV-positive mothers, and contributed to a more than 50 percent reduction in AIDS-related deaths in sub-Saharan Africa since the program's inception.

PEPFAR operates through Country Operational Plans (COPs), annual planning documents that each PEPFAR-eligible country develops in partnership with OGAC, USAID, and CDC. COPs specify targets for testing, treatment, prevention, and care; allocate funding by program area; and identify implementing partners for each program. Approved COP documents are public and available at pepfar.gov; they contain granular data on planned expenditures by program area that supplements the award-level data available through ForeignAssistance.gov.

PEPFAR expenditure data is available through pepfar.gov/funding and is integrated into ForeignAssistance.gov. The PEPFAR Expenditure Analysis (EA) process collects actual expenditure data from implementing partners annually, distinguishing between above-site (systems strengthening) and site-level (direct service delivery) spending. The EA data is aggregated to program area and country level in public reporting; partner-level expenditure detail is generally not public. The PEPFAR Scientific Advisory Board publishes periodic reviews of the scientific and programmatic evidence base; these are available at pepfar.gov alongside the dataset.

The DATA Act linkage: USAID on USASpending.gov

The Digital Accountability and Transparency Act of 2014 (DATA Act) requires all federal agencies, including USAID, to report their financial assistance awards to USASpending.gov. USAID appears on USASpending as a civilian agency under the Department of State and Foreign Operations (SFOPS) appropriations umbrella. On USASpending, USAID awards are searchable alongside domestic agencies; the agency DUNS/UEI and toptier code identify USAID within the broader federal spending architecture.

The practical difference between ForeignAssistance.gov and USASpending.gov for USAID research is one of framing and depth. ForeignAssistance.gov is organized around the foreign assistance logic—country, sector, implementing partner, IATI activity identifiers—and is the authoritative source for sector-coded, country-attributed, IATI-compliant data. USASpending presents USAID awards within the domestic federal procurement and financial assistance framework—Treasury Account Symbols, appropriation linkages, NAICS codes, and the full DATA Act financial chain from appropriation through outlay.

For contract awards (primarily USAID's for-profit technical assistance contracts), USAID data also flows into FPDS-NG, the Federal Procurement Data System, exactly like any domestic federal agency. FPDS records show PSC codes, competition type, contract type (FFP vs. cost-plus), and period of performance for USAID contracts. Researchers tracking contractor performance across USAID and domestic agencies (for example, examining whether a contractor winning USAID contracts also holds domestic USDA or HHS contracts) can use USASpending/FPDS for this cross-agency analysis more readily than ForeignAssistance.gov, which only covers foreign assistance obligations.

USAID also publishes IATI XML directly to the IATI Registry at iatiregistry.org. The IATI format encodes each aid activity with an IATI activity identifier (a unique string combining the reporting organization prefix and an internal activity reference), hierarchical activity data (parent programs and child awards), transaction-level data (commitments, disbursements, and expenditures with dates and value amounts), sector codes using the five-digit DAC scheme, recipient country codes, document links, and contact information. Organizations such as D-Portal (d-portal.org) aggregate IATI data from all publishing organizations globally and provide a unified search interface across donors.

Implementing partner concentration: Beltway contractors and INGOs

USAID's implementing partner landscape is characterized by significant concentration. In most fiscal years, the top 10 to 15 implementing partners collectively receive the majority of USAID contract and grant funding. This concentration reflects both the scale economies required to manage large multi-country programs and USAID's preference for established partners with proven financial management systems, audit compliance capacity, and country presence.

Among for-profit contractors—sometimes called “Beltway Bandits” for their concentration in the Washington, DC metropolitan area—Chemonics International consistently ranks as the largest USAID implementing partner, receiving approximately $1 to $2 billion annually. Chemonics runs field programs in economic growth, agriculture, democracy and governance, health systems, and financial sector development across sub-Saharan Africa, Asia, and the Middle East. DAI Global (Development Alternatives Inc.) is the second-largest for-profit partner, similarly active in democracy, governance, and economic growth programming. Management Systems International (MSI), acquired by Tetra Tech, specializes in democracy and governance evaluations and program management. AECOM International Development runs large infrastructure-adjacent programs. RTI International, a nonprofit research organization, is a major USAID contractor for education, health, and governance research programs.

Among international NGOs, the largest USAID recipients include Catholic Relief Services (CRS), Save the Children, CARE International, World Vision, and the International Rescue Committee (IRC). These organizations implement across humanitarian, food security, health, and livelihoods sectors. Population Services International (PSI) is a major USAID partner in global health, particularly family planning and malaria. Jhpiego (an affiliate of Johns Hopkins University) implements maternal and child health programs in dozens of countries.

Universities represent a distinct category of USAID implementing partners. Johns Hopkins University (through its Bloomberg School of Public Health), Harvard, Georgetown, the University of North Carolina, and Tulane University receive significant USAID funding for global health research, program evaluation, and technical assistance. The MEASURE Evaluation program (managed by University of North Carolina) is one of the longest-running USAID-funded research and evaluation mechanisms.

A persistent critique of the USAID implementing partner system is that the largest awards flow disproportionately to US-headquartered organizations rather than to local and national organizations in recipient countries. The USAID Local Works initiative and USAID's locally-led development policy (announced 2022) commit to increasing the percentage of awards going directly to local organizations—a target of 25 percent of funding to local partners by 2025—though progress against these targets is tracked through ForeignAssistance.gov data and is actively monitored by NGO watchdog organizations including Devex and the Interaction NGO coalition.

Geographic concentration: top recipient countries

USAID's geographic distribution reflects both humanitarian need and US strategic interests. In fiscal year 2022, the top recipient countries by obligation amount included:

• Afghanistan: despite the August 2021 US military withdrawal, Afghanistan remained among the top USAID recipients in FY2022 at approximately $1.2 to $1.5 billion, primarily for humanitarian assistance through UN agencies and NGOs. USAID paused all direct government-to-government assistance to the Taliban government but continued humanitarian programming through multilateral and NGO channels.
• Ethiopia: major USAID recipient for humanitarian assistance related to the Tigray conflict (2020–2022) and ongoing food security crises, receiving upward of $1 billion in most recent fiscal years.
• Ukraine: USAID Ukraine funding surged dramatically following Russia's full-scale invasion in February 2022, from under $300 million in FY2021 to several billion dollars in FY2022–2023 through emergency supplemental appropriations. Ukraine became one of the top-3 USAID recipients by FY2023.
• Democratic Republic of Congo: a chronic humanitarian crisis and major PEPFAR country, receiving over $700 million annually across health, humanitarian, and food security sectors.
• Nigeria: Africa's most populous country and a major PEPFAR focus country; USAID Nigeria programming runs approximately $700 million to $1 billion annually across health (PEPFAR), food security (Feed the Future), and democracy/governance.
• South Africa: a major PEPFAR recipient despite being an upper-middle-income country, because South Africa has the world's largest HIV-positive population (estimated 7.7 million people living with HIV). PEPFAR South Africa is one of the largest single-country PEPFAR programs.
• Jordan: a strategic partner in the Near East, receiving significant Economic Support Funds (ESF) alongside health and democracy programming; Jordan consistently ranks among the top-10 USAID recipients in part due to its role hosting Syrian and Iraqi refugees.
• Mozambique, Tanzania, and Kenya: all major PEPFAR and Feed the Future focus countries in sub-Saharan Africa with multi-hundred-million-dollar annual USAID portfolios spanning health, agriculture, and economic growth.

By region, Sub-Saharan Africa receives approximately 35 percent of USAID's total obligations, driven by the concentration of PEPFAR programming and food security investment. The Near East (including Egypt, Jordan, the West Bank/Gaza, Iraq, and Yemen) receives roughly 20 percent. Asia (including Afghanistan, Bangladesh, India, and Indonesia) receives approximately 15 percent. Latin America and the Caribbean receive around 10 percent, with Colombia and Haiti historically among the largest recipients. Europe, a minor USAID geographic area in normal years, grew substantially as a share with Ukraine spending.

OpenAid, IATI, and international transparency infrastructure

The International Aid Transparency Initiative (IATI) is a voluntary multilateral standard with over 1,500 publishing organizations including 40+ bilateral donor governments, the major multilateral development banks, UN agencies, and thousands of NGO implementing organizations. IATI data is stored in XML files published to the IATI Registry (iatiregistry.org), which catalogs all IATI-compliant publishers and links to their data files.

The IATI XML format encodes aid activities at multiple levels of granularity. A top-level IATI activity represents a program or project with its own title, description, start and end dates, total budget, and sector and country allocations. Transactions within an activity record individual financial events: commitments (formal funding decisions), disbursements (transfers to implementing organizations), expenditures (actual spending by the implementer), and incoming funds (from other donors for co-funded activities). The IATI standard's transaction-level detail is more granular than ForeignAssistance.gov's aggregated obligation figures and enables analysis of implementation timelines and cash flow.

D-Portal (d-portal.org), maintained by the IATI technical team, provides a user-friendly interface for searching IATI data across all publishers. It allows filtering by donor country, recipient country, sector, organization type, and year. Development Initiatives' Panorama platform (panorama.solutions) offers visualization of IATI data. AidData at William & Mary (aiddata.org) conducts systematic research using IATI and other aid databases, producing the most comprehensive academic datasets on Chinese development finance, World Bank project outcomes, and donor aid effectiveness.

The OECD's Creditor Reporting System (CRS) is a separate database that collects Official Development Assistance (ODA) statistics from all DAC member countries using a standardized reporting format. CRS data is the authoritative source for cross-donor comparisons of aid volumes by sector and recipient country; it aggregates to country-level totals rather than individual award records. The OECD publishes CRS data through its Stats portal (stats.oecd.org) and through the QWIDS (Query Wizard for International Development Statistics) interface. CRS covers all DAC donors—not just the US—making it indispensable for international comparative analysis.

DOGE, the 2025 foreign aid freeze, and data as accountability

On January 20, 2025, the Trump administration issued a Stop-Work order pausing nearly all US foreign assistance pending a 90-day review. The pause affected approximately $40 billion in programmed foreign assistance across USAID and the State Department. Implementing partners received stop-work notices requiring them to halt program activities within 48 hours; thousands of programs across 100+ countries were affected. The Department of Government Efficiency (DOGE) played an active role in the review and subsequent terminations of USAID contracts and grants.

The 2025 foreign aid freeze generated a significant public accountability challenge that demonstrated both the value and the limitations of foreign aid transparency databases. ForeignAssistance.gov data allowed researchers, journalists, and congressional oversight staff to identify which programs were at risk, which implementing partners held the largest active awards, and what country portfolios were most exposed. AidData at William & Mary and Devex published tracking analyses of terminated and suspended awards using award data from ForeignAssistance.gov and USASpending.

The limitations were equally apparent. ForeignAssistance.gov data reflects obligations at the time of award; stop-work orders and contract terminations generate de-obligation actions that may not appear in the transparency databases for weeks or months after the fact. Implementing partners had direct knowledge of their own program status that was not yet reflected in any public database. Congressional notifications under the Foreign Assistance Act's reprogramming provisions, which require advance notice to the Appropriations Committees before funds can be redirected, were a legal constraint that the administration's rapid freeze potentially violated—but resolving that question required comparing appropriation-level data in USASpending against programmatic data in ForeignAssistance.gov, a non-trivial analytical task.

The debate over USAID's continued existence—proposals to fold it into the State Department or eliminate it entirely—highlighted the agency's data infrastructure as both an accountability asset and an organizational complexity. The IATI publication obligations, ForeignAssistance.gov maintenance, and DATA Act reporting requirements collectively require significant institutional capacity; any reorganization creates risks for data continuity and transparency.

Python example: ForeignAssistance.gov API analysis for FY2023 USAID awards

The following script queries the ForeignAssistance.gov API for all USAID awards in FY2023. It performs four analyses: identifying the top-10 recipient countries by obligation amount, computing sector distribution (health, food security, democracy/governance, and others) separately for Sub-Saharan Africa and the Near East, ranking the top-10 implementing partners across all countries, and computing a year-over-year trend for the top recipient countries from FY2020 through FY2023 to capture the Ukraine funding surge.

import requests
import pandas as pd
from collections import defaultdict
from typing import Any

# ---------------------------------------------------------------------------
# ForeignAssistance.gov API: USAID FY2023 Awards by Country, Sector, Partner
# Base URL: https://foreignassistance.gov/api/v1/
# No API key required. Paginate with limit/offset. Data covers US government-
# wide foreign assistance: USAID, State, MCC, Peace Corps, DOD, PEPFAR, etc.
# Filter to USAID using agency_id or agency_name fields.
# ---------------------------------------------------------------------------

BASE = "https://foreignassistance.gov/api/v1"
FISCAL_YEAR = 2023
PAGE_LIMIT = 500


def fetch_usaid_awards(fiscal_year: int = FISCAL_YEAR) -> list[dict[str, Any]]:
    """
    Pull all USAID award records for a given fiscal year from ForeignAssistance.gov.
    Paginates automatically. Each record contains recipient country, sector,
    implementing partner, obligation and disbursement amounts.
    """
    awards: list[dict[str, Any]] = []
    offset = 0

    while True:
        url = (
            f"{BASE}/resources.json"
            f"?limit={PAGE_LIMIT}"
            f"&offset={offset}"
            f"&fiscal_year={fiscal_year}"
            f"&agency_name=U.S.+Agency+for+International+Development"
        )
        resp = requests.get(url, timeout=60)
        resp.raise_for_status()
        data = resp.json()

        # ForeignAssistance.gov returns {"data": [...], "total": N}
        batch = data.get("data", [])
        if not batch:
            break
        awards.extend(batch)

        total = data.get("total", 0)
        offset += PAGE_LIMIT
        if offset >= total:
            break

    return awards


def top_countries_by_obligation(
    awards: list[dict[str, Any]], top_n: int = 10
) -> pd.DataFrame:
    """
    Sum obligation amounts by recipient country and return the top-N.
    Obligation amount field: 'current_amount' (obligation in USD).
    Country field: 'recipient_country_name'.
    """
    country_totals: dict[str, float] = defaultdict(float)

    for award in awards:
        country = award.get("recipient_country_name") or "Unknown"
        amount = float(award.get("current_amount") or 0)
        country_totals[country] += amount

    rows = [
        {"country": c, "obligation_usd": v}
        for c, v in sorted(country_totals.items(), key=lambda x: x[1], reverse=True)
    ]
    df = pd.DataFrame(rows[:top_n])
    df.index = range(1, len(df) + 1)
    return df


def sector_distribution_by_region(
    awards: list[dict[str, Any]],
) -> pd.DataFrame:
    """
    Compare sector breakdown (health vs. democracy/governance vs. food security)
    between Sub-Saharan Africa and the Near East (MENA) regions.
    Uses 'dac_sector_name' for broad sector grouping and
    'region_name' for region classification.
    """
    # Simplified sector groupings from DAC sector names
    SECTOR_MAP = {
        "health": "Health",
        "population": "Health",
        "reproductive": "Health",
        "hiv": "Health",
        "malaria": "Health",
        "nutrition": "Food Security",
        "food": "Food Security",
        "agriculture": "Food Security",
        "rural": "Food Security",
        "democracy": "Democracy/Governance",
        "governance": "Democracy/Governance",
        "civil society": "Democracy/Governance",
        "rule of law": "Democracy/Governance",
        "economic": "Economic Growth",
        "trade": "Economic Growth",
        "financial": "Economic Growth",
        "infrastructure": "Infrastructure",
        "energy": "Infrastructure",
        "water": "Infrastructure",
        "transport": "Infrastructure",
        "humanitarian": "Humanitarian",
        "emergency": "Humanitarian",
        "education": "Education",
        "environment": "Environment/Climate",
        "climate": "Environment/Climate",
    }

    FOCUS_REGIONS = {"Sub-Saharan Africa", "Near East"}
    FOCUS_SECTORS = [
        "Health",
        "Food Security",
        "Democracy/Governance",
        "Economic Growth",
        "Humanitarian",
        "Infrastructure",
        "Education",
        "Environment/Climate",
        "Other",
    ]

    def map_sector(raw: str) -> str:
        raw_lower = (raw or "").lower()
        for keyword, label in SECTOR_MAP.items():
            if keyword in raw_lower:
                return label
        return "Other"

    # region -> sector -> obligation sum
    breakdown: dict[str, dict[str, float]] = {r: defaultdict(float) for r in FOCUS_REGIONS}

    for award in awards:
        region = award.get("region_name") or ""
        if region not in FOCUS_REGIONS:
            continue
        sector_raw = award.get("dac_sector_name") or ""
        sector = map_sector(sector_raw)
        amount = float(award.get("current_amount") or 0)
        breakdown[region][sector] += amount

    rows = []
    for region in sorted(FOCUS_REGIONS):
        total = sum(breakdown[region].values()) or 1
        for sector in FOCUS_SECTORS:
            amt = breakdown[region].get(sector, 0)
            rows.append(
                {
                    "region": region,
                    "sector": sector,
                    "obligation_usd": amt,
                    "pct_of_region": 100 * amt / total,
                }
            )
    return pd.DataFrame(rows)


def top_implementing_partners(
    awards: list[dict[str, Any]], top_n: int = 10
) -> pd.DataFrame:
    """
    Aggregate obligations by implementing partner name across all countries
    and return the top-N. Field: 'implementing_partner_name'.
    """
    partner_totals: dict[str, float] = defaultdict(float)

    for award in awards:
        partner = award.get("implementing_partner_name") or "Not Reported"
        amount = float(award.get("current_amount") or 0)
        partner_totals[partner] += amount

    rows = [
        {"implementing_partner": p, "obligation_usd": v}
        for p, v in sorted(partner_totals.items(), key=lambda x: x[1], reverse=True)
    ]
    df = pd.DataFrame(rows[:top_n])
    df.index = range(1, len(df) + 1)
    return df


def yoy_trend_top_countries(
    top_countries: list[str],
    fiscal_years: list[int],
) -> pd.DataFrame:
    """
    Fetch obligation totals for specified countries across multiple fiscal years
    to compute year-over-year trends. Makes one API call per fiscal year.
    """
    rows = []
    for fy in fiscal_years:
        awards = fetch_usaid_awards(fiscal_year=fy)
        country_totals: dict[str, float] = defaultdict(float)
        for award in awards:
            country = award.get("recipient_country_name") or "Unknown"
            amount = float(award.get("current_amount") or 0)
            country_totals[country] += amount
        for country in top_countries:
            rows.append(
                {
                    "fiscal_year": fy,
                    "country": country,
                    "obligation_usd": country_totals.get(country, 0),
                }
            )
    return pd.DataFrame(rows).pivot(
        index="fiscal_year", columns="country", values="obligation_usd"
    ).fillna(0)


def print_top_countries(df: pd.DataFrame, fiscal_year: int) -> None:
    total = df["obligation_usd"].sum()
    print(f"USAID FY{fiscal_year} Top-{len(df)} Recipient Countries by Obligation")
    print(f"Total shown: ${total / 1e9:.2f}B")
    print()
    print(f"  {'Rank':>4}  {'Country':<40}  {'Obligation ($M)':>16}")
    print("  " + "-" * 68)
    for rank, row in df.iterrows():
        print(
            f"  {rank:>4}  {row['country'][:40]:<40}"
            f"  ${row['obligation_usd'] / 1e6:>14.1f}"
        )
    print()


def print_sector_table(df: pd.DataFrame) -> None:
    print("USAID FY2023 Sector Distribution: Sub-Saharan Africa vs. Near East")
    print()
    print(
        f"  {'Sector':<26}  {'SSA ($M)':>10}  {'SSA %':>7}"
        f"  {'NE ($M)':>10}  {'NE %':>7}"
    )
    print("  " + "-" * 68)
    ssa = df[df["region"] == "Sub-Saharan Africa"].set_index("sector")
    ne = df[df["region"] == "Near East"].set_index("sector")
    for sector in [
        "Health", "Food Security", "Democracy/Governance", "Economic Growth",
        "Humanitarian", "Infrastructure", "Education", "Environment/Climate", "Other"
    ]:
        ssa_amt = ssa.loc[sector, "obligation_usd"] if sector in ssa.index else 0
        ssa_pct = ssa.loc[sector, "pct_of_region"] if sector in ssa.index else 0
        ne_amt = ne.loc[sector, "obligation_usd"] if sector in ne.index else 0
        ne_pct = ne.loc[sector, "pct_of_region"] if sector in ne.index else 0
        print(
            f"  {sector:<26}  ${ssa_amt / 1e6:>8.1f}  {ssa_pct:>6.1f}%"
            f"  ${ne_amt / 1e6:>8.1f}  {ne_pct:>6.1f}%"
        )
    print()


def print_top_partners(df: pd.DataFrame, fiscal_year: int) -> None:
    total = df["obligation_usd"].sum()
    print(f"USAID FY{fiscal_year} Top-{len(df)} Implementing Partners by Obligation")
    print(f"Total shown: ${total / 1e9:.2f}B")
    print()
    print(f"  {'Rank':>4}  {'Implementing Partner':<48}  {'Obligation ($M)':>16}")
    print("  " + "-" * 76)
    for rank, row in df.iterrows():
        print(
            f"  {rank:>4}  {row['implementing_partner'][:48]:<48}"
            f"  ${row['obligation_usd'] / 1e6:>14.1f}"
        )
    print()


def main() -> None:
    print("Fetching USAID FY2023 awards from ForeignAssistance.gov...")
    awards = fetch_usaid_awards(fiscal_year=FISCAL_YEAR)
    print(f"Retrieved {len(awards):,} award records.")
    print()

    # --- Part 1: Top-10 recipient countries ---
    print("--- Part 1: Top-10 Recipient Countries ---")
    country_df = top_countries_by_obligation(awards, top_n=10)
    print_top_countries(country_df, FISCAL_YEAR)

    # --- Part 2: Sector breakdown by region ---
    print("--- Part 2: Sector Distribution by Region ---")
    sector_df = sector_distribution_by_region(awards)
    print_sector_table(sector_df)

    # --- Part 3: Top-10 implementing partners ---
    print("--- Part 3: Top-10 Implementing Partners ---")
    partner_df = top_implementing_partners(awards, top_n=10)
    print_top_partners(partner_df, FISCAL_YEAR)

    # --- Part 4: Year-over-year trend (Ukraine surge visible here) ---
    print("--- Part 4: Year-over-Year Trend FY2020-FY2023 for Selected Countries ---")
    top_country_names = list(country_df["country"].head(5))
    trend_df = yoy_trend_top_countries(
        top_countries=top_country_names,
        fiscal_years=[2020, 2021, 2022, 2023],
    )
    print(trend_df.to_string(float_format=lambda x: f"${x / 1e6:.1f}M"))
    print()


if __name__ == "__main__":
    main()

Typical FY2023 output for the top-10 recipient countries will show Ukraine at or near the top due to emergency supplemental appropriations, followed by Ethiopia, Nigeria, the Democratic Republic of Congo, and Afghanistan. South Africa will appear in the top 10 driven by PEPFAR funding. The year-over-year trend analysis will show Ukraine moving from a relatively small recipient in FY2020–2021 to one of the largest by FY2023, while Afghanistan shows a different pattern—large in FY2020–2021 due to development programming, then shifting primarily to humanitarian channels post-withdrawal.

The sector distribution analysis will typically show health (primarily PEPFAR) dominating the Sub-Saharan Africa portfolio at 50 to 60 percent of obligations, with food security second at 15 to 20 percent reflecting Feed the Future concentration. The Near East portfolio will show a different balance, with humanitarian assistance higher (reflecting Yemen, Syria, and Gaza programming) and democracy/governance more prominent reflecting Jordan and West Bank programming. For implementing partners, Chemonics will typically appear first among for-profit contractors; among NGOs, Catholic Relief Services, Save the Children, and World Vision compete for the top positions depending on fiscal year and emergency funding flows.

Two data quality caveats apply. First, ForeignAssistance.gov reporting lags behind actual award actions; awards made late in the fiscal year may not appear until several months into the following year. Second, the implementing partner name field is not normalized—the same organization may appear under multiple name variants (e.g., “Chemonics International Inc.” vs. “Chemonics International”), requiring string normalization before aggregating partner totals.