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 site, 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:
Activities
http://fagov-api-prod.azurewebsites.net/api/public/activities?format={format}&fundingType={fundingType}&filtertype={filterType}&filtervalue={value}&year={YYYY}

Planned
http://fagov-api-prod.azurewebsites.net/api/public/planned?format={format}&filterType={filterType}&filtervalue={value}&year={YYYY}

Possible values for the parameters include:
NameValue
format xml | json
filterType location | agency | sector
filterValue Free text value to search for (complete or partial)
Examples:
  1. Hea -OR- Department of Health and Human Services
  2. Kaza -OR- Kazakhstan
  3. Mana -OR- Program Management
fundingType
*activities only*		 obligated | spent
year Four digit numerical value for the year. Ex: 2013

Response Format
Sample responses in both XML and JSON format:
TypeExample
XML<?xml version="1.0" encoding="UTF-8"?>
<Activities xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
 <Activity>
  <AgencyName>U.S. Agency for International Development</AgencyName>
  <Amount>3852.82</Amount>
  <Category>Health</Category>
  <Year>2015</Year>
  <BenefitingLocation>Korea, South</BenefitingLocation>
  <Sector>Pandemic Influenza and Other Emerging Threats (PIOET)</Sector>
 </Activity>
</Activities>

<?xml version="1.0" encoding="UTF-8"?>
<PlannedValues xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
 <PlannedValue>
  <AgencyName>U.S. Agency for International Development</AgencyName>
  <Amount>3852.82</Amount>
  <Category>Health</Category>
  <Year>2015</Year>
  <BenefitingLocation>Korea, South</BenefitingLocation>
  <Sector>Pandemic Influenza and Other Emerging Threats (PIOET)</Sector>
 </PlannedValue>
</PlannedValues>

JSON
[
 {
  "AgencyName": "MCC",
  "Amount": "15221",
  "Category": "General",
  "FiscalYear": "2013",
  "BenefitingLocation": "Ghana",
  "Sector": "Agriculture"
 }
]

Data Definitions
The following fields are associated with the data returned by the API.
NameDescriptionTypeSize
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
(varchar)		8,2
CategoryForeignAssistance.gov 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 obligations.int
(varchar)		4
Benefitting 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:
Format Filter TypeFilter ValueFunding Type
(activities only)		 URL
Activities
XMLLocationPakistanObligated http://fagov-api-prod.azurewebsites.net/api/public/activities?format=xml&fundingType=obligated&filterType=location&
filterValue=pakistan&year=2013
XMLLocationPakistanSpent http://fagov-api-prod.azurewebsites.net/api/public/activities?format=xml&fundingType=spent&filterType=location&
filterValue=pakistan&year=2013
JSONSectorCivil SocietyObligated http://fagov-api-prod.azurewebsites.net/api/public/activities?format=json&fundingType=obligated&filterType=sector&
filterValue=civil&20society&year=2013
JSONAgencyDepartment of DefenseSpent http://fagov-api-prod.azurewebsites.net/api/public/activities?format=json&fundingType=spent&filterType=agency&
filterValue=Department%20Of%20Defense&year=2013
Planned
XMLLocationPakistan http://fagov-api-prod.azurewebsites.net/api/public/planned?format=xml&filterType=location&
filterValue=pakistan&year=2013
JSONAgencyDepartment of Defense http://fagov-api-prod.azurewebsites.net/api/public/planned?format=json&filterType=agency&
filterValue=Department%20Of%20Defense&year=2013