# USAspending.gov Scraper: Awards, Recipients & Aggregates (`autofacts/usaspending-scraper`) Actor Search federal awards, subawards, recipients, NAICS/PSC filters, category totals, and state/county/district geography aggregates from the official public USAspending.gov API. No API key required. - **URL**: https://apify.com/autofacts/usaspending-scraper.md - **Developed by:** [Richard Feng](https://apify.com/autofacts) (community) - **Categories:** Business, AI, Developer tools - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing $1.00 / 1,000 federal spending records This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Actors are written with capital "A". ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ## USAspending.gov Scraper: Awards, Recipients & Aggregates Export federal spending data from the public USAspending.gov API: award search results, exact award details, subawards, recipient profiles, category totals, and geography aggregates. ### At a glance | Field | Details | |-------|---------| | Source | Official USAspending.gov public API | | Authentication | No API key required | | Coverage | U.S. federal awards, contracts, grants, recipients, subawards, agencies, NAICS/PSC classifications, and geography aggregates | | Geography | State, county, congressional district, country, place of performance, and recipient location views | | Best for | USAspending scraper, federal contracts API, grants data extraction, contractor market research, agency spend analysis, geographic funding dashboards | | Pricing | $0.001 per saved row | ### Features | Feature | Description | |---------|-------------| | Public API | Uses USAspending.gov API v2 directly; no API key is required. | | Award search | Search by keywords, fiscal year/date range, agency, recipient text, NAICS, PSC, amount, and award type. | | Award details | Fetch full award detail records by USAspending generated award ID. | | Subawards | Pull subaward rows for a parent generated award ID. | | Recipient profile | Fetch recipient profile records by USAspending recipient hash. | | Category aggregates | Export 18 aggregation categories including recipient, NAICS, PSC, agency, county, district, state, country, CFDA, account, object class, program activity, and TAS. | | Geography aggregates | Export state, county, district, or country totals with population and per-capita fields when returned by the API. | ### Quick Start ```json { "mode": "awards", "keywords": ["diabetes"], "fiscalYear": 2025, "awardTypes": ["A", "B", "C", "D"], "maxItems": 100 } ```` ### Input | Field | Type | Required | Default | Description | |-------|------|----------|---------|-------------| | `mode` | string | no | `awards` | `awards`, `awardDetail`, `subawards`, `recipient`, `byCategory`, or `geography`. | | `keywords` | string\[] | no | - | Free-text search terms. | | `fiscalYear` | integer | no | - | Federal fiscal year date range. | | `dateFrom`, `dateTo` | string | no | - | Explicit YYYY-MM-DD range. Use together. | | `dateSlice` | string | no | `none` | Split large date ranges by `month` or `quarter`. | | `awardTypes` | string\[] | no | all groups for award search | USAspending award type codes. Mixed groups are split into valid API requests. | | `agency` | string | no | - | Exact agency name. | | `agencyType` | string | no | `awarding` | `awarding` or `funding`. | | `agencyTier` | string | no | `toptier` | `toptier` or `subtier`. | | `naicsCodes` | string\[] | no | - | Required NAICS codes. | | `excludeNaicsCodes` | string\[] | no | - | NAICS codes to exclude. | | `pscCodes` | string\[] | no | - | PSC codes. | | `recipientSearch` | string | no | - | Recipient text filter for award search. | | `minAmount`, `maxAmount` | number | no | - | Award amount bounds. | | `awardId` | string | awardDetail/subawards | - | USAspending generated award ID. | | `recipientId` | string | recipient | - | USAspending recipient hash ending in `-C` or `-P`. | | `category` | string | byCategory | `recipient_duns` | Aggregation category. | | `geoLayer` | string | geography | `state` | `state`, `county`, `district`, or `country`. | | `scope` | string | geography | `place_of_performance` | `place_of_performance` or `recipient_location`. | | `spendingLevel` | string | no | `transactions` | Aggregation level for category/geography modes. | | `maxItems` | integer | no | 100 | Maximum saved records. | ### Output Dataset rows are one of: | `itemType` | Description | |------------|-------------| | `award` | Normalized award search row with recipient, agencies, amount, NAICS/PSC, performance location, dates, description, and URL. | | `awardDetail` | Full raw award detail record plus key display fields. | | `subaward` | Subaward row for a parent generated award ID. | | `recipient` | Full raw recipient profile record plus key display fields. | | `category` | Aggregate category row with key, name, amount, count, and metadata. | | `geography` | Geographic aggregate row with key, name, amount, population, and per-capita fields. | #### Example Item ```json { "itemType": "award", "awardId": "HT940216C0001", "generatedId": "CONT_AWD_HT940216C0001_9700_-NONE-_-NONE-", "recipient": { "name": "HUMANA GOVERNMENT BUSINESS INC" }, "amount": 51269205263.03, "awardingAgency": "Department of Defense", "url": "https://www.usaspending.gov/award/CONT_AWD_HT940216C0001_9700_-NONE-_-NONE-" } ``` ### Recipes #### NAICS market scan ```json { "mode": "awards", "fiscalYear": 2025, "naicsCodes": ["524114"], "awardTypes": ["A", "B", "C", "D"], "maxItems": 500 } ``` Use this for contractor business development and competitor research in a specific NAICS market. #### Congressional district funding ```json { "mode": "geography", "geoLayer": "district", "fiscalYear": 2025, "keywords": ["broadband"], "maxItems": 100 } ``` This produces BI-friendly district rows with spending totals and geographic keys. #### Top recipients by category ```json { "mode": "byCategory", "category": "recipient_duns", "fiscalYear": 2025, "agency": "Department of Defense", "maxItems": 100 } ``` Use category output to discover recipient IDs and then fetch exact recipient profiles. ### Pricing This Actor uses pay-per-event pricing: **$0.001 per saved row**. A run fetching 1,000 rows costs approximately **$1.00**. ### FAQ **Do I need an API key?** No. USAspending.gov API v2 is public and does not require an API key. **Why are mixed award type codes split into multiple requests?** USAspending rejects a single award search containing codes from multiple award type groups. The Actor groups codes automatically and emits the matched `awardTypeCodes` on each row. **How do I fetch award details or subawards?** Run `mode: "awards"` first and use the returned `generatedId` as `awardId` for `awardDetail` or `subawards`. ### Legal & Compliance USAspending.gov is an official public federal spending data source. This Actor uses the public API with conservative request spacing and stores the data returned by the API. Review USAspending.gov terms and your downstream compliance requirements before making legal, procurement, or investment decisions from exported data. # Actor input Schema ## `mode` (type: `string`): Choose the USAspending workflow to run. ## `keywords` (type: `array`): Free-text USAspending keyword filters. ## `fiscalYear` (type: `integer`): Federal fiscal year. FY 2025 maps to 2024-10-01 through 2025-09-30. ## `dateFrom` (type: `string`): Start date in YYYY-MM-DD format. Provide with Date to. ## `dateTo` (type: `string`): End date in YYYY-MM-DD format. Provide with Date from. ## `dateSlice` (type: `string`): Split date ranges into monthly or quarterly API windows for large result sets. ## `awardTypes` (type: `array`): USAspending award type codes. Mixed groups are split into valid API requests automatically. ## `agency` (type: `string`): Exact agency name, e.g. Department of Defense. ## `agencyType` (type: `string`): Whether the agency filter applies to awarding or funding agency. ## `agencyTier` (type: `string`): Top-tier or sub-tier agency matching. ## `naicsCodes` (type: `array`): Required NAICS codes. ## `excludeNaicsCodes` (type: `array`): NAICS codes to exclude. ## `pscCodes` (type: `array`): Product/service codes. ## `recipientSearch` (type: `string`): Recipient name or identifier text for award search filters. ## `minAmount` (type: `number`): Lower bound for award amount filters. ## `maxAmount` (type: `number`): Upper bound for award amount filters. ## `awardId` (type: `string`): Required for awardDetail and subawards modes. Use generated\_internal\_id from awards search. ## `recipientId` (type: `string`): Required for recipient mode, e.g. a USAspending recipient hash ending in -C or -P. ## `category` (type: `string`): Aggregation category for byCategory mode. ## `geoLayer` (type: `string`): Geographic aggregation layer for geography mode. ## `scope` (type: `string`): Use place of performance or recipient location for geography mode. ## `spendingLevel` (type: `string`): Aggregation level for category and geography modes. ## `maxItems` (type: `integer`): Maximum number of items to extract and save. Each saved item is charged as one event. ## Actor input object example ```json { "mode": "awards", "dateSlice": "none", "agencyType": "awarding", "agencyTier": "toptier", "category": "recipient_duns", "geoLayer": "state", "scope": "place_of_performance", "spendingLevel": "transactions", "maxItems": 100 } ``` # Actor output Schema ## `overview` (type: `string`): No description # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = {}; // Run the Actor and wait for it to finish const run = await client.actor("autofacts/usaspending-scraper").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = {} # Run the Actor and wait for it to finish run = client.actor("autofacts/usaspending-scraper").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{}' | apify call autofacts/usaspending-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=autofacts/usaspending-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "USAspending.gov Scraper: Awards, Recipients & Aggregates", "description": "Search federal awards, subawards, recipients, NAICS/PSC filters, category totals, and state/county/district geography aggregates from the official public USAspending.gov API. No API key required.", "version": "1.0", "x-build-id": "fXQXKhfxcrTtvu1ee" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/autofacts~usaspending-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-autofacts-usaspending-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/autofacts~usaspending-scraper/runs": { "post": { "operationId": "runs-sync-autofacts-usaspending-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/autofacts~usaspending-scraper/run-sync": { "post": { "operationId": "run-sync-autofacts-usaspending-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "properties": { "mode": { "title": "Mode", "enum": [ "awards", "awardDetail", "subawards", "recipient", "byCategory", "geography" ], "type": "string", "description": "Choose the USAspending workflow to run.", "default": "awards" }, "keywords": { "title": "Keywords", "type": "array", "description": "Free-text USAspending keyword filters.", "items": { "type": "string" } }, "fiscalYear": { "title": "Fiscal year", "type": "integer", "description": "Federal fiscal year. FY 2025 maps to 2024-10-01 through 2025-09-30." }, "dateFrom": { "title": "Date from", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "type": "string", "description": "Start date in YYYY-MM-DD format. Provide with Date to." }, "dateTo": { "title": "Date to", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "type": "string", "description": "End date in YYYY-MM-DD format. Provide with Date from." }, "dateSlice": { "title": "Date slicing", "enum": [ "none", "month", "quarter" ], "type": "string", "description": "Split date ranges into monthly or quarterly API windows for large result sets.", "default": "none" }, "awardTypes": { "title": "Award type codes", "type": "array", "description": "USAspending award type codes. Mixed groups are split into valid API requests automatically.", "items": { "type": "string" } }, "agency": { "title": "Agency name", "type": "string", "description": "Exact agency name, e.g. Department of Defense." }, "agencyType": { "title": "Agency type", "enum": [ "awarding", "funding" ], "type": "string", "description": "Whether the agency filter applies to awarding or funding agency.", "default": "awarding" }, "agencyTier": { "title": "Agency tier", "enum": [ "toptier", "subtier" ], "type": "string", "description": "Top-tier or sub-tier agency matching.", "default": "toptier" }, "naicsCodes": { "title": "NAICS codes", "type": "array", "description": "Required NAICS codes.", "items": { "type": "string" } }, "excludeNaicsCodes": { "title": "Exclude NAICS codes", "type": "array", "description": "NAICS codes to exclude.", "items": { "type": "string" } }, "pscCodes": { "title": "PSC codes", "type": "array", "description": "Product/service codes.", "items": { "type": "string" } }, "recipientSearch": { "title": "Recipient search", "type": "string", "description": "Recipient name or identifier text for award search filters." }, "minAmount": { "title": "Minimum award amount", "type": "number", "description": "Lower bound for award amount filters." }, "maxAmount": { "title": "Maximum award amount", "type": "number", "description": "Upper bound for award amount filters." }, "awardId": { "title": "Generated award ID", "type": "string", "description": "Required for awardDetail and subawards modes. Use generated_internal_id from awards search." }, "recipientId": { "title": "Recipient ID", "type": "string", "description": "Required for recipient mode, e.g. a USAspending recipient hash ending in -C or -P." }, "category": { "title": "Category", "enum": [ "recipient_duns", "recipient_parent_duns", "naics", "psc", "awarding_agency", "awarding_subagency", "funding_agency", "funding_subagency", "county", "district", "state_territory", "country", "cfda", "defc", "federal_account", "object_class", "program_activity", "tas" ], "type": "string", "description": "Aggregation category for byCategory mode.", "default": "recipient_duns" }, "geoLayer": { "title": "Geography layer", "enum": [ "state", "county", "district", "country" ], "type": "string", "description": "Geographic aggregation layer for geography mode.", "default": "state" }, "scope": { "title": "Geography scope", "enum": [ "place_of_performance", "recipient_location" ], "type": "string", "description": "Use place of performance or recipient location for geography mode.", "default": "place_of_performance" }, "spendingLevel": { "title": "Spending level", "enum": [ "transactions", "awards", "subawards" ], "type": "string", "description": "Aggregation level for category and geography modes.", "default": "transactions" }, "maxItems": { "title": "Max items", "minimum": 1, "type": "integer", "description": "Maximum number of items to extract and save. Each saved item is charged as one event.", "default": 100 } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```