Skip to navigation Skip to content
Provide Feedback |  Site Map |  Contact Us   |  Last updated on March 05, 2010  
USA Flag Icon  
USASpending.gov

API


fpds.php Method

Allows access to modified FPDS data on Federal contracts.

Error Codes and Warnings:

Currently there are only two error codes 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 for the search criteria no records were found for the search criteria specified
No more search results no records were found from the specified records_from start position
Arguments
#Added for program source parameters and duns number
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:

-1 Summary
The output XML for this level of detail includes general information such as the totals, the extent of competition, top 5 products or services sold, top 5 purchasing agencies, top 10 contractors etc.
HTML Example
XML Example
0 Low (list of contractors)
The output XML for this level of detail includes a list of contractors with contractor names, parent company names and total amounts for each contractor.
HTML Example
XML Example
1 Medium (contractor profiles)
The output XML for this level of detail includes a list of the same contractors as for the low level of details but provides significantly more data for each contractor.
HTML Example
XML Example
2 High (list of transactions)
The output XML for this level of detail includes a list of individual transactions. As with the low level of detail, there is only a few fields for each transaction (amount, parent company name, major agency, date and product/service)
HTML Example
XML Example
3 Extensive (detailed info on each transaction)
The output XML for this level of detail includes a list of the same transactions as for the high level of details but provides significantly more data for each transaction.
HTML Example
XML Example
4 Complete (all information)
The output XML for this level of detail includes ALL the information available for the given search criteria.
Important: this level of detail outputs a very large XML document that might take a while to download, it is advisable to use a lesser level of detail if possible
HTML Example
XML Example
Defaults to -1 (summary) if not set.
sortby Determines how records are sorted. Valid values are:

r = by contractor or recipient name
f = by dollars of awards (in descending order)
g = by major contracting agency
p = by Product or Service Category
d = by date of award
Defaults to sort by dollars if not provided.
max_records Allows you to set the maximum number of records retrieved to fewer than 1000
records_from Allows you to set the starting position of the records to be retrieved
NOTE: At least one argument of the below search criteria is required in order to produce results
fiscal_year Specifies a single year; defaults to all years.
first_year_range Specifies the first year in a range of years; 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; if used, must be used with first_year_range and without fiscal_year
company_name The name of a a contractor or contractor parent company
city The city within a contractor's address
state The state abbreviation within a contractor's address.
ZIPCode The ZIP code within a contractor's address.
vendorCountryCode The two-letter country code for the country in a contractor's address. See here for list.
vendor_cd The 4-character Congressional District within which a contractor is located. See here for list.
pop_cd The Congressional District of the place of performance. See here for list.
stateCode The state abbreviation of the state of the place of performance
placeOfPerformanceZIPCode The ZIP code of the place of performance.
placeOfPerformanceCountryCode The two-letter country code for the place of performance country. See here for list.
mod_agency The 4-digit code for a specific governmental agency issuing contracts. See here for list.
maj_agency_cat The 2-character code for a major governmental agency issuing contracts. See here for list.
psc_cat The 2-character code for a major product or service category. See here for list.
psc_sub The 4-character code for a product or service. See here for list.
descriptionOfContractRequirement Free text search within the text that describes what the contract is for.
PIID A Federal ID number for the contract.
compete_cat The competition status of a contract. Values are:

c = Available for everyone for competition
o = Everyone could compete, but only one bid or offer was recieved
p = Competition within a limited pool
n = Not competed for an allowable reason
a = Available only for groups such as disabled persons, prisoners, and regulated utilities
f = Actions necessary to continue existing competitive contracts for continuity (until the next one could be competed)
u = Not identified, soon to be addressed
duns_number The contractor duns number.
program_source_agency_code The program source agency code.
program_source_account_code The program source account code.
program_source_desc Full text search of program source description.
busn_indctr Determines the Business Fund Indicator:

r = funds provided by Recovery Act

Example Call

Summary for contracts for the state of Alabama: //www.usaspending.gov/fpds/fpds.php?datype=X&detail=-1&state=AL

in this example there are 3 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. state = AL search criteria with state = to AL (Alabama). 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. 

  <USAspendingSearchResults xml_format_version="0.6" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xsi:noNamespaceSchemaLocation="fpds_summary.xsd">
   	 <search_criteria>
			<search_criterion field="Contractor State" value="Alabama"/>
			<search_criterion field="Sort By" value="No sort (summary only)"/>
			<search_criterion field="Level of Detail" value="Summary"/>
			<search_criterion field="Output" value="XML"/>
	</search_criteria>
  <data compiled_from_government_data_last_released_on="2006-10-10" database="FPDS" 
description="U.S. Federal contracts" max_records="1000">
  <record detail="summary" description="summary record for search" database="FPDS">
  <totals>
	  <total_ObligatedAmount>31533355314.79</total_ObligatedAmount>
	  <rank_among_states>20</rank_among_states>
	  <number_of_contractors>4731</number_of_contractors>
	  <number_of_transactions>147101</number_of_transactions>
  </totals>
  <extent_of_competition description="total obligated amount dollars by extent of competition in contracts">
   	<full_and_open_competition>15335240279.53</full_and_open_competition>
   	<full_and_open_competition_but_only_one_bid>3116092659.03</full_and_open_competition_but_only_one_bid>
	<competition_after_exclusion_of_sources>6052315503.32</competition_after_exclusion_of_sources>
	<follow_on_contract>213508017.24</follow_on_contract>
	<not_available_for_competition>2187289457.30</not_available_for_competition>
	<not_competed>3908817553.50</not_competed>
	<unknown>720091844.87</unknown>
  </extent_of_competition>
  <top_known_congressional_districts description="Top congressional districts where work is performed"
 ranked_by="total obligated amount in dollars" maximum_shown="5">
     <congressional_district rank="1" total_obligatedAmount="13839820351.79">
Alabama 5 (Robert E. (Bud) Cramer Jr.)</congressional_district>
     ...
  </top_known_congressional_districts>
  <top_products_or_services_sold ranked_by="total obligated amount in dollars" maximum_shown="5">
     <product_or_service_category rank="1" total_obligatedAmount="3014132809.00">
Other Defense -- Advanced Development (R&amp;D)</product_or_service_category>
     ...
  </top_products_or_services_sold>
  <top_contracting_agencies ranked_by="total obligated amount in dollars" maximum_shown="5">
  	<agency rank="1" total_obligatedAmount="16469203977.27">
ARMY, Department of the (except Corps of Engineers Civil Program Financing)</agency>
		...
  </top_contracting_agencies>
  <top_contractor_parent_companies ranked_by="total obligated amount in dollars" maximum_shown="10">
  	<contractor_parent_company rank="1" total_obligatedAmount="3231332670.00">
BOEING CO.</contractor_parent_company>
		...
  </top_contractor_parent_companies>
  <fiscal_years description="total obligated amount in dollars by year">
  	<fiscal_year year="2000">3095382695.72</fiscal_year>
		...
  </fiscal_years>
  </record>
  </data>
  </USAspendingSearchResults>

Accessibility | Contact Info | Privacy Policy

EGOV  Whitehouse.gov  Recovery.gov