faads.php Method
Allows access to modified FAADS data on Federal assistance.
Error Codes and Warnings:
Currently there is only one error code associated with the faads method, although an expanded list is planned for future versions. In case of an error no results will be displayed and the error message will be displayed inside the <error> XML element.
Error message | Description: |
No records found | no records were found for the search criteria specified |
Arguments
datype (required) | must be set to X. If not, output will be HTML instead of XML. | ||||||||||||||
detail | Controls which type of output -- which "level of detail" -- you get. Choices are:
|
||||||||||||||
sortby | Determines how records are sorted. Valid values are:
r = by contractor or recipient name |
||||||||||||||
max_records | Allows you to set the maximum number of records retrieved to fewer than 1000 | ||||||||||||||
NOTE: At least one argument of the below search criteria is required in order to produce results | |||||||||||||||
fiscal_year | Specifies a single year from 2000-2007. | ||||||||||||||
first_year_range | Specifies the first year in a range of years from 2000-2006; if used, must be used with last_year_range and without fiscal_year | ||||||||||||||
last_year_range | Specifies the last year in a range of years from 2000-2006; if used, must be used with first_year_range and without fiscal_year | ||||||||||||||
recipient_name | The name of a recipient of assistance | ||||||||||||||
recipient_city_name | The city in the address of a recipient | ||||||||||||||
recipient_state_code | The FIPS state code for the state in the address of a recipient. See here for list. | ||||||||||||||
recipient_zip | The ZIP code in the address of a recipient | ||||||||||||||
recipient_county_name | The county in which a recipient is located | ||||||||||||||
recipient_cd | The Congressional District in which the recipient is located, formatted with four characters. See here for list. | ||||||||||||||
principal_place_state_code | The FIPS state code for the state of the place of performance. See here for list. | ||||||||||||||
principal_place_cc | The city or county of the place of performance. | ||||||||||||||
agency_code | The 4-character code for a specific governmental agency providing assistance. See here for list. | ||||||||||||||
maj_agency_cat | The 2-character code for a major governmental agency providing assistance. See here for list. | ||||||||||||||
recip_cat_type | The type of recipient. Valid values are:
f = For Profits |
||||||||||||||
asst_cat_type | The type of assistance provided. Valid values are:
d = Direct Payments (both specified and unrestricted) |
||||||||||||||
project_description | A free text search on a description of the project. | ||||||||||||||
cfda_program_num | An ID for the governmental program. See here for list. | ||||||||||||||
federal_award_id | A Federal ID for the award | ||||||||||||||
duns_number | The recipient duns number. | ||||||||||||||
progsrc_agen_code | The program source agency code. | ||||||||||||||
progsrc_acnt_code | The program source account code. | ||||||||||||||
program_source_desc | Full text search of program source description. |
Example Call
//www.usaspending.gov/faads/faads.php?datype=X&detail=-1&recipient_name=Smith&fiscal_year=2006
in this example there are 4 arguments submitted to the API method:
1. datatype=X which is the required argument showing that the output will be in XML
2. detail = -1 indicating the desired level of detail (in this case detail=-1 or Summary)
3. recipient_name = Smith and fiscal_year = 2006 is search criteria. As least one search criteria argument must be present.
Example Output
Note that besides the actual data, the XML contains the search criteria submitted to the method.
<?xml version="1.0"?> <fedspendingSearchResults xml_format_version="0.6" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="faads_summary.xsd"> <search_criteria> <search_criterion field="Recipient Name" value="Smith"/> <search_criterion field="Federal Fiscal Year" value="2006"/> <search_criterion field="Sort By" value="No sort (summary only)"/> <search_criterion field="Level of Detail" value="Summary"/> <search_criterion field="Type of Report Output" value="XML"/> </search_criteria> <data compiled_from_government_data_last_released_on="2006-11-01" database="FAADS" description="U.S. Federal grants and other assistance" max_records="1000"> <record detail="summary" description="summary record for search" database="FAADS"> <totals> <fiscal_year>2006</fiscal_year> <fed_total>51301419</fed_total> <number_of_recipients>378</number_of_recipients> <number_of_transactions>442</number_of_transactions> </totals> <top_known_congressional_districts description="Top congressional districts where recipients are located" ranked_by="total obligated amount in dollars" maximum_shown="5"> <congressional_district rank="1" total_obligatedAmount="15482243">Arkansas 2 (Vic Snyder)</congressional_district> ... </top_known_congressional_districts> <top_cfda_programs ranked_by="total obligated amount in dollars" maximum_shown="5"> <cfda_program rank="1" total_obligatedAmount="20979059">84.268: Federal Direct Student Loans</cfda_program> ... </top_cfda_programs> <top_agencies_providing_assistance ranked_by="total obligated amount in dollars" maximum_shown="5"> <agency rank="1" total_obligatedAmount="26648200">Small Business Administration</agency> ... </top_agencies_providing_assistance> <top_recipients ranked_by="total obligated amount in dollars" maximum_shown="10"> <recipient rank="1" total_obligatedAmount="15482243">PHILANDER SMITH COLLEGE</recipient> ... </top_recipients> <assistance_types description="total Federal obligated dollars for each type of governmental assistance"> <direct_payments_both_specified_and_unrestricted>1135675</direct_payments_both_specified_and_unrestricted> <grants_and_cooperative_agreements>22755298</grants_and_cooperative_agreements> <insurance>0</insurance> <loans_both_direct_and_guaranteed>27410446</loans_both_direct_and_guaranteed> <other>0</other> </assistance_types> <recipient_types description="total Federal obligated dollars for each type of recipient"> <for_profits>1450351</for_profits> <government>992263</government> <higher_education>20936556</higher_education> <individuals>27460488</individuals> <nonprofits>290557</nonprofits> <other>171204</other> </recipient_types> </record> </data> </fedspendingSearchResults>