Home  /  Developers Page

Fork me on GitHub

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, country, 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 “option” parameter of the URL.

The Restful API URL at a glance:
http://foreignassistance.gov/dashboardservice/dashboardserviceapi.svc/DashboardServiceAPI/<data format>/GetData?type=<fund type>&filter=<filter by>&option=<filter value>&year=<year>

Possible values for the parameters include:
  • Data Format
    1. XML
    2. JSON
  • Data Type
    1. Planned
    2. Obligated
    3. Spent
    4. Transaction
  • Filter By
    1. Country
    2. Agency
    3. Sector
  • Year
    1. Four digit numerical value for the year. Ex: 2013
Base URL
The URL of the website that is constant and shared with the rest of the web services including the website and file downloads:
Hover over for data definitions.
Title Example
XML Sample http://foreignassistance.gov/dashboardservice/dashboardserviceapi.svc/xml/GetData?type=spent&filter=country&option=ghana&year=2013
Result
  • <a:FAActivity>
  • <a:AgencyName>MCC</a:AgencyName>U.S. Government agency.
  • <a:Amount>-15221</a:Amount>The dollar amount of the implementing mechanism signed (ie; total contract cost, total activity cost, total grant cost).
  • <a:Category>General</a:Category>ForeignAssistance.gov category mapping.
  • <a:FiscalYear>2013</a:FiscalYear>In annual and multi-year funds, identifies the first fiscal year of availability under law that an appropriation account may incur new obligations.
  • <a:BenefitingLocation>Ghana</aBenefitingLocation>Target beneficiary location of the foreign assistance funds; country if possible, otherwise by lowest level of geographic granularity available.
  • <a:Sector>Agriculture</a:Sector>The 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.
  • </a:FAActivity>
JSON Sample http://foreignassistance.gov/dashboardservice/dashboardserviceapi.svc/json/GetData?type=spent&filter=country&option=ghana&year=2013
Result
  • {
  • <a:AgencyName>MCC</a:AgencyName>U.S. Government agency.
  • <a:Amount>-15221</a:Amount>The dollar amount of the implementing mechanism signed (ie; total contract cost, total activity cost, total grant cost).
  • <a:Category>General</a:Category>ForeignAssistance.gov category mapping.
  • <a:FiscalYear>2013</a:FiscalYear>In annual and multi-year funds, identifies the first fiscal year of availability under law that an appropriation account may incur new obligations.
  • <a:BenefitingLocation>Ghana</aBenefitingLocation>Target beneficiary location of the foreign assistance funds; country if possible, otherwise by lowest level of geographic granularity available.
  • <a:Sector>Agriculture</a:Sector>The 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.
  • }

Data Definitions
The following fields are associated with the data returned by the API.
Name Description Type Size
Agency Name U.S. Government agency. varchar 4000
Amount The dollar amount of the implementing mechanism signed (ie; total contract cost, total activity cost, total grant cost). decimal 8,2
Category ForeignAssistance.gov category mapping. varchar 4000
Fiscal Year In annual and multi-year funds, identifies the first fiscal year of availability under law that an appropriation account may incur new obligations. int 4
Benefitting Location Target beneficiary location of the foreign assistance funds; country if possible, otherwise by lowest level of geographic granularity available. varchar 4000
Sector The 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. varchar 4000


Example Use
Some variations of the possible combinations for the API are as follows:
Hover over for example links.
Data Format Data Type Data Filter Data Option Data Example
XML Planning Country Pakistan Example Link Herehttp://foreignassistance.gov/dashboardservice/dashboardserviceapi.svc/XML/GetData?type=planning&filter=country&option=pakistan&year=2012
XML Spent Country Pakistan Example Link Herehttp://foreignassistance.gov/dashboardservice/dashboardserviceapi.svc/XML/GetData?type=spent&filter=country&option=pakistan&year=2012
JSON Obligation Sector Civil Society Example Link Herehttp://foreignassistance.gov/dashboardservice/dashboardserviceapi.svc/JSON/GetData?type=obligation&filter=sector&option=civil society&year=2012
JSON Transaction Sector Agriculture Example Link Herehttp://foreignassistance.gov/dashboardservice/dashboardserviceapi.svc/JSON/GetData?type=transaction&filter=sector&option=agriculture&year=2013