nokey.government package

Submodules

nokey.government.federal_register module

class nokey.government.federal_register.FederalRegister(use_caching=False, cache_name='federal_register_cache', backend='sqlite', expire_after=3600)

Bases: object

A class for interacting with the Federal Register API.

base_url

The base URL of the API.

about

A short description of the API.

get_agencies_details()

Returns all agency details.

Parameters:

None –

Returns:

A dictionary containing all agency details.

Return type:

dict

get_agency_by_slug(slug)

Returns a particular agency’s details.

Parameters:

slug (str) – The Federal Register slug for the agency. See Federal Register API docs for extensive list of possible values.

Returns:

A dictionary containing a particular agency’s details.

Return type:

dict

get_current_public_inspection_documents()

Returns all the public inspection documents that are currently on public inspection.

Parameters:

None –

Returns:

A dictionary containing all the public inspection documents that are currently on public inspection.

Return type:

dict

get_docs_url()

Returns the URL for the Federal Register API documentation.

Parameters:

None –

Returns:

The URL for the API docs.

Return type:

string

get_document_counts_by_facet(facet, search_term=None, doc_type=None)

Returns counts of matching Federal Register documents grouped by a facet.

Parameters:

• facet (str) – The facet by which to group the documents. Supported values are daily, weekly, monthly, quarterly, yearly, agency, topic, section, type, and subtype.

• search_term (str) – Option search query term. Defaults to None.

• doc_type (str) – Additional optional search by document type. Supported values are rule (final rule), prorule (proposed rule), notice (notice), and presdocu (presidential document)

Returns:

Returns a dictionary of document counts for the given parameters.

Return type:

dict

get_document_toc_by_date(pub_date)

Returns the document table of contents based on print edition.

Parameters:

pub_date (str) – The exact publication date (YYYY-MM-DD).

Returns:

A dictionary containing the document table of contents that matches the given date.

Return type:

dict

get_fed_reg_document(document_num)

Returns a Federal Register document of the given number.

Parameters:

document_num (str) – The unique number for the document.

Returns:

A dictionary containing the document matching the given number.

Return type:

dict

get_image_variants_by_id(image_id)

Returns the available image variants and their metadata for a single image identifier.

Parameters:

image_id (str) – The Federal Register image identifier.

Returns:

A dictionary containing the available image variants and their metadata for a single image identifier.

Return type:

dict

get_multiple_fed_reg_documents(document_nums)

Returns multiple Federal Register documents of the given numbers.

Parameters:

document_nums (str) – A string of unspaced, comma-separated document numbers.

Returns:

A dictionary containing the documents matching the given numbers.

Return type:

dict

get_multiple_public_inspection_documents(document_nums)

Returns the public inspection documents matching the given numbers.

Parameters:

document_nums (str) – The numbers matching the public inspection documents, separated by commas, no spaces.

Returns:

A dictionary containing the public inspection documents matching the given numbers.

Return type:

dict

get_public_inspection_document(document_num)

Returns a single public inspection document matching the given number.

Parameters:

document_num (str) – The number matching the public inspection document.

Returns:

A dictionary containing a single public inspection document matching the given number.

Return type:

dict

get_suggested_search_by_slug(slug)

Returns a particular suggested search.

Parameters:

slug (str) – The Federal Register slug for the suggested search. See Federal Register API docs for extensive list of possible values.

Returns:

A dictionary containing a particular suggested search.

Return type:

dict

get_suggested_searches_by_section(section)

Returns all suggested searches or limit by FederalRegister.gov section.

Parameters:

section (str) – The Federal Register slug for the section. Supported values are business-and-industry, environment, health-and-public-welfare, money, science-and-technology, and world.

Returns:

A dictionary containing all the suggested searches or limit by Federal.Register.gov section.

Return type:

dict

search_all_documents(search_term, per_page=20, doc_type=None)

Returns the Federal Register documents published since 1994 matching the given parameters.

Parameters:

• search_term (str) – The term by which to search the documents.

• per_page (int) – The number of documents to return at once; default is 20; 1000 maximum.

• doc_type (str) – Additional optional search by document type. Supported values are rule (final rule), prorule (proposed rule), notice (notice), and presdocu (presidential document)

Returns:

A dictionary containing the documents published since 1994 matching the given values.

Return type:

dict

search_all_public_inspection_documents(pub_date, per_page=20, search_term=None, doc_type=None)

Returns the Federal Register documents published since 1994 matching the given parameters.

Parameters:

• pub_date (str) – Public inspection issue date (YYYY-MM-DD).

• per_page (int) – The number of documents to return at once; default is 20; 1000 maximum.

• search_term (str) – The term by which to search the documents.

• doc_type (str) – Additional optional search by document type. Supported values are rule (final rule), prorule (proposed rule), notice (notice), and presdocu (presidential document)

Returns:

A dictionary containing the documents published since 1994 matching the given values.

Return type:

dict

nokey.government.usa_spending module

class nokey.government.usa_spending.USAspending(use_caching=False, cache_name='usa_spending_cache', backend='sqlite', expire_after=3600)

Bases: object

A class for interacting with the USA Spending API.

base_url

The base URL for the API.

about

A short description of the API.

awarding_agency_and_office_autocomplete(search_text, limit=None)

Returns a list of rewarding agencies matching the specified search text.

Parameters:

• search_text (str) – Text for search query.

• limit (int) – Optional. Maximum number of results to return. Default is None.

Returns:

A dictionary containing list of rewarding agencies.

Return type:

dict

bulk_award_download(filters, file_format='csv')

Returns a ZIP file of award data for download.

Parameters:

• filters (dict) – A dictionary of filter options for the downloaded data. See the endpoint docs for the format of this filter object.

• file_format (str) – Format of the file to be downloaded. Default is csv, but other options are tsv and pstxt.

Returns:

Dictionary containing the data regarding ZIP file for download.

Return type:

dict

cfda_autocomplete(search_text, limit=None)

Returns a list of cfda programs matching the specified search text.

Parameters:

• search_text (str) – Text for search query.

• limit (int) – Optional. Maximum number of results to return. Default is None.

Returns:

A dictionary containing list of cfda programs.

Return type:

dict

city_autocomplete(search_text, limit, country_code, scope, state_code=None)

Returns a list of city names matching the specified search text.

Parameters:

• search_text (str) – Text for search query.

• limit (int) – Maximum number of results to return. Required.

• country_code (str) – Country code part of a filter object.

• scope (str) – Scope of the search, part of a filter object. Possible values are primary_place_of_performance and recipient_location.

• state_code (str) – Optional state code part of a filter object.

Returns:

A dictionary containing list of city names.

Return type:

dict

download_account(account_level, submission_types, fiscal_year, agency=None, federal_account=None, quarter=None, period=None, def_codes=None, file_format='csv')

Generate files and return metadata using filters on custom account.

Parameters:

• account_level (str) – Used to filter for a specific type of file. Specific values are treasury_account and federal_account.

• submission_types (list) – Possible values are account_balances, object_class_program_activity, and award_financial.

• fiscal_year (int) – Fiscal year.

• agency (str) – Optional. The agency on which to filter. This field expects an internal toptier agency identifier also known as the toptier_agency_id. Defaults to None.

• federal_account (str) – Optional. An internal id. Defaults to None.

• quarter (int) – Either quarter or period is required. Do not supply both. Note that both monthly and quarterly submissions will be included in the resulting download file even if only quarter is provided. Possible values are 1, 2, 3, and 4.

• period (int) – Either quarter or period is required. Do not supply both. Agencies cannot submit data for period 1 so it is disallowed as a query filter. Note that both monthly and quarterly submissions will be included in the resulting download file even if only period is provided. Possible values are 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, and 12.

• def_codes (list) – Option search parameter by def codes.

• file_format (str) – Optional. Defaults to csv, but other values are tsv and pstxt.

Returns:

A dictionary containing information on the download job.

Return type:

dict

download_assistance_data(award_id, file_format='csv')

Creates a new download job for the requested award and returns a link to a zipped file containing contract award data.

Parameters:

• award_id (str) – Unique identifier for the award.

• file_format (str) – Optional. Defaults to csv, but other values are tsv and pstxt.

Returns:

A dictionary containing information about the download job.

Return type:

dict

download_award_data_advanced(filters, columns=None, file_format='csv', limit=None)

Creates a download job for the award data matching the search filters.

Parameters:

• filters (dict) – An advanced json object for filtering results. Must contain ar least one filter entry. See this endpoint’s docs for information on format of this filtering object.

• columns (list) – A list of the column names desired. Default is None.

• file_format (str) – Default is csv, but other options are tsv and pstxt.

• limit (int) – Optional. Number of items in file. Default is None.

Returns:

A dictionary containing information about the download job.

Return type:

dict

download_contract_data(award_id, file_format='csv')

Creates a new download job for the requested award and returns a link to a zipped file containing award contract data.

Parameters:

• award_id (str) – Unique identifier for the award.

• file_format (str) – Optional. Defaults to csv, but other values are tsv and pstxt.

Returns:

A dictionary containing information about the download job.

Return type:

dict

download_def_data(def_codes, file_format='csv')

Creates a new download job for the requested COVID-19 related account and award. Returns a link to a zipped file containing the generated data files.

Parameters:

• def_codes (list) – A list of Disaster Emergency Fund (def) codes (strings). Possible values are L, M, N, O, P, U, and V, but it must be either one of these or all of them.

• file_format (str) – Optional. Defaults to csv, but other values are tsv and pstxt.

Returns:

A dictionary containing information about the download job.

Return type:

dict

download_def_recipient_data(def_codes, award_type_codes=None, query=None)

Returns information to download a zip file of recipient disaster data. Specifically, only COVID-19 at the moment

Parameters:

• def_codes (list) – A list of Disaster Emergency Fund (def) codes (strings). Possible values are L, M, N, O, P, U, and V, but it must be either one of these or all of them.

• award_type_codes (list) – Optional. Possible values are 02, 03, 04, 05, 06, 07, 08, 09, 10, 11, A, B, C, D, IDV_A, IDV_B_A, IDV_B_B, IDV_B_C, IDV_B, IDV_C, IDV_D, IDV_E, and -1.

• query (str) – Search query term.

Returns:

A dictionary containing information about the download job.

Return type:

dict

download_idv_data(award_id, file_format='csv')

Creates a new download job for the requested award and returns a link to a zipped file containing IDV data.

Parameters:

• award_id (str) – Unique identifier for the award.

• file_format (str) – Optional. Defaults to csv, but other values are tsv and pstxt.

Returns:

A dictionary containing information about the download job.

Return type:

dict

download_transaction_count(filters)

Returns the number of transactions that would be included in a download request for the given filter set.

Parameters:

filters (dict) – Advanced json filter object. See this endpoint’s docs for information on the format of this json object.

Returns:

A dictionary containing a number of transactions.

Return type:

dict

download_transactions_data_advanced(filters, columns=None, file_format='csv', limit=None)

Creates a download job for the transaction data matching the search filters.

Parameters:

• filters (dict) – An advanced json object for filtering results. Must contain ar least one filter entry. See this endpoint’s docs for information on format of this filtering object.

• columns (list) – A list of the column names desired. Default is None.

• file_format (str) – Default is csv, but other options are tsv and pstxt.

• limit (int) – Optional. Number of items in file. Default is None.

Returns:

A dictionary containing information about the download job.

Return type:

dict

explore_spending(Type, filters)

Returns spending data information through various types of filters.

Parameters:

• Type (str) – Options are federal_account, object_class, recipient, award, budget_function, budget_subfunction, agency, and program_activity.

• filters (dict) – An advanced JSON search object. See this endpoint’s docs for the format of this object.

Returns:

A dictionary containing spending data information through various types of filters.

Return type:

dict

funding_agency_autocomplete(search_text, limit=None)

Returns a list of funding agencies matching the specified search text.

Parameters:

• search_text (str) – Text for search query.

• limit (int) – Optional. Maximum number of results to return. Default is None.

Returns:

A dictionary containing list of funding agencies.

Return type:

dict

get_agencies_awarding_def_loans(def_codes, award_type_codes=None, limit=10, page=1, sort='id', order='desc')

Returns insights on the Agencies awarding loans from disaster/emergency funding per the requested filters.

Parameters:

• def_codes (list) – A list of Disaster Emergency Fund (def) codes (strings). Possible values are L, M, N, O, P, U, and V.

• award_type_codes (list) – Optional. Only accepts loan award type 07 or 08 in the array, since this endpoint is specific to loans. Defaults to None.

• limit (int) – Page size of results. Default is 10.

• page (int) – Pagination parameter. Defaults to first page.

• order (str) – Order of returned data. Defaults to desc (descending), with asc (ascending) as other option.

• sort (str) – Optional parameter indicating what returns values should be sorted by. Default is id, but other options are code, description, award_count, face_value_of_loan, obligation, and outlay.

Returns:

A dictionary containing insights on the Agencies awarding loans from disaster/emergency funding per the requested filters.

Return type:

dict

get_agencies_receiving_def_funding(def_codes, spending_type='total', award_type_codes=None, limit=10, page=1, sort='id', order='desc')

Returns insights on the Agencies receiving funding from disaster/emergency funding per the requested filters.

Parameters:

• def_codes (list) – A list of Disaster Emergency Fund (def) codes (strings). Possible values are L, M, N, O, P, U, and V.

• spending_type (str) – Spending type. Defaults to total, but other option is award.

• award_type_codes (list) – Optional. Only to be used if spending type is award. Possible values are 02, 03, 04, 05, 06, 07, 08, 09, 10, 11, A, B, C, D, IDV_A, IDV_B_A, IDV_B_B, IDV_B_C, IDV_B, IDV_C, IDV_D, IDV_E, and -1.

• limit (int) – Page size of results. Default is 10.

• page (int) – Pagination parameter. Defaults to first page.

• order (str) – Order of returned data. Defaults to desc (descending), with asc (ascending) as other option.

• sort (str) – Optional parameter indicating what returns values should be sorted by. Default is id, but other options are code, description, award_count, face_value_of_loan, obligation, and outlay.

Returns:

A dictionary containing insights on the Agencies receiving funding from disaster/emergency funding per the requested filters.

Return type:

dict

get_agency_overview_by_agency_id(agency_id)

Returns a high-level overview of a specific government agency, given its USAspending.gov id.

Parameters:

agency_id (int) – The unique USAspending.gov agency identifier. This ID is the agency_id value returned in the /api/v2/references/toptier_agencies/ endpoint.

Returns:

A dictionary containing an agency overview.

Return type:

dict

get_agency_overview_by_toptier_code(toptier_code, page=1, limit=10, order='desc', sort='current_total_budget_authority_amount')

Returns an overview of government agency submission data.

Parameters:

• toptier_code (str) – The specific agency’s toptier code.

• page (int) – Pagination parameter. Defaults to first page.

• limit (int) – Number of items per page. Defaults to 10.

• order (str) – The direction (asc or desc) that the sort field will be sorted in. Defaults to desc.

• sort (str) – A data field that will be used to sort the response array. Default is current_total_budget_authority_amount, but other options are fiscal_period, fiscal_year, missing_tas_accounts_count, tas_accounts_total, obligation_difference, percent_of_total_budgetary_resources, recent_publication_date, recent_publication_date_certified, tas_obligation_not_in_gtas_total, unlinked_contract_award_count, and unlinked_assistance_award_count.

Returns:

A dictionary containing an overview of government agency submission data.

Return type:

dict

get_agency_overview_by_year(fiscal_year, fiscal_period, Filter=None, page=1, limit=10, order='desc', sort='current_total_budget_authority_amount')

Returns an overview of government agency submission data.

Parameters:

• fiscal_year (int) – The fiscal year.

• fiscal_period (int) – The fiscal period. Valid values: 2-12 (2 = November … 12 = September) For retriving quarterly data, provide the period which equals ‘quarter * 3’ (e.g. Q2 = P6).

• Filter (str) – The agency name or abbreviation to filter on (partial match, case insesitive). Defaults to None.

• page (int) – Pagination parameter. Defaults to first page.

• limit (int) – Number of items per page. Defaults to 10.

• order (str) – The direction (asc or desc) that the sort field will be sorted in. Defaults to desc.

• sort (str) – A data field that will be used to sort the response array. Default is current_total_budget_authority_amount, but other options are fiscal_period, fiscal_year, missing_tas_accounts_count, tas_accounts_total, obligation_difference, percent_of_total_budgetary_resources, recent_publication_date, recent_publication_date_certified, tas_obligation_not_in_gtas_total, unlinked_contract_award_count, and unlinked_assistance_award_count.

Returns:

A dictionary containing an overview of government agency submission data.

Return type:

dict

get_agency_overview_info(toptier_agency_code, fiscal_year=2024)

Returns agency overview information for USAspending.gov’s Agency Details page for agencies that have ever awarded.

Parameters:

• toptier_agency_code (str) – A numerical code (in string form, due to the use of leading zeros) identifying the agency.

• fiscal_year (int) – The fiscal year. Optional parameter, defaults to the current year.

Returns:

A dictionary containing the agency overview information.

Return type:

dict

get_agency_reporting_publish_dates(fiscal_year, Filter=None, page=1, limit=10, order='desc', sort='current_total_budget_authority_amount')

Returns list of agency submission information, included published and certified dates for the fiscal year.

Parameters:

• fiscal_year (int) – The fiscal year.

• Filter (str) – The agency name or abbreviation to filter on (partial match, case insesitive). Defaults to None.

• page (int) – Pagination parameter. Defaults to first page.

• limit (int) – Number of items per page. Defaults to 10.

• order (str) – The direction (asc or desc) that the sort field will be sorted in. Defaults to desc.

• sort (str) – A data field that will be used to sort the response array. Default is current_total_budget_authority_amount, but other options are agency_name, abbreviation, toptier_code, and publication_date.

Returns:

A dictionary containing a list of agency submission information, included published and certified dates for the fiscal year.

Return type:

dict

get_agency_summary_info(toptier_agency_code, fiscal_year=2024, agency_type='awarding')

Returns agency summary information, specifically the number of transactions and award obligations for the sub agency section of USAspending.gov’s Agency Details page.

Parameters:

• toptier_agency_code (str) – A numerical code (in string form, due to the use of leading zeros) identifying the agency.

• fiscal_year (int) – The fiscal year. Optional parameter, defaults to the current year.

• agency_type (str) – Optional. Determines if the data being returned is derived from the awarding agency or the funding agency. Defaults to awarding, but other option is funding.

Returns:

A dictionary containing the agency summary information.

Return type:

dict

get_aggregated_def_spending(def_codes, spending_type='total', award_type_codes=None, award_type=None, limit=10, page=1, sort='id', order='desc')

Returns account data obligation and outlay spending aggregations of all (File D) Awards which received disaster/emergency funding per the requested filters.

Parameters:

• def_codes (list) – A list of Disaster Emergency Fund (def) codes (strings). Possible values are L, M, N, O, P, U, and V.

• spending_type (str) – Spending type. Defaults to total, but other option is award.

• award_type_codes (list) – Optional. Only to be used if spending type is award. Possible values are 02, 03, 04, 05, 06, 07, 08, 09, 10, 11, A, B, C, D, IDV_A, IDV_B_A, IDV_B_B, IDV_B_C, IDV_B, IDV_C, IDV_D, IDV_E, and -1.

• award_type (str) – When provided, it will return results limiting to the award type (Assistance or Procurment) based on Financial Account data. This is mutually exclusive from award_type_codes. Possible values are procurement and assistance.

• limit (int) – Page size of results. Default is 10.

• page (int) – Pagination parameter. Defaults to first page.

• order (str) – Order of returned data. Defaults to desc (descending), with asc (ascending) as other option.

• sort (str) – Optional parameter indicating what returns values should be sorted by. Default is id, but other options are code, description, award_count, face_value_of_loan, obligation, and outlay.

Returns:

A dictionary containing account data obligation and outlay spending aggregations of all (File D) Awards which received disaster/emergency funding per the requested filters.

Return type:

dict

get_aggregated_def_spending_count(def_codes, spending_type='total', award_type_codes=None, award_type=None, limit=10, page=1, sort='id', order='desc')

Returns the count of account data obligation and outlay spending aggregations of all (File D) Awards which received disaster/emergency funding per the requested filters.

Parameters:

• def_codes (list) – A list of Disaster Emergency Fund (def) codes (strings). Possible values are L, M, N, O, P, U, and V.

• spending_type (str) – Spending type. Defaults to total, but other option is award.

• award_type_codes (list) – Optional. Only to be used if spending type is award. Possible values are 02, 03, 04, 05, 06, 07, 08, 09, 10, 11, A, B, C, D, IDV_A, IDV_B_A, IDV_B_B, IDV_B_C, IDV_B, IDV_C, IDV_D, IDV_E, and -1.

• award_type (str) – When provided, it will return results limiting to the award type (Assistance or Procurment) based on Financial Account data. This is mutually exclusive from award_type_codes. Possible values are procurement and assistance.

• limit (int) – Page size of results. Default is 10.

• page (int) – Pagination parameter. Defaults to first page.

• order (str) – Order of returned data. Defaults to desc (descending), with asc (ascending) as other option.

• sort (str) – Optional parameter indicating what returns values should be sorted by. Default is id, but other options are code, description, award_count, face_value_of_loan, obligation, and outlay.

Returns:

A dictionary containing the count of account data obligation and outlay spending aggregations of all (File D) Awards which received disaster/emergency funding per the requested filters.

Return type:

dict

get_award_accounts(award_id, page=1, limit=None, order='desc', sort='federal_account')

Returns a list of federal accounts under a given award.

Parameters:

• award_id (str) – Unique matching the award.

• page (int) – Optional pagination parameter. Defaults to first page.

• limit (int) – Number of items to return. Defaults to None.

• order (str) – Ordering of the data. Defaults to desc (descending), and other option is asc (ascending).

• sort (str) – The field to sort on. Default is federal_account, but other options are account_title, agency, and total_transaction_obligated_amount.

Returns:

Dictionary containing a list of federal accounts under a given award.

Return type:

dict

get_award_data(award_id)

Returns a list of data that is associated with the award profile page.

Parameters:

award_id (str) – Unique identifier matching the award.

Returns:

Dictionary containing a list of data associated with an award.

Return type:

dict

get_award_funding_data(award_id, page=1, limit=10, order='desc', sort='reporting_fiscal_date')

Returns federal account, awarding agencies, funding agencies, and transaction obligated amount information for a requested award.

Parameters:

• award_id (str) – Unique identifier matching the award.

• page (int) – Optional pagination parameter. Defaults to first page.

• limit (int) – Number of items to return. Defaults to 10.

• order (str) – Ordering of the data. Defaults to desc (descending), and other option is asc (ascending).

• sort (str) – The field to sort on. Default is reporting_fiscal_date, but other options are account_title, awarding_agency_name, disaster_emergency_fund_code, federal_account, funding_agency_name, gross_outlay_amount, object_class, program_activity, and transaction_obligated_amount.

Returns:

Dictionary containing a list of data for a given award.

Return type:

dict

get_award_funding_obligations_and_count(award_id)

Returns the total transaction obligations and count of awarding agencies, funding agencies, and federal accounts for an award.

Parameters:

award_id (str) – Unique identifier matching the award.

Returns:

Dictionary containing a list of total transaction obligations and count of awarding agencies, funding agencies, and federal accounts for an award.

Return type:

dict

get_award_last_updated()

Returns the last updated date for the award data.

Parameters:

None –

Returns:

Dictionary containing the last updated date for the award data.

Return type:

dict

get_award_transactions_count(award_id)

Returns the number of transactions associated with the given award.

Parameters:

award_id (str) – Unique identifier matching the award.

Returns:

Dictionary containing the number of transactions associated with the given award.

Return type:

dict

get_award_types()

Returns a grouping of award types.

Parameters:

None –

Returns:

A dictionary containing a grouping of award types.

Return type:

dict

get_awards_type_count(group='all', fiscal_year=2024, order='desc', limit=1, page=1)

Returns a count of Awards types for agencies in a single fiscal year.

Parameters:

• group (str) – Optional parameter. Use cfo to get results where CFO designated agencies are returned. Otherwise the default is all.

• fiscal_year (int) – The fiscal year. Optional parameter, defaults to the current year.

• order (str) – Indicates what direction results should be sorted by. Valid options include asc for ascending order or desc for descending order (default).

• limit (int) – The number of items to return. Default is 1.

• page (int) – Pagination parameter. Default is 1.

Returns:

A dictionary containing the count.

Return type:

dict

get_budget_function_count_for_agency(toptier_agency_code, fiscal_year=2024)

Returns the count of Budget Functions for the agency in a single fiscal year.

Parameters:

• toptier_agency_code (str) – A numerical code (in string form, due to the use of leading zeros) identifying the agency.

• fiscal_year (int) – The fiscal year. Optional parameter, defaults to the current year.

Returns:

A dictionary containing the count.

Return type:

dict

get_budget_functions()

Returns a list of all Budget Functions ordered by their title.

Parameters:

None –

Returns:

Dictionary containing a list of all Budget Functions ordered by their title.

Return type:

dict

get_budget_functions_for_agency(toptier_agency_code, fiscal_year=2024, Filter=None, order='desc', limit=10, page=1)

Returns a list of Budget Functions and Budget Subfunctions for the agency in a single fiscal year.

Parameters:

• toptier_agency_code (str) – A numerical code (in string form, due to the use of leading zeros) identifying the agency.

• fiscal_year (int) – The fiscal year. Optional parameter, defaults to the current year.

• Filter (str) – Optional. This will filter the Budget Function by their name to those matching the text.

• order (str) – Indicates what direction results should be sorted by. Valid options include asc for ascending order or desc for descending order (default).

• limit (int) – Optional parameter to limit number of items. Default is 10.

• page (int) – Pagination parameter. Default is 1.

Returns:

A dictionary containing a list of Budget Functions and Subfunctions.

Return type:

dict

get_budget_subfunctions(budget_function=None)

Returns a list of all Budget Subfunctions that can be filtered by Budget Function, ordered by their title.

Parameters:

budget_function (int) – Number matching the budget function.

Returns:

Dictionary containing a list of Budget Subfunctions.

Return type:

dict

get_budgetary_resources_for_agency(toptier_agency_code)

Returns budgetary resources and obligations for the agency and fiscal year requested.

Parameters:

toptier_agency_code (str) – A numerical code (in string form, due to the use of leading zeros) identifying the agency.

Returns:

A dictionary containing a list of budgetary resources and obligations.

Return type:

dict

get_cfda_programs_receiving_def_funding(def_codes, spending_type='total', award_type_codes=None, limit=10, page=1, sort='id', order='desc')

Returns insights on the cfda programs receiving funding from disaster/emergency funding per the requested filters.

Parameters:

• def_codes (list) – A list of Disaster Emergency Fund (def) codes (strings). Possible values are L, M, N, O, P, U, and V.

• spending_type (str) – Spending type. Defaults to total, but other option is award.

• award_type_codes (list) – Optional. Only to be used if spending type is award. Possible values are 02, 03, 04, 05, 06, 07, 08, 09, 10, 11, A, B, C, D, IDV_A, IDV_B_A, IDV_B_B, IDV_B_C, IDV_B, IDV_C, IDV_D, IDV_E, and -1.

• limit (int) – Page size of results. Default is 10.

• page (int) – Pagination parameter. Defaults to first page.

• order (str) – Order of returned data. Defaults to desc (descending), with asc (ascending) as other option.

• sort (str) – Optional parameter indicating what returns values should be sorted by. Default is id, but other options are code, description, award_count, face_value_of_loan, obligation, and outlay.

Returns:

A dictionary containing insights on the cfda programs receiving funding from disaster/emergency funding per the requested filters.

Return type:

dict

get_cfda_receiving_def_count(def_codes, award_type_codes=None)

Returns the count of CFDA programs which received disaster/emergency funding per the requested filters.

Parameters:

• def_codes (list) – A list of Disaster Emergency Fund (def) codes (strings). Possible values are L, M, N, O, P, U, and V.

• award_type_codes (list) – Optional. Possible values are 02, 03, 04, 05, 06, 07, 08, 09, 10, 11. Defaults to None here, but in the API it defaults to all the codes.

Returns:

A dictionary containing the count of CFDA programs which received disaster/emergency funding per the requested filters.

Return type:

dict

get_child_recipients_by_duns_or_uei(duns_or_uei, year='latest')

Returns a list of child recipients belonging to the given parent recipient DUNS or UEI.

Parameters:

• duns_or_uei (str) – Parent recipient’s DUNS or UEI.

• year (str) – The fiscal year you would like data for. Use all to view all time or latest to view the latest 12 months. Default is latest.

Returns:

A dictionary containing a list of child recipients.

Return type:

dict

get_count_agencies_receiving_def(def_codes)

Returns a count for agencies which received disaster/emergency funding per the requested filters.

Parameters:

def_codes (list) – A list of Disaster Emergency Fund (def) codes (strings). Possible values are L, M, N, O, P, U, and V.

Returns:

A dictionary containing a count of agencies which received disaster/emergency funding.

Return type:

dict

get_data_dictionary()

Returns data corresponding to the latest data dictionary csv file.

Parameters:

None –

Returns:

A dictionary containing data corresponding to the latest data dictionary csv file.

Return type:

dict

get_def_codes()

Returns a JSON object describing all Disaster and Emergency Funding (DEF) Codes.

Parameters:

None –

Returns:

A dictionary containing all Disaster and Emergency Funding (DEF) Codes

Return type:

dict

get_def_loans_for_cfda(def_codes, award_type_codes=None, limit=10, page=1, sort='id', order='desc')

Returns insights on the CFDA Programs’ loans from disaster/emergency funding per the requested filters.

Parameters:

• def_codes (list) – A list of Disaster Emergency Fund (def) codes (strings). Possible values are L, M, N, O, P, U, and V.

• award_type_codes (list) – Optional. Only accepts loan award type 07 or 08 in the array, since this endpoint is specific to loans. Defaults to None.

• limit (int) – Page size of results. Default is 10.

• page (int) – Pagination parameter. Defaults to first page.

• order (str) – Order of returned data. Defaults to desc (descending), with asc (ascending) as other option.

• sort (str) – Optional parameter indicating what returns values should be sorted by. Default is id, but other options are code, description, award_count, face_value_of_loan, obligation, and outlay.

Returns:

A dictionary containing insights on the CFDA Programs’ loans from disaster/emergency funding per the requested filters.

Return type:

dict

get_def_loans_for_federal_accounts(def_codes, award_type_codes=None, limit=10, page=1, sort='id', order='desc')

Returns insights on the Federal Accounts awarding loans from disaster/emergency funding per the requested filters.

Parameters:

• def_codes (list) – A list of Disaster Emergency Fund (def) codes (strings). Possible values are L, M, N, O, P, U, and V.

• award_type_codes (list) – Optional. Only accepts loan award type 07 or 08 in the array, since this endpoint is specific to loans. Defaults to None.

• limit (int) – Page size of results. Default is 10.

• page (int) – Pagination parameter. Defaults to first page.

• order (str) – Order of returned data. Defaults to desc (descending), with asc (ascending) as other option.

• sort (str) – Optional parameter indicating what returns values should be sorted by. Default is id, but other options are code, description, award_count, face_value_of_loan, obligation, and outlay.

Returns:

A dictionary containing insights on the Federal Accounts awarding loans from disaster/emergency funding per the requested filters.

Return type:

dict

get_def_loans_for_object_classes(def_codes, award_type_codes=None, limit=10, page=1, sort='id', order='desc')

Returns insights on the Object Classes’ loans from disaster/emergency funding per the requested filters.

Parameters:

• def_codes (list) – A list of Disaster Emergency Fund (def) codes (strings). Possible values are L, M, N, O, P, U, and V.

• award_type_codes (list) – Optional. Only accepts loan award type 07 or 08 in the array, since this endpoint is specific to loans. Defaults to None.

• limit (int) – Page size of results. Default is 10.

• page (int) – Pagination parameter. Defaults to first page.

• order (str) – Order of returned data. Defaults to desc (descending), with asc (ascending) as other option.

• sort (str) – Optional parameter indicating what returns values should be sorted by. Default is id, but other options are code, description, award_count, face_value_of_loan, obligation, and outlay.

Returns:

A dictionary containing insights on the Object Classes’ loans from disaster/emergency funding per the requested filters.

Return type:

dict

get_def_loans_for_recipients(def_codes, award_type_codes=None, limit=10, page=1, sort='id', order='desc')

Returns insights on the recipient loans from disaster/emergency funding per the requested filters.

Parameters:

• def_codes (list) – A list of Disaster Emergency Fund (def) codes (strings). Possible values are L, M, N, O, P, U, and V.

• award_type_codes (list) – Optional. Only accepts loan award type 07 or 08 in the array, since this endpoint is specific to loans. Defaults to None.

• limit (int) – Page size of results. Default is 10.

• page (int) – Pagination parameter. Defaults to first page.

• order (str) – Order of returned data. Defaults to desc (descending), with asc (ascending) as other option.

• sort (str) – Optional parameter indicating what returns values should be sorted by. Default is id, but other options are code, description, award_count, face_value_of_loan, obligation, and outlay.

Returns:

A dictionary containing insights on the recipient loans from disaster/emergency funding per the requested filters.

Return type:

dict

get_def_spending_by_geography(def_codes, geo_layer, spendng_type, geo_layer_filters=None, scope='recipient_location')

Returns geographical spending information from emergency/disaster funding based on recipient location.

Parameters:

• def_codes (list) – A list of Disaster Emergency Fund (def) codes (strings). Possible values are L, M, N, O, P, U, and V.

• geo_layer (str) – Sets the type of shape codes in the response. Possible values are state, county, and district.

• spending_type (str) – Possible values are obligation, outlay, and face_value_of_loan.

• geo_layer_filters (list) – Optional. Allows the API to only request data for what is currently in view in the map.. Defaults to None.

• scope (str) – Optional. When fetching awards, use the primary place of performance or recipient location. Defaults to recipient_location, but other values is place_of_performance.

Returns:

A dictionary containing geographical spending information from emergency/disaster funding based on recipient location.

Return type:

dict

get_defc_receiving_def_count(def_codes)

Returns the count of DEFC which received disaster/emergency funding per the requested filters.

Parameters:

def_codes (list) – A list of Disaster Emergency Fund (def) codes (strings). Possible values are L, M, N, O, P, U, and V.

Returns:

A dictionary containing the count of DEFC which received disaster/emergency funding per the requested filters.

Return type:

dict

get_docs_url()

Returns the URL for the USAspending API documentation.

Parameters:

None –

Returns:

The URL for the API docs.

Return type:

string

get_download_status(file_name)

Returns the current status of a download job.

Parameters:

file_name (str) – The full name of the file downloaded. Taken from the file_name field of a download endpoint response.

Returns:

Dictionary containing the current status of a download job.

Return type:

dict

get_federal_account(account_number, fiscal_year=2024)

Returns the agency identifier, account code, title, and database id for the given federal account.

Parameters:

• account_number (str) – The Federal Account symbol comprised of Agency Code and Main Account Code. A unique identifier for federal accounts.

• fiscal_year (str) – Desired fiscal year. Defaults to current year.

Returns:

A dictionary containing the agency identifier, account code, title, and database id for the given federal account.

Return type:

dict

get_federal_account_by_obligation(fiscal_year, funding_agency_id, limit=10, page=1)

Returns the amount that the specific agency has obligated to various federal accounts in a given fiscal year.

Parameters:

• fiscal_year (int) – The desired fiscal year.

• funding_agency_id (int) – The unique USAspending.gov agency identifier. This ID is the agency_id value returned in the /api/v2/references/toptier_agencies/ endpoint.

• limit (int) – Maximum number of results to return.

• page (int) – Optional pagination parameter. Defaults to first page.

Returns:

A dictionary containing the amount that the specific agency has obligated to various federal accounts in a given fiscal year.

Return type:

dict

get_federal_accounts_by_bureau_for_agency(toptier_agency_code, bureau_slug, fiscal_year=2024, agency_type='awarding', order='desc', limit=10, page=1)

Returns a list of federal_accounts by bureau for the agency in a single fiscal year.

Parameters:

• toptier_agency_code (str) – A numerical code (in string form, due to the use of leading zeros) identifying the agency.

• bureau_slug (str) – The slug for the bureau.

• fiscal_year (int) – The fiscal year. Optional parameter, defaults to the current year.

• agency_type (str) – Optional. Determines if the data being returned is derived from the awarding agency or the funding agency. Defaults to awarding, but other option is funding.

• order (str) – Indicates what direction results should be sorted by. Valid options include asc for ascending order or desc for descending order (default).

• limit (int) – Optional parameter to limit number of items. Default is 10.

• page (int) – Optional pagination parameter. Default is 1.

Returns:

A dictionary containing a list of federal accounts by bureau.

Return type:

dict

get_federal_accounts_count_by_award(award_id)

Returns the number of federal accounts associated with the given award.

Parameters:

award_id (str) – Unique identifier matching the award.

Returns:

Dictionary containing the number of federal accounts associated with the given award.

Return type:

dict

get_federal_accounts_count_for_agency(toptier_agency_code, fiscal_year=2024)

Returns the count of Federal Accounts and Treasury Accounts for the agency in a single fiscal year.

Parameters:

• toptier_agency_code (str) – A numerical code (in string form, due to the use of leading zeros) identifying the agency.

• fiscal_year (int) – The fiscal year. Optional parameter, defaults to the current year.

Returns:

A dictionary containing the count of Federal Accounts and Treasury Accounts.

Return type:

dict

get_federal_accounts_for_agency(toptier_agency_code, fiscal_year=2024, Filter=None, order='desc', limit=10, page=1)

Returns a list of Federal Accounts and Treasury Accounts for the agency in a single fiscal year.

Parameters:

• toptier_agency_code (str) – A numerical code (in string form, due to the use of leading zeros) identifying the agency.

• fiscal_year (int) – The fiscal year. Optional parameter, defaults to the current year.

• Filter (str) – Optional. This will filter the Budget Function by their name to those matching the text.

• order (str) – Indicates what direction results should be sorted by. Valid options include asc for ascending order or desc for descending order (default).

• limit (int) – Optional parameter to limit number of items. Default is 10.

• page (int) – Optional pagination parameter. Default is 1.

Returns:

A dictionary containing a list of Federal Accounts and Treasury Accounts.

Return type:

dict

get_federal_accounts_receiving_def_count(def_codes)

Returns the count of Federal Accounts and TAS which received disaster/emergency funding per the requested filters.

Parameters:

def_codes (list) – A list of Disaster Emergency Fund (def) codes (strings). Possible values are L, M, N, O, P, U, and V.

Returns:

A dictionary containing the count of Federal Accounts and TAS which received disaster/emergency funding per the requested filters.

Return type:

dict

get_federal_accounts_receiving_def_funding(def_codes, spending_type='total', award_type_codes=None, limit=10, page=1, sort='id', order='desc')

Returns insights on the Federal Accounts and TAS receiving funding from disaster/emergency funding per the requested filters.

Parameters:

• def_codes (list) – A list of Disaster Emergency Fund (def) codes (strings). Possible values are L, M, N, O, P, U, and V.

• spending_type (str) – Spending type. Defaults to total, but other option is award.

• award_type_codes (list) – Optional. Only to be used if spending type is award. Possible values are 02, 03, 04, 05, 06, 07, 08, 09, 10, 11, A, B, C, D, IDV_A, IDV_B_A, IDV_B_B, IDV_B_C, IDV_B, IDV_C, IDV_D, IDV_E, and -1.

• limit (int) – Page size of results. Default is 10.

• page (int) – Pagination parameter. Defaults to first page.

• order (str) – Order of returned data. Defaults to desc (descending), with asc (ascending) as other option.

• sort (str) – Optional parameter indicating what returns values should be sorted by. Default is id, but other options are code, description, award_count, face_value_of_loan, obligation, and outlay.

Returns:

A dictionary containing insights on the Federal Accounts and TAS receiving funding from disaster/emergency funding per the requested filters.

Return type:

dict

get_federal_accounts_under_idv(award_id, page=1, limit=10, order='desc', sort='total_transaction_obligated_amount')

Returns a list of federal accounts under a given IDV.

Parameters:

• award_id (str) – IDV (Indefinite Delivery Vehicle) to return accounts for.

• page (int) – Pagination parameter. Defaults to first page.

• limit (int) – Optional. Number of items to return. Default is 10.

• order (str) – Order in which to return data. Default is desc, and other option is asc.

• sort (str) – Sorting parameter. Default is total_transaction_obligated_amount, but other options are federal_account, agency, and account_title.

Returns:

A dictionary containing a list of federal accounts.

Return type:

dict

get_filter_hash_for_url(filters)

Returns a hash for URL, based on selected filter criteria.

Parameters:

filters (dict) – Advanced JSON filtering object. See this endpoint’s docs for information on the format of this filtering object.

Returns:

A dictionary containing a hash.

Return type:

dict

get_filter_object_from_hash(Hash)

Accepts a hash generated by /api/v2/references/filter/ and returns an Advanced Search filter object.

Parameters:

hash (str) – A hash.

Returns:

A dictionary containing a filter object.

Return type:

dict

get_financial_balances(fiscal_year, funding_agency_id)

Returns aggregated balances for a specific government agency in a given fiscal year.

Parameters:

• fiscal_year (int) – The desired fiscal year.

• funding_agency_id (int) – The unique USAspending.gov agency identifier. This ID is the agency_id value returned in the /api/v2/references/toptier_agencies/ endpoint.

Returns:

A dictionary containing financial balance data.

Return type:

dict

get_financial_spending_by_object_class(fiscal_year, funding_agency_id)

Returns the total amount that a specific agency has obligated to major object classes in a given fiscal year.

Parameters:

• fiscal_year (int) – The desired fiscal year.

• funding_agency_id (int) – The unique USAspending.gov agency identifier. This ID is the agency_id value returned in the /api/v2/references/toptier_agencies/ endpoint.

Returns:

A dictionary containing financial spending data.

Return type:

dict

get_financial_spending_for_minor_object_class(fiscal_year, funding_agency_id, major_object_class_code)

Returns the total amount that a specific agency has obligated to minor object classes within a specific major object class in a given fiscal year.

Parameters:

• fiscal_year (int) – The desired fiscal year.

• funding_agency_id (int) – The unique USAspending.gov agency identifier. This ID is the agency_id value returned in the /api/v2/references/toptier_agencies/ endpoint.

• major_object_class_code (int) – The major object class code returned in /api/v2/financial_spending/major_object_class/.

Returns:

A dictionary containing financial spending data.

Return type:

dict

get_fiscal_year_snapshot_for_federal_account(federal_account_id, fiscal_year=2024)

Returns budget information for a federal account for the year provided based on account’s internal ID.

Parameters:

• federal_account_id (int) – Database id for a federal account.

• fiscal_year (int) – The fiscal year. Defaults to the current year.

Returns:

A dictionary containing budget information for a federal account for the year provided based on account’s internal ID

Return type:

dict

get_glossary(page=1, limit=10)

Returns a list of glossary data.

Parameters:

• page (int) – Pagination parameter. Defaults to first page.

• limit (int) – Number of items per page. Defaults to 10.

Returns:

A dictionary containing a list of glossary data.

Return type:

dict

get_idv_activity(award_id, page=1, limit=10, hide_edge_cases='false')

Returns a list of child and grandchild awards for a given IDV.

Parameters:

• award_id (str) – IDV (Indefinite Delivery Vehicle) to return accounts for.

• page (int) – Pagination parameter. Defaults to first page.

• limit (int) – Optional. Number of items to return. Default is 10.

• hide_edge_cases (str) – Choose whether or not to hide awards that have no/negative obligated amounts and/or no/negative awarded amounts and/or no end date. Default is false and true is other option.

Returns:

A dictionary containing a list of awards.

Return type:

dict

get_idv_amounts(award_id)

Returns aggregated award counts and funding amounts for IDV contracts.

Parameters:

award_id (str) – Either a “generated” natural award id (string) or a database surrogate award id (number). Generated award identifiers are preferred as they are effectively permanent. Surrogate award ids are retained for backward compatibility but are deprecated.

Returns:

A dictionary containing a list of award coints and funding amounts.

Return type:

dict

get_idv_awards(award_id, Type='child_idvs', page=1, limit=10, order='desc', sort='period_of_performance_start_date')

Returns a list of child IDVs, child awards, or grandchild awards for IDV.

Parameters:

• award_id (str) – Either a “generated” natural award id (string) or a database surrogate award id (number). Generated award identifiers are preferred as they are effectively permanent. Surrogate award ids are retained for backward compatibility but are deprecated.

• type (str) – The type of related awards to return. Default is child_idvs, but other options are child_awards and grandchild_awards.

• page (int) – Pagination parameter. Defaults to first page.

• limit (int) – Optional. Number of items to return. Default is 10.

• order (str) – Order in which to return data. Default is desc, and other option is asc.

• sort (str) – Sorting parameter. Default is period_of_performance_start_date, but other options are piid, description, period_of_performance_current_end_date, last_date_to_order, funding_agency, awarding_agency, award_type, and obligated_amount.

Returns:

A dictionary containing a list of idv award data.

Return type:

dict

get_idv_federal_account_count(award_id, piid=None)

Returns the number of federal accounts associated with the given IDV and it’s children and grandchildren.

Parameters:

• award_id (str) – Either a “generated” natural award id (string) or a database surrogate award id (number). Generated award identifiers are preferred as they are effectively permanent. Surrogate award ids are retained for backward compatibility but are deprecated.

• piid (str) – Optional. Award ID to further refine results. All File C financial data for this award is returned if omitted. Defaults to None.

Returns:

A dictionary containing a federal account count.

Return type:

dict

get_idv_funding(award_id, piid=None, page=1, limit=10, order='desc', sort='reporting_fiscal_date')

Returns a list of File C financial data for an IDV award’s descendant contracts.

Parameters:

• award_id (str) – Either a “generated” natural award id (string) or a database surrogate award id (number). Generated award identifiers are preferred as they are effectively permanent. Surrogate award ids are retained for backward compatibility but are deprecated.

• piid (str) – Optional. Award ID to further refine results. All File C financial data for this award is returned if omitted. Defaults to None.

• page (int) – Pagination parameter. Defaults to first page.

• limit (int) – Optional. Number of items to return. Default is 10.

• order (str) – Order in which to return data. Default is desc, and other option is asc.

• sort (str) – Sorting parameter. Default is reporting_fiscal_date, but other options are account_title, disaster_emergency_fund_code, gross_outlay_amount, object_class, piid, program_activity, reporting_agency_name, and transaction_obligated_amount.

Returns:

A dictionary containing a list of financial data.

Return type:

dict

get_idv_funding_totals(award_id)

Returns award metadata summing the total transaction obligations and counting awarding agencies, funding agencies, and federal accounts for an IDV’s children and grandchildren.

Parameters:

award_id (str) – Either a “generated” natural award id (string) or a database surrogate award id (number). Generated award identifiers are preferred as they are effectively permanent. Surrogate award ids are retained for backward compatibility but are deprecated.

Returns:

A dictionary containing award metadata.

Return type:

dict

get_naics_codes(Filter=None)

Returns a list of Tier 1 NAICS codes, their descriptions, and a count of their Tier 3 grandchildren. If filter is provided then return parents/grandparents that match the search text.

Parameters:

Filter (str) – Optional. This will filter the NAICS by their descriptions to those matching the text. Default is None.

Returns:

A dictionary containing a list of naics codes.

Return type:

dict

get_new_awards_count_for_agency(toptier_agency_code, fiscal_year=2024, agency_type='awarding')

Returns a count of New Awards for the agency in a single fiscal year.

Parameters:

• toptier_agency_code (str) – A numerical code (in string form, due to the use of leading zeros) identifying the agency.

• fiscal_year (int) – The fiscal year. Optional parameter, defaults to the current year.

• agency_type (str) – Optional. Determines if the data being returned is derived from the awarding agency or the funding agency. Defaults to awarding, but other option is funding.

Returns:

A dictionary containing the count.

Return type:

dict

get_new_awards_over_time(start_date, end_date, recipient_id, group='quarter')

Returns the count of new awards grouped by time period in ascending order (earliest to most recent).

Parameters:

• start_date (str) – (YYYY-MM-DD) Currently limited to an earliest date of 2007-10-01 (FY2008). For data going back to 2000-10-01 (FY2001), use either the Custom Award Download feature on the website or one of our download or bulk_download API endpoints.

• end_date (str) – (YYYY-MM-DD) Currently limited to an earliest date of 2007-10-01 (FY2008). For data going back to 2000-10-01 (FY2001), use either the Custom Award Download feature on the website or one of our download or bulk_download API endpoints.

• recipient_id (str) – Optional. A hash of recipient UEI, DUNS, name, and level. A unique identifier for recipients. Defaults to None.

• group (str) – How to group the data. Default is quarter, but other options are fiscal_year and month.

Returns:

A dictionary containing a count of new awards.

Return type:

dict

get_object_classes_count_for_agency(toptier_agency_code, fiscal_year=2024)

Returns the count of Object Classes for the agency in a single fiscal year.

Parameters:

• toptier_agency_code (str) – A numerical code (in string form, due to the use of leading zeros) identifying the agency.

• fiscal_year (int) – The fiscal year. Optional parameter, defaults to the current year.

Returns:

A dictionary containing the count of Object Classes.

Return type:

dict

get_object_classes_for_agency(toptier_agency_code, fiscal_year=2024, Filter=None, order='desc', limit=10, page=1)

Returns a list of Object Classes for the agency in a single fiscal year.

Parameters:

• toptier_agency_code (str) – A numerical code (in string form, due to the use of leading zeros) identifying the agency.

• fiscal_year (int) – The fiscal year. Optional parameter, defaults to the current year.

• Filter (str) – Optional. This will filter the Budget Function by their name to those matching the text.

• order (str) – Indicates what direction results should be sorted by. Valid options include asc for ascending order or desc for descending order (default).

• limit (int) – Optional parameter to limit number of items. Default is 10.

• page (int) – Optional pagination parameter. Default is 1.

Returns:

A dictionary containing a list of Objects Classes.

Return type:

dict

get_object_classes_for_tas(tas, fiscal_year=2024, Filter=None, order='desc', limit=10, page=1)

Returns a list of Object Classes for the specified Treasury Account Symbol (tas).

Parameters:

• tas (str) – The treasury account symbol (tas) of a treasury account. This endpoint supports TAS codes with 0 or 1 slashes in the code.

• fiscal_year (int) – The fiscal year. Optional parameter, defaults to the current year.

• Filter (str) – Optional. This will filter the Budget Function by their name to those matching the text.

• order (str) – Indicates what direction results should be sorted by. Valid options include asc for ascending order or desc for descending order (default).

• limit (int) – Optional parameter to limit number of items. Default is 10.

• page (int) – Optional pagination parameter. Default is 1.

Returns:

A dictionary containing a list of Object Classes.

Return type:

dict

get_object_classes_receiving_def_count(def_codes)

Returns the count of Object Classes which received disaster/emergency funding per the requested filters.

Parameters:

def_codes (list) – A list of Disaster Emergency Fund (def) codes (strings). Possible values are L, M, N, O, P, U, and V.

Returns:

A dictionary containing the count of Object Classes which received disaster/emergency funding per the requested filters.

Return type:

dict

get_object_classes_receiving_def_funding(def_codes, spending_type='total', award_type_codes=None, limit=10, page=1, sort='id', order='desc')

Returns insights on the Object Classes receiving funding from disaster/emergency funding per the requested filters.

Parameters:

• def_codes (list) – A list of Disaster Emergency Fund (def) codes (strings). Possible values are L, M, N, O, P, U, and V.

• spending_type (str) – Spending type. Defaults to total, but other option is award.

• award_type_codes (list) – Optional. Only to be used if spending type is award. Possible values are 02, 03, 04, 05, 06, 07, 08, 09, 10, 11, A, B, C, D, IDV_A, IDV_B_A, IDV_B_B, IDV_B_C, IDV_B, IDV_C, IDV_D, IDV_E, and -1.

• limit (int) – Page size of results. Default is 10.

• page (int) – Pagination parameter. Defaults to first page.

• order (str) – Order of returned data. Defaults to desc (descending), with asc (ascending) as other option.

• sort (str) – Optional parameter indicating what returns values should be sorted by. Default is id, but other options are code, description, award_count, face_value_of_loan, obligation, and outlay.

Returns:

A dictionary containing insights on the Object Classes receiving funding from disaster/emergency funding per the requested filters.

Return type:

dict

get_obligation_difference_data(toptier_code, fiscal_year, fiscal_period, page=1, limit=10, order='desc', sort='tas')

Returns an overview of government agency obligation differences data.

Parameters:

• toptier_code (str) – The specific agency code.

• fiscal_year (int) – The fiscal year.

• fiscal_period (int) – The fiscal period. Valid values: 2-12 (2 = November … 12 = September) For retriving quarterly data, provide the period which equals ‘quarter * 3’ (e.g. Q2 = P6).

• page (int) – Optional pagination parameter. Defaults to first page.

• limit (int) – Number of results per page. Defaults to 10.

• order (str) – The direction (asc or desc) that the sort field will be sorted in. Default is desc.

• sort (str) – A data field that will be used to sort the response array. Default is tas, but other options are difference, file_a_obligation, and file_b_obligation.

Returns:

A dictionary containing an overview of government agency obligation differences data.

Return type:

dict

get_obligations_by_award_category_for_agency(toptier_agency_code, fiscal_year=2024)

Returns a breakdown of obligations by award category within a single fiscal year.

Parameters:

• toptier_agency_code (str) – A numerical code (in string form, due to the use of leading zeros) identifying the agency.

• fiscal_year (int) – The fiscal year. Optional parameter, defaults to the current year.

Returns:

A dictionary containing a breakdown of obligations by award category.

Return type:

dict

get_program_activities_for_tas(tas, fiscal_year=2024, Filter=None, order='desc', limit=10, page=1)

Returns a list of Program Activities for the specified Treasury Account Symbol (tas).

Parameters:

• tas (str) – The treasury account symbol (tas) of a treasury account. This endpoint supports TAS codes with 0 or 1 slashes in the code.

• fiscal_year (int) – The fiscal year. Optional parameter, defaults to the current year.

• Filter (str) – Optional. This will filter the Budget Function by their name to those matching the text.

• order (str) – Indicates what direction results should be sorted by. Valid options include asc for ascending order or desc for descending order (default).

• limit (int) – Optional parameter to limit number of items. Default is 10.

• page (int) – Optional pagination parameter. Default is 1.

Returns:

A dictionary containing a list of Program Activities.

Return type:

dict

get_program_activity_count_for_agency(toptier_agency_code, fiscal_year=2024)

Returns the count of Program Activity categories for the agency in a single fiscal year.

Parameters:

• toptier_agency_code (str) – A numerical code (in string form, due to the use of leading zeros) identifying the agency.

• fiscal_year (int) – The fiscal year. Optional parameter, defaults to the current year.

Returns:

A dictionary containing the count of Program Activity categories.

Return type:

dict

get_program_activity_for_agency(toptier_agency_code, fiscal_year=2024, Filter=None, order='desc', limit=10, page=1)

Returns a list of Program Activity categories for the agency in a single fiscal year.

Parameters:

• toptier_agency_code (str) – A numerical code (in string form, due to the use of leading zeros) identifying the agency.

• fiscal_year (int) – The fiscal year. Optional parameter, defaults to the current year.

• Filter (str) – Optional. This will filter the Budget Function by their name to those matching the text.

• order (str) – Indicates what direction results should be sorted by. Valid options include asc for ascending order or desc for descending order (default).

• limit (int) – Optional parameter to limit number of items. Default is 10.

• page (int) – Optional pagination parameter. Default is 1.

Returns:

A dictionary containing a list of Program Activity categories.

Return type:

dict

get_psc_search_tree_nodes(depth=0, Filter=None)

Returns the basic groupings of Product Service Codes.

Parameters:

• depth (int) – Defines how many levels of descendants to return under each node. For example, depth=0 will return a flat array, while depth=2 will populate the children array of each top level node with that node’s children and grandchildren. The actual depth of each tree may be less than the value of depth if returned nodes have no children. Negative values are treated as infinite, returning all descendants. Default is 0.

• Filter (str) – Restricts results to nodes with a id or description matching the filter string. If depth is greater than zero, nodes will also appear the response if at least one child within depth matches the filter. Default is None.

Returns:

A dictionary containing the basic groupings of the psc codes.

Return type:

dict

get_recipient_award_spending(awarding_agency_id, fiscal_year, limit=10, page=1)

Returns all award spending by recipient for a given agency id and fiscal year.

Parameters:

• awarding_agency_id (int) – Internal award id of the recipient.

• fiscal_year (int) – The fiscal year for the search.

• limit (int) – Number of items to return. Defaults to 10.

• page (int) – Pagination parameter. Defaults to first page.

Returns:

Dictionary containing all award spending by recipient.

Return type:

dict

get_recipient_count(keyword=None, award_type='all')

Returns the count of recipients given an award_type and keyword string.

Parameters:

• keyword (str) – The keyword results are filtered by. Searches on name, UEI, or DUNS.

• award_type (str) – The award type results are filtered by. Default is all, but other options are contracts, grants, loans, direct_payments, and other_financial_assistance.

Returns:

A dictionary containing a count of recipients.

Return type:

dict

get_recipient_overview(recipient_id, year='latest')

Returns a high-level overview of a specific recipient, given its id.

Parameters:

• recipient_id (str) – A unique identifier for the recipient at a specific level (parent, child, or neither).

• year (str) – The fiscal year you would like data for. Use all to view all time or latest to view the latest 12 months. Default is latest.

Returns:

A dictionary containing an overview of recipient.

Return type:

dict

get_recipients_receiving_def_count(def_codes, award_type_codes=None)

Returns the count of Recipients which received disaster/emergency funding per the requested filters.

Parameters:

• def_codes (list) – A list of Disaster Emergency Fund (def) codes (strings). Possible values are L, M, N, O, P, U, and V.

• award_type_codes (list) – Optional. Only to be used if spending type is award. Possible values are 02, 03, 04, 05, 06, 07, 08, 09, 10, 11, A, B, C, D, IDV_A, IDV_B_A, IDV_B_B, IDV_B_C, IDV_B, IDV_C, IDV_D, IDV_E, and -1.

Returns:

A dictionary containing the count of Recipients which received disaster/emergency funding per the requested filters.

Return type:

dict

get_recipients_receiving_def_funding(def_codes, spending_type='total', award_type_codes=None, limit=10, page=1, sort='id', order='desc')

Returns insights on the recipients receiving funding from disaster/emergency funding per the requested filters.

Parameters:

• def_codes (list) – A list of Disaster Emergency Fund (def) codes (strings). Possible values are L, M, N, O, P, U, and V.

• spending_type (str) – Spending type. Defaults to total, but other option is award.

• award_type_codes (list) – Optional. Only to be used if spending type is award. Possible values are 02, 03, 04, 05, 06, 07, 08, 09, 10, 11, A, B, C, D, IDV_A, IDV_B_A, IDV_B_B, IDV_B_C, IDV_B, IDV_C, IDV_D, IDV_E, and -1.

• limit (int) – Page size of results. Default is 10.

• page (int) – Pagination parameter. Defaults to first page.

• order (str) – Order of returned data. Defaults to desc (descending), with asc (ascending) as other option.

• sort (str) – Optional parameter indicating what returns values should be sorted by. Default is id, but other options are code, description, award_count, face_value_of_loan, obligation, and outlay.

Returns:

A dictionary containing insights on the recipients receiving funding from disaster/emergency funding per the requested filters.

Return type:

dict

get_reporting_publishing_dates_for_single_agency(toptier_code, fiscal_year, fiscal_period)

Returns the history of publication and certification dates for a single agency’s submission.

Parameters:

• toptier_code (str) – The specific agency’s toptier code.

• fiscal_year (int) – The fiscal year of the submission.

• fiscal_period (int) – The fiscal period of the submission. valid values: 2-12 (2 = November … 12 = September) For retriving quarterly submissions, provide the period which equals ‘quarter * 3’ (e.g. Q2 = P6).

Returns:

A dictionary containing a publishing and certification data for a single agency.

Return type:

dict

get_spending_by_award(filters, fields, limit=10, order='desc', page=1, sort=None, subawards=False, last_record_unique_id=None, last_record_sort_value=None)

Returns the fields of the filtered awards.

Parameters:

• filters (dict) – An advanced JSON search object. See this endpoint’s docs for the format of this object.

• fields (list) – Spending by award fields to return. See this endpoint’s docs for the available fields.

• limit (int) – Number of items to return. Default is 10.

• order (str) – Indicates what direction results should be sorted by. Valid options include asc for ascending order or desc for descending order. Default is desc and other option is asc.

• page (int) – Pagination parameter. Defaults to first page.

• sort (str) – Optional parameter indicating what value results should be sorted by. Valid options are any of the fields in the JSON objects in the response. Defaults to the first field provided, but here it defaults to None.

• subawards (bool) – True when you want to group by Subawards instead of Awards. Defaulted to False.

• last_record_unique_id (int) – Optional. The unique id of the last record in the results set. Used in the experimental Elasticsearch API functionality. Defaults to None.

• last_record_sort_value (str) – Optional. The value of the last record that is being sorted on. Used in the experimental Elasticsearch API functionality. Defaults to None.

Returns:

A dictionary containing the fields of the filtered awards.

Return type:

dict

get_spending_by_award_count(filters, subawards=False)

Returns the number of awards in each award type (Contracts, Loans, Direct Payments, Grants, Other and IDVs).

Parameters:

• filters (dict) – An advanced JSON search object. See this endpoint’s docs for the format of this object.

• subawards (bool) – True when you want to group by Subawards instead of Awards. Defaulted to False.

Returns:

A dictionary containing a number of awards.

Return type:

dict

get_spending_by_awarding_agency(filters, limit=10, page=1, subawards=False)

Returns a list of the top results of Awarding Agencies sorted by the total amounts in descending order.

Parameters:

• filters (dict) – An advanced JSON search object. See this endpoint’s docs for the format of this object.

• limit (int) – Number of items to return. Default is 10.

• page (int) – Pagination parameter. Defaults to first page.

• subawards (bool) – True when you want to group by Subawards instead of Awards. Defaulted to False.

Returns:

A dictionary containing a list of the top results of Awarding Agencies sorted by the total amounts in descending order.

Return type:

dict

get_spending_by_awarding_subagency(filters, limit=10, page=1, subawards=False)

Returns a list of the top results of Awarding Subagencies sorted by the total amounts in descending order.

Parameters:

• filters (dict) – An advanced JSON search object. See this endpoint’s docs for the format of this object.

• limit (int) – Number of items to return. Default is 10.

• page (int) – Pagination parameter. Defaults to first page.

• subawards (bool) – True when you want to group by Subawards instead of Awards. Defaulted to False.

Returns:

A dictionary containing a list of the top results of Awarding Subagencies sorted by the total amounts in descending order.

Return type:

dict

get_spending_by_cfda(filters, limit=10, page=1, subawards=False)

Returns a list of the top results of CFDA sorted by the total amounts in descending order.

Parameters:

• filters (dict) – An advanced JSON search object. See this endpoint’s docs for the format of this object.

• limit (int) – Number of items to return. Default is 10.

• page (int) – Pagination parameter. Defaults to first page.

• subawards (bool) – True when you want to group by Subawards instead of Awards. Defaulted to False.

Returns:

A dictionary containing a list of the top results of CFDA sorted by the total amounts in descending order.

Return type:

dict

get_spending_by_country(filters, limit=10, page=1, subawards=False)

Returns a list of the top results of Countries sorted by the total amounts in descending order.

Parameters:

• filters (dict) – An advanced JSON search object. See this endpoint’s docs for the format of this object.

• limit (int) – Number of items to return. Default is 10.

• page (int) – Pagination parameter. Defaults to first page.

• subawards (bool) – True when you want to group by Subawards instead of Awards. Defaulted to False.

Returns:

A dictionary containing a list of the top results of Countries sorted by the total amounts in descending order.

Return type:

dict

get_spending_by_county(filters, limit=10, page=1, subawards=False)

Returns a list of the top results of Counties sorted by the total amounts in descending order.

Parameters:

• filters (dict) – An advanced JSON search object. See this endpoint’s docs for the format of this object.

• limit (int) – Number of items to return. Default is 10.

• page (int) – Pagination parameter. Defaults to first page.

• subawards (bool) – True when you want to group by Subawards instead of Awards. Defaulted to False.

Returns:

A dictionary containing a list of the top results of Counties sorted by the total amounts in descending order.

Return type:

dict

get_spending_by_district(filters, limit=10, page=1, subawards=False)

Returns a list of the top results of Congressional Districts sorted by the total amounts in descending order.

Parameters:

• filters (dict) – An advanced JSON search object. See this endpoint’s docs for the format of this object.

• limit (int) – Number of items to return. Default is 10.

• page (int) – Pagination parameter. Defaults to first page.

• subawards (bool) – True when you want to group by Subawards instead of Awards. Defaulted to False.

Returns:

A dictionary containing a list of the top results of Congressional Districts sorted by the total amounts in descending order.

Return type:

dict

get_spending_by_federal_account(filters, limit=10, page=1, subawards=False)

Returns a list of the top results of Federal Accounts sorted by the total amounts in descending order.

Parameters:

• filters (dict) – An advanced JSON search object. See this endpoint’s docs for the format of this object.

• limit (int) – Number of items to return. Default is 10.

• page (int) – Pagination parameter. Defaults to first page.

• subawards (bool) – True when you want to group by Subawards instead of Awards. Defaulted to False.

Returns:

A dictionary containing a list of the top results of Federal Accounts sorted by the total amounts in descending order.

Return type:

dict

get_spending_by_funding_agency(filters, limit=10, page=1, subawards=False)

Returns a list of the top results of Funding Agencies sorted by the total amounts in descending order.

Parameters:

• filters (dict) – An advanced JSON search object. See this endpoint’s docs for the format of this object.

• limit (int) – Number of items to return. Default is 10.

• page (int) – Pagination parameter. Defaults to first page.

• subawards (bool) – True when you want to group by Subawards instead of Awards. Defaulted to False.

Returns:

A dictionary containing a list of the top results of Funding Agencies sorted by the total amounts in descending order.

Return type:

dict

get_spending_by_funding_subagency(filters, limit=10, page=1, subawards=False)

Returns a list of the top results of Funding Subagencies sorted by the total amounts in descending order.

Parameters:

• filters (dict) – An advanced JSON search object. See this endpoint’s docs for the format of this object.

• limit (int) – Number of items to return. Default is 10.

• page (int) – Pagination parameter. Defaults to first page.

• subawards (bool) – True when you want to group by Subawards instead of Awards. Defaulted to False.

Returns:

A dictionary containing a list of the top results of Funding Subagencies sorted by the total amounts in descending order.

Return type:

dict

get_spending_by_geography(filters, scope, geo_layer, geo_layer_filters=None, subawards=False)

Returns aggregated obligation amounts in different geographic areas.

Parameters:

• filters (dict) – An advanced JSON search object. See this endpoint’s docs for the format of this object.

• scope (str) – When fetching transactions, use the primary place of performance or recipient location. Options are place_of_performance and recipient_location.

• geo_layer (str) – Set the type of areas in the response. Options are state, county, district, and country.

• geo_layer_filters (list) – Optional. List of U.S. state codes, U.S. county codes, U.S. Congressional districts, or ISO 3166-1 alpha-3 country codes to show results for.

• subawards (bool) – True when you want to group by Subawards instead of Awards. Defaulted to False.

Returns:

A dictionary containing aggregated obligation amounts in different geographic areas.

Return type:

dict

get_spending_by_naics(filters, limit=10, page=1, subawards=False)

Returns a list of the top results of NAICS sorted by the total amounts in descending order.

Parameters:

• filters (dict) – An advanced JSON search object. See this endpoint’s docs for the format of this object.

• limit (int) – Number of items to return. Default is 10.

• page (int) – Pagination parameter. Defaults to first page.

• subawards (bool) – True when you want to group by Subawards instead of Awards. Defaulted to False.

Returns:

A dictionary containing a list of the top results of NAICS sorted by the total amounts in descending order.

Return type:

dict

get_spending_by_psc(filters, limit=10, page=1, subawards=False)

Returns a list of the top results of PSC sorted by the total amounts in descending order.

Parameters:

• filters (dict) – An advanced JSON search object. See this endpoint’s docs for the format of this object.

• limit (int) – Number of items to return. Default is 10.

• page (int) – Pagination parameter. Defaults to first page.

• subawards (bool) – True when you want to group by Subawards instead of Awards. Defaulted to False.

Returns:

A dictionary containing a list of the top results of PSC sorted by the total amounts in descending order.

Return type:

dict

get_spending_by_state_territory(filters, limit=10, page=1, subawards=False)

Returns a list of the top results of State Territories sorted by the total amounts in descending order.

Parameters:

• filters (dict) – An advanced JSON search object. See this endpoint’s docs for the format of this object.

• limit (int) – Number of items to return. Default is 10.

• page (int) – Pagination parameter. Defaults to first page.

• subawards (bool) – True when you want to group by Subawards instead of Awards. Defaulted to False.

Returns:

A dictionary containing a list of the top results of State Territories sorted by the total amounts in descending order.

Return type:

dict

get_spending_by_transaction(filters, fields, limit=10, page=1, sort='Transaction Amount', order='desc')

Returns transaction records which match the provided filters.

Parameters:

• filters (dict) – An advanced JSON search object. See this endpoint’s docs for the format of this object.

• fields (list) – The field names to include in the response.

• limit (int) – The number of results per page. Default is 10.

• page (int) – Pagination parameter. Defaults to first page.

• sort (str) – The field on which to order results in the response. Default is “Transaction Amount”

• order (str) – The direction in which to order results. asc for ascending or desc for descending. Default is desc.

Returns:

A dictionary containing transaction records which match the provided filters.

Return type:

dict

get_spending_by_transaction_count(filters)

Returns counts of transaction records which match the provided filters.

Parameters:

filters (dict) – An advanced JSON search object. See this endpoint’s docs for the format of this object.

Returns:

A dictionary containing counts transaction records which match the provided filters.

Return type:

dict

get_spending_data_by_object_class(federal_account_id)

Returns object classes that the specified federal account has allotted money toward.

Parameters:

federal_account_id (int) – Database id for a federal account.

Returns:

A dictionary containing the data matching the parameter.

Return type:

dict

get_spending_over_time(filters, group='fiscal_year', subawards=False)

Returns a list of aggregated award amounts grouped by time period in ascending order (earliest to most recent).

Parameters:

• filters (dict) – An advanced JSON search object. See this endpoint’s docs for the format of this object.

• group (str) – Default is fiscal_year, and other options are quarter and month.

• subawards (bool) – True when you want to group by Subawards instead of Awards. Defaulted to False.

Returns:

A dictionary containing a list of aggregated award amounts grouped by time period in ascending order (earliest to most recent).

Return type:

dict

get_state_award_breakdown(fips, year='latest')

Returns the award amounts and totals, based on award type, of a specific state or territory, given its USAspending.gov id.

Parameters:

• fips (str) – The FIPS code for the state you want to view. You must include leading zeros.

• year (str) – The fiscal year you would like data for. Use all to view all time or latest to view the latest 12 months. Default is latest.

Returns:

A dictionary containing amounts and totals of a state.

Return type:

dict

get_state_metadata(fips, year='latest')

Returns a high-level overview of a specific state or territory, given its USAspending.gov id.

Parameters:

• fips (str) – The FIPS code for the state you want to view. You must include leading zeros.

• year (str) – The fiscal year you would like data for. Use all to view all time or latest to view the latest 12 months. Default is latest.

Returns:

A dictionary containing state metadata.

Return type:

dict

get_states()

Returns a list of states and their amounts.

Parameters:

None –

Returns:

A dictionary containing a list of states.

Return type:

dict

get_sub_agencies_for_agency(toptier_agency_code, fiscal_year=2024, agency_type='awarding', order='desc', limit=10, page=1)

Returns a list of sub-agencies and offices with obligated amounts, transaction counts and new award counts for the agency in a single fiscal year.

Parameters:

• toptier_agency_code (str) – A numerical code (in string form, due to the use of leading zeros) identifying the agency.

• fiscal_year (int) – The fiscal year. Optional parameter, defaults to the current year.

• agency_type (str) – Optional. Determines if the data being returned is derived from the awarding agency or the funding agency. Defaults to awarding, but other option is funding.

• order (str) – Indicates what direction results should be sorted by. Valid options include asc for ascending order or desc for descending order (default).

• limit (int) – Optional parameter to limit number of items. Default is 10.

• page (int) – Optional pagination parameter. Default is 1.

Returns:

A dictionary containing a list of sub-agencies and offices.

Return type:

dict

get_sub_agency_count_for_agency(toptier_agency_code, fiscal_year=2024, agency_type='awarding')

Returns the number of sub-agencies and offices for the agency in a single fiscal year.

Parameters:

• toptier_agency_code (str) – A numerical code (in string form, due to the use of leading zeros) identifying the agency.

• fiscal_year (int) – The fiscal year. Optional parameter, defaults to the current year.

• agency_type (str) – Optional. Determines if the data being returned is derived from the awarding agency or the funding agency. Defaults to awarding, but other option is funding.

Returns:

A dictionary containing a number of sub-agencies and offices.

Return type:

dict

get_subawards(sort, page=1, limit=10, order='desc', award_id=None)

Returns a filtered set of subawards.

Parameters:

• sort (str) – Required sorting parameter. Options are subaward_number, id, description, action_date, amount, recipient_name.

• page (int) – Pagination parameter. Defaults to first page.

• limit (int) – Number of items per page. Default is 10.

• order (str) – Ordering parameter. Default is desc (descending) and other option is asc (ascending).

• award_id (str) – Optional. Either a “generated” natural award id (string) or a database surrogate award id (number). Generated award identifiers are preferred as they are effectively permanent. Surrogate award ids are retained for backward compatibility but are deprecated.

Returns:

A dictionary containing a filtered set of subawards.

Return type:

dict

get_subawards_for_award(award_id)

Returns the number of subawards associated with the given award.

Parameters:

award_id (str) – Unique identifier matching the award.

Returns:

Dictionary containing the number of subawards associated with the given award.

Return type:

dict

get_subcomponents_for_agency(toptier_agency_code, fiscal_year=2024, agency_type='awarding', order='desc', limit=10, page=1)

Returns a list of Sub-Components in the Agency’s appropriations for a single fiscal year.

Parameters:

• toptier_agency_code (str) – A numerical code (in string form, due to the use of leading zeros) identifying the agency.

• fiscal_year (int) – The fiscal year. Optional parameter, defaults to the current year.

• agency_type (str) – Optional. Determines if the data being returned is derived from the awarding agency or the funding agency. Defaults to awarding, but other option is funding.

• order (str) – Indicates what direction results should be sorted by. Valid options include asc for ascending order or desc for descending order (default).

• limit (int) – Optional parameter to limit number of items. Default is 10.

• page (int) – Optional pagination parameter. Default is 1.

Returns:

A dictionary containing a list of Sub-Components.

Return type:

dict

get_submission_periods(use_cache=False)

Returns a list of all fields in the “dabs_submission_window_schedule” table except ‘id’.

Parameters:

use_cache (bool) – Optional. Whether or not to use a cache when retrieving values. Defaults to false.

Returns:

A dictionary containing a list of all fields in the “dabs_submission_window_schedule” table except ‘id’.

Return type:

dict

get_tas_discrepancies_data(toptier_code, fiscal_year, fiscal_period, page=1, limit=10, order='desc', sort='amount')

Returns an overview of government agency TAS discrepancies data.

Parameters:

• toptier_code (str) – The specific agency code.

• fiscal_year (int) – The fiscal year.

• fiscal_period (int) – The fiscal period. Valid values: 2-12 (2 = November … 12 = September) For retriving quarterly data, provide the period which equals ‘quarter * 3’ (e.g. Q2 = P6).

• page (int) – Optional pagination parameter. Defaults to first page.

• limit (int) – Number of results per page. Defaults to 10.

• order (str) – The direction (asc or desc) that the sort field will be sorted in. Default is desc.

• sort (str) – A data field that will be used to sort the response array. Default is amount, but other option is tas.

Returns:

A dictionary containing an overview of government agency TAS discrepancies data.

Return type:

dict

get_tas_search_tree_nodes(depth=0, Filter=None)

Returns a list of toptier agencies that have at least one TAS affiliated with them.

Parameters:

• depth (int) – Defines how many levels of descendants to return under each node. For example, depth=0 will return a flat array, while depth=2 will populate the children array of each top level node with that node’s children and grandchildren. The actual depth of each tree may be less than the value of depth if returned nodes have no children. Negative values are treated as infinite, returning all descendants. Default is 0.

• Filter (str) – Restricts results to nodes with a id or description matching the filter string. If depth is greater than zero, nodes will also appear the response if at least one child within depth matches the filter. Default is None.

Returns:

A dictionary containing a list of toptier agencies.

Return type:

dict

get_toptier_agencies(sort='percentage_of_total_budget_authority', order='desc')

Returns a list of toptier agencies, their budgetary resources, and and the percent of the total government budget authority this agency accounts for.

Parameters:

• sort (str) – A data field that will be used to sort the response array. Defaults to percentage_of_total_budget_authority.

• order (str) – The direction (asc or desc) that the sort field will be sorted in. Defaults to desc.

Returns:

A dictionary containing a list of toptier agencies.

Return type:

dict

get_total_budgetary_resources(fiscal_year=None, fiscal_period=None)

Returns federal budgetary resources by fiscal year and fiscal period.

Parameters:

• fiscal_year (int) – Optional. The fiscal year to retrieve, 2017 or later. Defaults to None.

• fiscal_period (int) – Optional. The fiscal period. If this optional parameter is provided then fiscal_year is a required parameter. If fiscal_period is provided without fiscal_year, a 400 error is returned. Valid values: 2-12 (2 = November … 12 = September). For retrieving quarterly data, provide the period which equals ‘quarter * 3’ (e.g. Q2 = P6). If neither paramater is provided, the entire available history will be returned.

Returns:

A dictionary containing federal budgetary resources by fiscal year and fiscal period.

Return type:

dict

get_transaction_spending_summary(filters)

Returns the high-level aggregations of the counts and dollar amounts for all transactions which match the keyword filter.

Parameters:

filters (dict) – An advanced JSON search object. See this endpoint’s docs for the format of this object.

Returns:

A dictionary containing the high-level aggregations of the counts and dollar amounts for all transactions which match the keyword filter.

Return type:

dict

get_transactions(award_id, sort='action_date', page=1, limit=10, order='desc')

Returns a list of transactions, their amount, type, action date, action type, modification number, and description.

Parameters:

• award_id (str) – Either a “generated” natural award id (string) or a database surrogate award id (number). Generated award identifiers are preferred as they are effectively permanent. Surrogate award ids are retained for backward compatibility but are deprecated.

• sort (str) – The field results are sorted by. Default is action_date, but other options are modification_number, federal_action_obligation, face_value_loan_guarantee, original_loan_subsidy_cost, action_type_description, and description.

• page (int) – Pagination parameter. Defaults to first page.

• limit (int) – Number of items per page. Default is 10. Max is 5000.

• order (str) – Ordering parameter. Default is desc (descending) and other option is asc (ascending).

Returns:

A dictionary containing a list of transactions, their amount, type, action date, action type, modification number, and description.

Return type:

dict

get_unlinked_awards_for_agency(toptier_code, fiscal_year, fiscal_period, Type)

Returns the number of unlinked and linked awards for the agency in the provided fiscal year and period.

Parameters:

• toptier_code (str) – The specific agency’s toptier code.

• fiscal_year (int) – The fiscal year of the submission.

• fiscal_period (int) – The fiscal period of the submission. valid values: 2-12 (2 = November … 12 = September) For retriving quarterly submissions, provide the period which equals ‘quarter * 3’ (e.g. Q2 = P6).

• Type (str) – Possible vales are assistance and procurement.

Returns:

A dictionary containing number of unlinked and linked awards.

Return type:

dict

glossary_autocomplete(search_text, limit=None)

Returns glossary autocomplete data for submitted text snippet.

Parameters:

• search_text (str) – Text for search query.

• limit (int) – Optional. Maximum number of results to return. Default is None.

Returns:

A dictionary containing glossary autocomplete data.

Return type:

dict

list_agencies(agencies_type, agency=None)

Returns one of three result set flavors. For “account_agencies” requests it returns a list of all toptier agencies with at least one DABS submission. For “award_agencies” requests it returns a list of all user selectable flagged toptier agencies with at least one subtier agency. For specific agency requests it returns a list of all user selectable flagged subtier agencies.

Parameters:

• agencies_type (str) – Type of agency desired. Possible options are account_agencies and award_agencies.

• agency (int) – Agency identifier number.

Returns:

Dictionary containing a list of selected agency information.

Return type:

dict

list_monthly_files(agency, fiscal_year, file_type)

Returns a list of the current versions of generated archive files for a given fiscal year and agency.

Parameters:

• agency (str or int) – Agency database ID or all.

• fiscal_year (int) – Fiscal year.

• file_type (str) – Optional parameter for archive file type. Possible values are assistance and contracts. Defaults to None.

Returns:

Dictionary containing a list of current versions of generated archive files.

Return type:

dict

location_autocomplete(search_text, limit=10)

Returns a list of locations matching the specified search text.

Parameters:

• search_text (str) – Text for search query.

• limit (int) – Maximum number of results to return. Default is 10.

Returns:

A dictionary containing list of locations.

Return type:

dict

naics_autocomplete(search_text, limit=10)

Returns a list of naics objects matching the specified search text.

Parameters:

• search_text (str) – Text for search query.

• limit (int) – Maximum number of results to return. Default is 10.

Returns:

A dictionary containing list of naics objects.

Return type:

dict

psc_autocomplete(search_text, limit=None)

Returns a list of product or service (psc) codes matching the specified search text.

Parameters:

• search_text (str) – Text for search query.

• limit (int) – Optional. Maximum number of results to return. Default is None.

Returns:

A dictionary containing list of product or service (psc) codes.

Return type:

dict

recipient_autocomplete(search_text, limit=10, recipient_levels=None)

Returns a list of recipients matching the specified search text.

Parameters:

• search_text (str) – Text for search query.

• limit (int) – Maximum number of results to return. Default is 10, and maximum is 500.

• recipient_levels (array) – Optional. Array of strings identifying the recipient levels. Default is None.

Returns:

A dictionary containing list of recipients.

Return type:

dict

search_federal_accounts(fiscal_year='2024', agency_identifier=None, sort_direction='desc', sort_field='budgetary_resources', limit=50, page=1, keyword=None)

Returns a list of federal accounts, their number, name, managing agency, and budgetary resources matching the search parameters.

Parameters:

• fiscal_year (str) – The desired fiscal year, entered as a string. If none is given, default is previous year.

• agency_identifier (str) – Agency id. Optional. Defaults to None.

• sort_direction (str) – The direction in which to sort. Defaults to desc, but other option is asc.

• sort_field (str) – The field on which to sort. Default is budgetary_resources, but other options are account_number, account_name, and managing_agency.

• limit (int) – Number of results to include per page. Defaults to 50.

• page (int) – The page to return. Defaults to first page.

• keyword (str) – Optional search term. Default is None.

Returns:

A dictionary containing a list of federal accounts, their number, name, managing agency, and budgetary resources matching the search parameters.

Return type:

dict

search_recipients(order='desc', sort='amount', limit=50, page=1, keyword=None, award_type='all')

Returns a list of recipients, their level, DUNS, UEI, and amount.

Parameters:

• order (str) – The direction results are sorted by. asc for ascending, desc for descending. Default is desc.

• sort (str) – The field results are sorted by. Default is amount, but other values are name and duns.

• limit (int) – Number of results per page. Default is 50. Max is 1000.

• page (int) – Pagination parameter. Defaults to first page.

• keyword (str) – The keyword results are filtered by. Searches on name, UEI, or DUNS.

• award_type (str) – The award type results are filtered by. Default is all, but other options are contracts, grants, loans, direct_payments, and other_financial_assistance.

Returns:

A dictionary containing a list of recipient data.

Return type:

dict

tas_autocomplete_a(Filter, limit=10)

Returns the list of potential Availability Type Codes narrowed by other components supplied in the Treasury Account filter.

Parameters:

• Filter (dict) – The component filters to be used in the data. Each component listed may be omitted, null, or a string value. If omitted, no filtering will be performed on that component. If null, the filter will include account numbers missing that component. If a string, the filter will perform an exact match on account numbers where that component matches the string provided. Possible values are ata (optional, string, nullable) Allocation Transfer Agency Identifier (3 characters). TAS only; aid (optional, string, nullable) Agency Identifier (3 characters); bpoa (optional, string, nullable) Beginning Period of Availability (4 characters). TAS only; epoa (optional, string, nullable) Ending Period of Availability (4 characters). TAS only; a (optional, string, nullable) Availability Type Code (1 character). Will either be ‘X’ or null. TAS only; main (optional, string, nullable) Main Account Code (4 characters); and sub (optional, string, nullable) Sub Account Code (3 characters). TAS only.

• limit (int) – Optional. Maximum number of results to return. Default is 10.

Returns:

A dictionary containing list of potential Availability Type Codes.

Return type:

dict

tas_autocomplete_aid(Filter, limit=10)

Returns the list of potential Agency Identifiers narrowed by other components supplied in the Treasury Account or Federal Account filter.

Parameters:

• Filter (dict) – The component filters to be used in the data. Each component listed may be omitted, null, or a string value. If omitted, no filtering will be performed on that component. If null, the filter will include account numbers missing that component. If a string, the filter will perform an exact match on account numbers where that component matches the string provided. Possible values are ata (optional, string, nullable) Allocation Transfer Agency Identifier (3 characters). TAS only; aid (optional, string, nullable) Agency Identifier (3 characters); bpoa (optional, string, nullable) Beginning Period of Availability (4 characters). TAS only; epoa (optional, string, nullable) Ending Period of Availability (4 characters). TAS only; a (optional, string, nullable) Availability Type Code (1 character). Will either be ‘X’ or null. TAS only; main (optional, string, nullable) Main Account Code (4 characters); and sub (optional, string, nullable) Sub Account Code (3 characters). TAS only.

• limit (int) – Optional. Maximum number of results to return. Default is 10.

Returns:

A dictionary containing list of potential Agency Identifiers.

Return type:

dict

tas_autocomplete_ata(Filter, limit=10)

Returns the list of potential Allocation Transfer Agency Identifiers narrowed by other components supplied in the Treasury Account filter.

Parameters:

• Filter (dict) – The component filters to be used in the data. Each component listed may be omitted, null, or a string value. If omitted, no filtering will be performed on that component. If null, the filter will include account numbers missing that component. If a string, the filter will perform an exact match on account numbers where that component matches the string provided. Possible values are ata (optional, string, nullable) Allocation Transfer Agency Identifier (3 characters). TAS only; aid (optional, string, nullable) Agency Identifier (3 characters); bpoa (optional, string, nullable) Beginning Period of Availability (4 characters). TAS only; epoa (optional, string, nullable) Ending Period of Availability (4 characters). TAS only; a (optional, string, nullable) Availability Type Code (1 character). Will either be ‘X’ or null. TAS only; main (optional, string, nullable) Main Account Code (4 characters); and sub (optional, string, nullable) Sub Account Code (3 characters). TAS only.

• limit (int) – Optional. Maximum number of results to return. Default is 10.

Returns:

A dictionary containing list of potential Transfer Agency Identifiers.

Return type:

dict

tas_autocomplete_bpoa(Filter, limit=10)

Returns the list of potential Beginning Period of Availabilities narrowed by other components supplied in the Treasury Account filter.

Parameters:

• Filter (dict) – The component filters to be used in the data. Each component listed may be omitted, null, or a string value. If omitted, no filtering will be performed on that component. If null, the filter will include account numbers missing that component. If a string, the filter will perform an exact match on account numbers where that component matches the string provided. Possible values are ata (optional, string, nullable) Allocation Transfer Agency Identifier (3 characters). TAS only; aid (optional, string, nullable) Agency Identifier (3 characters); bpoa (optional, string, nullable) Beginning Period of Availability (4 characters). TAS only; epoa (optional, string, nullable) Ending Period of Availability (4 characters). TAS only; a (optional, string, nullable) Availability Type Code (1 character). Will either be ‘X’ or null. TAS only; main (optional, string, nullable) Main Account Code (4 characters); and sub (optional, string, nullable) Sub Account Code (3 characters). TAS only.

• limit (int) – Optional. Maximum number of results to return. Default is 10.

Returns:

A dictionary containing list of potential Beginning Period of Availabilities.

Return type:

dict

tas_autocomplete_epoa(Filter, limit=10)

Returns the list of potential Ending Period of Availabilities narrowed by other components supplied in the Treasury Account filter.

Parameters:

• Filter (dict) – The component filters to be used in the data. Each component listed may be omitted, null, or a string value. If omitted, no filtering will be performed on that component. If null, the filter will include account numbers missing that component. If a string, the filter will perform an exact match on account numbers where that component matches the string provided. Possible values are ata (optional, string, nullable) Allocation Transfer Agency Identifier (3 characters). TAS only; aid (optional, string, nullable) Agency Identifier (3 characters); bpoa (optional, string, nullable) Beginning Period of Availability (4 characters). TAS only; epoa (optional, string, nullable) Ending Period of Availability (4 characters). TAS only; a (optional, string, nullable) Availability Type Code (1 character). Will either be ‘X’ or null. TAS only; main (optional, string, nullable) Main Account Code (4 characters); and sub (optional, string, nullable) Sub Account Code (3 characters). TAS only.

• limit (int) – Optional. Maximum number of results to return. Default is 10.

Returns:

A dictionary containing list of potential Ending Period of Availabilities.

Return type:

dict

tas_autocomplete_main(Filter, limit=10)

Returns the list of potential Main Account Codes narrowed by other components supplied in the Treasury Account or Federal Account filter.

Parameters:

• Filter (dict) – The component filters to be used in the data. Each component listed may be omitted, null, or a string value. If omitted, no filtering will be performed on that component. If null, the filter will include account numbers missing that component. If a string, the filter will perform an exact match on account numbers where that component matches the string provided. Possible values are ata (optional, string, nullable) Allocation Transfer Agency Identifier (3 characters). TAS only; aid (optional, string, nullable) Agency Identifier (3 characters); bpoa (optional, string, nullable) Beginning Period of Availability (4 characters). TAS only; epoa (optional, string, nullable) Ending Period of Availability (4 characters). TAS only; a (optional, string, nullable) Availability Type Code (1 character). Will either be ‘X’ or null. TAS only; main (optional, string, nullable) Main Account Code (4 characters); and sub (optional, string, nullable) Sub Account Code (3 characters). TAS only.

• limit (int) – Optional. Maximum number of results to return. Default is 10.

Returns:

A dictionary containing list of potential Main Account Codes.

Return type:

dict

tas_autocomplete_sub(Filter, limit=10)

Returns the list of potential Sub Account Codes narrowed by other components supplied in the Treasury Account filter.

Parameters:

• Filter (dict) – The component filters to be used in the data. Each component listed may be omitted, null, or a string value. If omitted, no filtering will be performed on that component. If null, the filter will include account numbers missing that component. If a string, the filter will perform an exact match on account numbers where that component matches the string provided. Possible values are ata (optional, string, nullable) Allocation Transfer Agency Identifier (3 characters). TAS only; aid (optional, string, nullable) Agency Identifier (3 characters); bpoa (optional, string, nullable) Beginning Period of Availability (4 characters). TAS only; epoa (optional, string, nullable) Ending Period of Availability (4 characters). TAS only; a (optional, string, nullable) Availability Type Code (1 character). Will either be ‘X’ or null. TAS only; main (optional, string, nullable) Main Account Code (4 characters); and sub (optional, string, nullable) Sub Account Code (3 characters). TAS only.

• limit (int) – Optional. Maximum number of results to return. Default is 10.

Returns:

A dictionary containing list of potential Sub Account Codes.

Return type:

dict

Module contents