Update: The and Foreign Aid Explorer websites are consolidating!

Learn more about the consolidation effort.

What's New?

Last updated on . Learn more

For Developers

Restful API for Data

REST (REpresentational State Transfer) API (Application Programming Interface) is a simple stateless architecture that generally runs over HTTP. REST involves reading a designated Web page that contains an XML or JSON file. The XML or JSON file describes and includes the desired content. To take advantage of the foreign assistance data available on the website, the API allows for the drilling and slicing of data by type, format, location, sector, agency, and fiscal year in multiple ways while serving as a source of up to date foreign assistance information through integration with software applications.

The API URL provides a mechanism to assign parameter values to request data with certain filters. The API has the ability to provide a choice for the type of data that is being requested, the format that the output should be in, and the filter that should be applied to it, along with the value for the filter as represented by the "filterValue" parameter of the URL.

The Restful API URLs at a glance:


Possible values for the parameters include:
formatxml | json
filterTypelocation | agency | sector
filterValueFree text value to search for (complete or partial)
  1. Hea -OR- Department of Health and Human Services
  2. Kaza -OR- Kazakhstan
  3. Mana -OR- Program Management
Activities fundingType
obligated | spent
Planned fundingType
requested | appropriated | actual
yearFour digit numerical value for the fiscal year. Ex: 2013

Response Format
Sample responses in both XML and JSON format:
Activities<?xml version="1.0" encoding="UTF-8"?>
<Activities xmlns:xsd="" xmlns:xsi="">
  <AgencyName>U.S. Agency for International Development</AgencyName>
  <BenefitingLocation>Korea, South</BenefitingLocation>
  <Sector>Pandemic Influenza and Other Emerging Threats (PIOET)</Sector>

  "AgencyName": "U.S. Agency for International Development",
  "Amount": "3852.82",
  "Category": "Health",
  "Year": "2015",
  "BenefitingLocation": "Korea, South",
  "Sector": "Pandemic Influenza and Other Emerging Threats (PIOET)"

Planned<?xml version="1.0" encoding="UTF-8"?>
<PlannedValues xmlns:xsd="" xmlns:xsi="">
  <AgencyName>U.S. Agency for International Development</AgencyName>
  <Category>Peace and Security</Category>

  "AgencyName": "U.S. Department of State and U.S. Agency for International Development",
  "FundingType": "Appropriation"
  "Amount": "16000000.0000",
  "Category": "Peace and Security",
  "Year": "2017",
  "BenefitingLocation": "Afghanistan",
  "Sector": "Counter-Terrorism"

Data Definitions
The following fields are associated with the data returned by the API.
Agency NameU.S. government agency.varchar4000
AmountThe dollar amount of the implementing mechanism signed (ie; total contract cost, total activity cost, total grant cost).decimal
8,2 category mapping.varchar4000
YearIn annual and multi-year funds, identifies the first fiscal year of availability under law that an appropriation account may incur new
Benefiting LocationTarget beneficiary location of the foreign assistance funds; country if possible, otherwise by lowest level of geographic granularity available.varchar4000
SectorThe sector, sub-sector, and/or element that the requested funds intend to foster based on the sector framework established by the sub-working groups as a common structure and standardized definitions against which to classify funds.varchar4000

Example Use
Some variations of the possible combinations for the API are as follows:
FormatFilter TypeFilter ValueFunding TypeURL
JSONSectorCivil SocietyObligated
JSONAgencyDepartment of DefenseSpent
JSONAgencyDepartment of DefenseAppropriated