USAspending API ReferenceIndependent
Try the API

Advanced Search

Filter awards, transactions, and subawards, then chart and table the results.

POST24Open on usaspending.gov How Advanced Search works

Open a row for parameters and ready-to-run samples. The full reference has every field and a live console.

POSTGenerated Filter Hash for URL/api/v2/references/filter/

These endpoints support the advanced search page and allow for complex filtering for specific subsets of spending data.

filtersversion
curl -X POST 'https://api.usaspending.gov/api/v2/references/filter/' \
  -H 'Content-Type: application/json' \
  -d '{
  "filters": {
    "keyword": {},
    "timePeriodType": "fy",
    "timePeriodFY": [
      "2020"
    ],
    "timePeriodStart": null,
    "timePeriodEnd": null,
    "selectedLocations": {
      "USA_AZ": {
        "identifier": "USA_AZ",
        "filter": {
          "country": "USA",
          "state": "AZ"
        },
        "display": {
          "entity": "State",
          "standalone": "Arizona",
          "title": "Arizona"
        }
      }
    },
    "locationDomesticForeign": "all",
    "selectedFundingAgencies": {},
    "selectedAwardingAgencies": {
      "806_toptier": {
        "id": 806,
        "toptier_flag": true,
        "toptier_agency": {
          "id": 68,
          "toptier_code": "075",
          "abbreviation": "HHS",
          "name": "Department of Health and Human Services"
        },
        "subtier_agency": {
          "abbreviation": "HHS",
          "name": "Department of Health and Human Services"
        },
        "agencyType": "toptier"
      }
    },
    "selectedRecipients": [],
    "recipientDomesticForeign": "all",
    "recipientType": [],
    "selectedRecipientLocations": {},
    "awardType": [
      "IDV_D",
      "IDV_B_A",
      "IDV_E",
      "IDV_B_B",
      "IDV_B_C",
      "07",
      "08",
      "IDV_A",
      "IDV_B",
      "IDV_C"
    ],
    "selectedAwardIDs": {},
    "awardAmounts": {
      "range-1": [
        1000000,
        25000000
      ]
    },
    "selectedCFDA": {},
    "selectedNAICS": {},
    "selectedPSC": {},
    "pricingType": [],
    "setAside": [],
    "extentCompeted": [],
    "federalAccounts": {},
    "treasuryAccounts": {}
  },
  "version": "2019-07-26"
}'
Full reference and live console Contract
POSTRestore Filters From URL Hash/api/v2/references/hash/

Restores selected filter criteria, based on URL hash.

hash
curl -X POST 'https://api.usaspending.gov/api/v2/references/hash/' \
  -H 'Content-Type: application/json' \
  -d '{
  "hash": "5703c297b902ac3b76088c5c275b53f9"
}'
Full reference and live console Contract
POSTNew Awards Over Time/api/v2/search/new_awards_over_time/

This endpoint is used to power USAspending.gov's recipient profile pages.

groupfilters
curl -X POST 'https://api.usaspending.gov/api/v2/search/new_awards_over_time/' \
  -H 'Content-Type: application/json' \
  -d '{
  "group": "fiscal_year",
  "filters": {
    "recipient_id": "1c3edaaa-611b-840c-bf2b-fd34df49f21f-P",
    "time_period": [
      {
        "start_date": "2007-10-01",
        "end_date": "2020-09-30"
      }
    ]
  }
}'
Full reference and live console Contract
POSTNumber of awards for each type/api/v2/search/spending_by_award_count/

These endpoints support the advanced search page and allow for complex filtering for specific subsets of spending data.

filtersspending_levelsubawards
curl -X POST 'https://api.usaspending.gov/api/v2/search/spending_by_award_count/' \
  -H 'Content-Type: application/json' \
  -d '{
  "filters": {
    "keywords": [
      "Filter is required"
    ]
  }
}'
Full reference and live console Contract
POSTSpending by Award/api/v2/search/spending_by_award/

This endpoints supports the advanced search page and allow for complex filtering for specific subsets of spending data.

filtersfieldslimitorderpagesortsubawardslast_record_unique_idlast_record_sort_valuespending_level
curl -X POST 'https://api.usaspending.gov/api/v2/search/spending_by_award/' \
  -H 'Content-Type: application/json' \
  -d '{
  "subawards": false,
  "limit": 10,
  "page": 1,
  "filters": {
    "award_type_codes": [
      "A",
      "B",
      "C"
    ],
    "time_period": [
      {
        "start_date": "2018-10-01",
        "end_date": "2019-09-30"
      }
    ]
  },
  "fields": [
    "Award ID",
    "Recipient Name",
    "Start Date",
    "End Date",
    "Award Amount",
    "Awarding Agency",
    "Awarding Sub Agency",
    "Contract Award Type",
    "Award Type",
    "Funding Agency",
    "Funding Sub Agency"
  ]
}'
Full reference and live console Contract
POSTSpending By Category/api/v2/search/spending_by_category/

This endpoint supports the advanced search page and allow for complex filtering for specific subsets of spending data.

categoryfilterslimitpagespending_levelsubawards
curl -X POST 'https://api.usaspending.gov/api/v2/search/spending_by_category/' \
  -H 'Content-Type: application/json' \
  -d '{
  "category": "awarding_agency",
  "filters": {
    "keywords": [
      "Filter is required"
    ]
  }
}'
Full reference and live console Contract
POSTSpending By Awarding Agency/api/v2/search/spending_by_category/awarding_agency/

This endpoint supports the advanced search page and allow for complex filtering for specific subsets of spending data.

filterslimitpagespending_levelsubawards
curl -X POST 'https://api.usaspending.gov/api/v2/search/spending_by_category/awarding_agency/' \
  -H 'Content-Type: application/json' \
  -d '{
  "filters": {
    "recipient_id": "1c3edaaa-611b-840c-bf2b-fd34df49f21f-P",
    "time_period": [
      {
        "start_date": "2019-09-28",
        "end_date": "2020-09-28"
      }
    ]
  },
  "category": "awarding_agency",
  "limit": 5,
  "page": 1,
  "spending_level": "transactions"
}'
Full reference and live console Contract
POSTSpending By Awarding Subagency/api/v2/search/spending_by_category/awarding_subagency/

This endpoint supports the advanced search page and allow for complex filtering for specific subsets of spending data.

filterslimitpagespending_levelsubawards
curl -X POST 'https://api.usaspending.gov/api/v2/search/spending_by_category/awarding_subagency/' \
  -H 'Content-Type: application/json' \
  -d '{
  "filters": {
    "recipient_id": "1c3edaaa-611b-840c-bf2b-fd34df49f21f-P",
    "time_period": [
      {
        "start_date": "2019-09-28",
        "end_date": "2020-09-28"
      }
    ]
  },
  "category": "awarding_subagency",
  "limit": 5,
  "page": 1,
  "spending_level": "transactions"
}'
Full reference and live console Contract
POSTSpending By CFDA/api/v2/search/spending_by_category/cfda/

This endpoint supports the advanced search page and allow for complex filtering for specific subsets of spending data.

filterslimitpagespending_levelsubawards
curl -X POST 'https://api.usaspending.gov/api/v2/search/spending_by_category/cfda/' \
  -H 'Content-Type: application/json' \
  -d '{
  "filters": {
    "recipient_id": "1c3edaaa-611b-840c-bf2b-fd34df49f21f-P",
    "time_period": [
      {
        "start_date": "2019-09-28",
        "end_date": "2020-09-28"
      }
    ]
  },
  "category": "cfda",
  "limit": 5,
  "page": 1,
  "spending_level": "transactions"
}'
Full reference and live console Contract
POSTSpending By Country/api/v2/search/spending_by_category/country/

This endpoint supports the state profile page and allow for complex filtering for specific subsets of spending data.

filterslimitpagespending_levelsubawards
curl -X POST 'https://api.usaspending.gov/api/v2/search/spending_by_category/country/' \
  -H 'Content-Type: application/json' \
  -d '{
  "filters": {
    "recipient_id": "1c3edaaa-611b-840c-bf2b-fd34df49f21f-P",
    "time_period": [
      {
        "start_date": "2019-09-28",
        "end_date": "2020-09-28"
      }
    ]
  },
  "category": "country",
  "limit": 5,
  "page": 1,
  "spending_level": "transactions"
}'
Full reference and live console Contract
POSTSpending By County/api/v2/search/spending_by_category/county/

This endpoint supports the state profile page and allow for complex filtering for specific subsets of spending data.

filterslimitpagespending_levelsubawards
curl -X POST 'https://api.usaspending.gov/api/v2/search/spending_by_category/county/' \
  -H 'Content-Type: application/json' \
  -d '{
  "filters": {
    "recipient_id": "1c3edaaa-611b-840c-bf2b-fd34df49f21f-P",
    "time_period": [
      {
        "start_date": "2019-09-28",
        "end_date": "2020-09-28"
      }
    ]
  },
  "category": "county",
  "limit": 5,
  "page": 1,
  "spending_level": "transactions"
}'
Full reference and live console Contract
POSTSpending By DEFC/api/v2/search/spending_by_category/defc/

This endpoint supports the advanced search page and allow for complex filtering for specific subsets of spending data.

filterslimitpagespending_levelsubawards
curl -X POST 'https://api.usaspending.gov/api/v2/search/spending_by_category/defc/' \
  -H 'Content-Type: application/json' \
  -d '{
  "category": "defc",
  "filters": {
    "award_type_codes": [
      "A",
      "B",
      "C",
      "D"
    ],
    "time_period": [
      {
        "start_date": "2019-09-28",
        "end_date": "2020-09-28"
      }
    ]
  },
  "spending_level": "transactions"
}'
Full reference and live console Contract
POSTSpending By District/api/v2/search/spending_by_category/district/

This endpoint supports the state profile page and allow for complex filtering for specific subsets of spending data.

filterslimitpagespending_levelsubawards
curl -X POST 'https://api.usaspending.gov/api/v2/search/spending_by_category/district/' \
  -H 'Content-Type: application/json' \
  -d '{
  "filters": {
    "recipient_id": "1c3edaaa-611b-840c-bf2b-fd34df49f21f-P",
    "time_period": [
      {
        "start_date": "2019-09-28",
        "end_date": "2020-09-28"
      }
    ]
  },
  "category": "district",
  "limit": 5,
  "page": 1,
  "spending_level": "transactions"
}'
Full reference and live console Contract
POSTSpending By Federal Account/api/v2/search/spending_by_category/federal_account/

This endpoint supports the advanced search page and allow for complex filtering for specific subsets of spending data.

filterslimitpagespending_levelsubawards
curl -X POST 'https://api.usaspending.gov/api/v2/search/spending_by_category/federal_account/' \
  -H 'Content-Type: application/json' \
  -d '{
  "filters": {
    "recipient_id": "1c3edaaa-611b-840c-bf2b-fd34df49f21f-P",
    "time_period": [
      {
        "start_date": "2019-09-28",
        "end_date": "2020-09-28"
      }
    ]
  },
  "category": "federal_account",
  "limit": 5,
  "page": 1,
  "spending_level": "transactions"
}'
Full reference and live console Contract
POSTSpending By Funding Agency/api/v2/search/spending_by_category/funding_agency/

This endpoint supports the advanced search page and allow for complex filtering for specific subsets of spending data.

filterslimitpagespending_levelsubawards
curl -X POST 'https://api.usaspending.gov/api/v2/search/spending_by_category/funding_agency/' \
  -H 'Content-Type: application/json' \
  -d '{
  "filters": {
    "recipient_id": "1c3edaaa-611b-840c-bf2b-fd34df49f21f-P",
    "time_period": [
      {
        "start_date": "2019-09-28",
        "end_date": "2020-09-28"
      }
    ]
  },
  "category": "funding_agency",
  "limit": 5,
  "page": 1,
  "spending_level": "transactions"
}'
Full reference and live console Contract
POSTSpending By Funding Subagency/api/v2/search/spending_by_category/funding_subagency/

This endpoint supports the advanced search page and allow for complex filtering for specific subsets of spending data.

filterslimitpagespending_levelsubawards
curl -X POST 'https://api.usaspending.gov/api/v2/search/spending_by_category/funding_subagency/' \
  -H 'Content-Type: application/json' \
  -d '{
  "filters": {
    "recipient_id": "1c3edaaa-611b-840c-bf2b-fd34df49f21f-P",
    "time_period": [
      {
        "start_date": "2019-09-28",
        "end_date": "2020-09-28"
      }
    ]
  },
  "category": "funding_subagency",
  "limit": 5,
  "page": 1,
  "spending_level": "transactions"
}'
Full reference and live console Contract
POSTSpending By NAICS/api/v2/search/spending_by_category/naics/

This endpoint supports the advanced search page and allow for complex filtering for specific subsets of spending data.

filterslimitpagespending_levelsubawards
curl -X POST 'https://api.usaspending.gov/api/v2/search/spending_by_category/naics/' \
  -H 'Content-Type: application/json' \
  -d '{
  "filters": {
    "recipient_id": "1c3edaaa-611b-840c-bf2b-fd34df49f21f-P",
    "time_period": [
      {
        "start_date": "2019-09-28",
        "end_date": "2020-09-28"
      }
    ]
  },
  "category": "naics",
  "limit": 5,
  "page": 1,
  "spending_level": "transactions"
}'
Full reference and live console Contract
POSTSpending By PSC/api/v2/search/spending_by_category/psc/

This endpoint supports the advanced search page and allow for complex filtering for specific subsets of spending data.

filterslimitpagespending_levelsubawards
curl -X POST 'https://api.usaspending.gov/api/v2/search/spending_by_category/psc/' \
  -H 'Content-Type: application/json' \
  -d '{
  "filters": {
    "recipient_id": "1c3edaaa-611b-840c-bf2b-fd34df49f21f-P",
    "time_period": [
      {
        "start_date": "2019-09-28",
        "end_date": "2020-09-28"
      }
    ]
  },
  "category": "psc",
  "limit": 5,
  "page": 1,
  "spending_level": "transactions"
}'
Full reference and live console Contract
POSTSpending By Recipient DUNS/api/v2/search/spending_by_category/recipient_duns/

Deprecated: Please see the following API contract instead: usaspendingapi/apicontracts/contracts/v2/search/spendingbycategory/recipient This endpoint supports the Advanced Search page and allow for co

filterslimitpagespending_levelsubawards
curl -X POST 'https://api.usaspending.gov/api/v2/search/spending_by_category/recipient_duns/' \
  -H 'Content-Type: application/json' \
  -d '{
  "filters": {
    "recipient_id": "1c3edaaa-611b-840c-bf2b-fd34df49f21f-P",
    "time_period": [
      {
        "start_date": "2019-09-28",
        "end_date": "2020-09-28"
      }
    ]
  },
  "category": "recipient_duns",
  "limit": 5,
  "page": 1,
  "spending_level": "transactions"
}'
Full reference and live console Contract
POSTSpending By Recipient/api/v2/search/spending_by_category/recipient/

This endpoint supports the Advanced Search page and allow for complex filtering for specific subsets of spending data.

filterslimitpagespending_levelsubawards
curl -X POST 'https://api.usaspending.gov/api/v2/search/spending_by_category/recipient/' \
  -H 'Content-Type: application/json' \
  -d '{
  "filters": {
    "recipient_id": "1c3edaaa-611b-840c-bf2b-fd34df49f21f-P",
    "time_period": [
      {
        "start_date": "2019-09-28",
        "end_date": "2020-09-28"
      }
    ]
  },
  "category": "recipient",
  "limit": 5,
  "page": 1,
  "spending_level": "transactions"
}'
Full reference and live console Contract
POSTSpending By State Territory/api/v2/search/spending_by_category/state_territory/

This endpoint supports the state profile page and allow for complex filtering for specific subsets of spending data.

filterslimitpagespending_levelsubawards
curl -X POST 'https://api.usaspending.gov/api/v2/search/spending_by_category/state_territory/' \
  -H 'Content-Type: application/json' \
  -d '{
  "filters": {
    "recipient_id": "1c3edaaa-611b-840c-bf2b-fd34df49f21f-P",
    "time_period": [
      {
        "start_date": "2019-09-28",
        "end_date": "2020-09-28"
      }
    ]
  },
  "category": "state_territory",
  "limit": 5,
  "page": 1,
  "spending_level": "transactions"
}'
Full reference and live console Contract
POSTSpending by Geography/api/v2/search/spending_by_geography/

This endpoint supports the advanced search page and allow for complex filtering for specific subsets of spending data.

filterssubawardsspending_levelscopegeo_layergeo_layer_filters
curl -X POST 'https://api.usaspending.gov/api/v2/search/spending_by_geography/' \
  -H 'Content-Type: application/json' \
  -d '{
  "filters": {
    "keywords": [
      "Filter is required"
    ]
  },
  "scope": "place_of_performance",
  "geo_layer": "state"
}'
Full reference and live console Contract
POSTSpending By Subaward Grouped/api/v2/search/spending_by_subaward_grouped/

This endpoint takes award filters and returns a list containing filtered award ids, the number of subawards in each award, the total amount of obligations of all the subawards, the prime award obligat

filterslimitpagesortorder
curl -X POST 'https://api.usaspending.gov/api/v2/search/spending_by_subaward_grouped/' \
  -H 'Content-Type: application/json' \
  -d '{
  "limit": 10,
  "page": 1,
  "filters": {
    "award_type_codes": [
      "A",
      "B",
      "C"
    ],
    "time_period": [
      {
        "start_date": "2018-10-01",
        "end_date": "2019-09-30"
      }
    ]
  },
  "sort": "award_id",
  "order": "desc"
}'
Full reference and live console Contract
POSTSpending Over Time/api/v2/search/spending_over_time/

This endpoint supports the advanced search page and allow for complex filtering for specific subsets of spending data.

groupfilterssubawardsspending_level
curl -X POST 'https://api.usaspending.gov/api/v2/search/spending_over_time/' \
  -H 'Content-Type: application/json' \
  -d '{
  "group": "fiscal_year",
  "filters": {
    "keywords": [
      "Filter is required"
    ]
  }
}'
Full reference and live console Contract

Loading…