# USAspending.gov Awards Scraper (`datamule/usaspending-gov-awards-scraper`) Actor Scrape U.S. federal awards from the official USAspending.gov API. Query contracts, grants, loans & assistance by recipient, agency, NAICS/PSC, date & amount. One record per award — recipient, amount, agency, dates, codes + raw. Pay per award. - **URL**: https://apify.com/datamule/usaspending-gov-awards-scraper.md - **Developed by:** [Datamule](https://apify.com/datamule) (community) - **Categories:** Developer tools - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $0.35 / 1,000 award records This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have. 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 Awards Scraper Scrape U.S. federal award records — **contracts, grants, loans and other financial assistance** — from the **official USAspending.gov API** (`https://api.usaspending.gov/api/v2/search/spending_by_award`), the U.S. Treasury's public system of record for federal spending. No API key, no login. One clean dataset record per award, with a unified set of normalized columns plus the complete raw award object so nothing is lost. ### What it does Pick an **award category** (`awardGroup`) — USAspending requires every award type in a single query to belong to one category — then filter it any way you like (the API ANDs the filters together): | Input | API filter | Example | |-------|-----------|---------| | `awardGroup` | award category | `contracts`, `grants`, `loans` | | `keywords` | free-text over the whole award | `cybersecurity`, `cloud` | | `recipientSearch` | recipient (company/org) name | `Lockheed Martin` | | `awardingAgency` | awarding top-tier agency | `Department of Defense` | | `naicsCodes` | NAICS industry code(s) | `541519` | | `pscCodes` | PSC product/service code(s) | `D319` | | `awardTypeCodes` | specific type codes within the category | `D` (definitive contracts) | | `startDate` / `endDate` | award action-date window | `2020-01-01` → `2023-12-31` | | `minAmount` / `maxAmount` | award-amount range (USD) | `1000000` → … | | `sort` / `order` | result ordering | `amount` / `desc` | `maxResults` caps how many awards you get; the actor paginates automatically (up to 100 per request) until it reaches the cap or the result set is exhausted. #### Award categories - **contracts** — BPA calls, purchase orders, delivery orders, definitive contracts - **idvs** — indefinite-delivery vehicles (GWAC, IDC, FSS schedules, BOA, BPA) - **grants** — block / formula / project grants + cooperative agreements - **loans** — direct & guaranteed/insured loans - **other_financial_assistance** — direct payments for specified / unrestricted use - **direct_payments** — insurance, other financial assistance, etc. ### Output One dataset record per award. The source columns differ by category (contracts carry NAICS/PSC + a contract award type; assistance awards carry a CFDA program + an assistance award type; loans carry a loan value / subsidy cost instead of an obligated amount) — so every record is flattened onto **one unified schema**: `awardId`, `awardGroup`, `awardType`, `recipientName`, `recipientUei`, `recipientId`, `awardAmount`, `totalOutlays`, `loanValue`, `subsidyCost`, `awardingAgency`, `awardingSubAgency`, `fundingAgency`, `fundingSubAgency`, `periodOfPerformanceStart`, `periodOfPerformanceEnd`, `lastModifiedDate`, `baseObligationDate`, `description`, `naicsCode`, `naicsDescription`, `pscCode`, `pscDescription`, `cfdaNumber`, `cfdaProgramTitle`, `assistanceListings`, `recipientLocation` (city / state / country), `placeOfPerformance` (city / state / country), `defCodes`, `covid19Obligations`, `covid19Outlays`, `infrastructureObligations`, `infrastructureOutlays`, `awardUrl`, `generatedInternalId` …plus **`raw`** — the complete, untouched award object from the API — so any field not surfaced above is still available. ### Example input ```json { "awardGroup": "contracts", "keywords": ["cloud"], "awardingAgency": "Department of Defense", "startDate": "2020-01-01", "minAmount": 1000000, "sort": "amount", "order": "desc", "maxResults": 200 } ```` A query that matches nothing returns **0 records and succeeds** (never an error). ### Notes & limits - USAspending's searchable award history starts at **2007-10-01**. For older data (back to 2000-10-01) use USAspending's bulk-download endpoints. - Deep paging is capped at roughly **10,000 records per query** — refine your filters (agency, date window, amount) to reach the rest. - NAICS/PSC codes are only populated on **contract-type** awards; CFDA program info only on **assistance** awards. Non-applicable columns come back `null`. ### Pricing Pay-per-event: charged per award returned. ### Source Data comes from the U.S. Department of the Treasury's USAspending.gov API (). USAspending.gov data is in the public domain. This actor is an independent tool and is not affiliated with or endorsed by the U.S. Treasury or any federal agency. # Actor input Schema ## `awardGroup` (type: `string`): Which category of federal award to search. USAspending requires all award types in one query to belong to a single category, so pick one per run. Contracts = procurement (BPA calls, purchase/delivery orders, definitive contracts). IDVs = indefinite-delivery vehicles (GWAC, IDC, FSS schedules). Grants = block/formula/project grants + cooperative agreements. Loans = direct & guaranteed loans. Other financial assistance / Direct payments = the remaining assistance types. ## `keywords` (type: `string`): Free-text search across the whole award record (maps to the API's keywords filter). e.g. "cybersecurity", "cloud migration", "vaccine". One term per line, or comma-separated. Combine with the filters below. ## `recipientSearch` (type: `string`): Search by recipient name — the company, university, state, or organization that received the award (recipient\_search\_text). e.g. "Lockheed Martin", "Johns Hopkins University". One per line, or comma-separated. ## `awardingAgency` (type: `string`): Filter to a single awarding top-tier agency, by its full name. e.g. "Department of Defense", "Department of Health and Human Services", "National Aeronautics and Space Administration". Leave empty for all agencies. ## `naicsCodes` (type: `string`): Filter contracts/IDVs by one or more NAICS industry codes. e.g. "541519" (other computer related services), "541512" (computer systems design). One per line, or comma-separated. (NAICS is only populated on contract-type awards.) ## `pscCodes` (type: `string`): Filter contracts/IDVs by one or more PSC (Product & Service) codes. e.g. "D319" (IT & telecom other), "R425" (engineering technical services). One per line, or comma-separated. (PSC is only populated on contract-type awards.) ## `awardTypeCodes` (type: `string`): Advanced: narrow to specific award type codes WITHIN the selected category. e.g. for Contracts, "D" = only definitive contracts; for Grants, "04" = only project grants. Must belong to the chosen award category. Leave empty to include every type in the category. ## `startDate` (type: `string`): Only awards with an action date on or after this date (YYYY-MM-DD). USAspending's searchable history starts at 2007-10-01. Leave empty for no lower bound. ## `endDate` (type: `string`): Only awards with an action date on or before this date (YYYY-MM-DD). Leave empty for no upper bound. ## `minAmount` (type: `integer`): Only awards with an amount at or above this value (US dollars). Leave empty for no minimum. ## `maxAmount` (type: `integer`): Only awards with an amount at or below this value (US dollars). Leave empty for no maximum. ## `sort` (type: `string`): Field to sort results by. Amount / Outlays / Start date / End date / Last modified / Recipient / Award ID apply to contracts, grants and assistance; Loan value / Subsidy cost apply to loans. If a sort field doesn't apply to the chosen award category, the actor falls back to that category's default so the query always succeeds. ## `order` (type: `string`): Ascending or descending. ## `maxResults` (type: `integer`): Maximum number of award records to return. The actor paginates automatically at up to 100 per request until this many are collected or the result set is exhausted. Note: USAspending caps deep paging at roughly 10,000 records per query — refine your filters to reach the rest. ## `limit` (type: `integer`): Awards fetched per API request (1–100). Larger pages = fewer requests. Usually leave at the default. ## Actor input object example ```json { "awardGroup": "contracts", "keywords": "cloud", "minAmount": 1000000, "sort": "amount", "order": "desc", "maxResults": 100, "limit": 100 } ``` # Actor output Schema ## `results` (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 = { "keywords": "cloud", "recipientSearch": "", "awardingAgency": "", "naicsCodes": "", "pscCodes": "", "awardTypeCodes": "", "startDate": "", "endDate": "", "minAmount": 1000000, "maxResults": 100, "limit": 100 }; // Run the Actor and wait for it to finish const run = await client.actor("datamule/usaspending-gov-awards-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 = { "keywords": "cloud", "recipientSearch": "", "awardingAgency": "", "naicsCodes": "", "pscCodes": "", "awardTypeCodes": "", "startDate": "", "endDate": "", "minAmount": 1000000, "maxResults": 100, "limit": 100, } # Run the Actor and wait for it to finish run = client.actor("datamule/usaspending-gov-awards-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 '{ "keywords": "cloud", "recipientSearch": "", "awardingAgency": "", "naicsCodes": "", "pscCodes": "", "awardTypeCodes": "", "startDate": "", "endDate": "", "minAmount": 1000000, "maxResults": 100, "limit": 100 }' | apify call datamule/usaspending-gov-awards-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=datamule/usaspending-gov-awards-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "USAspending.gov Awards Scraper", "description": "Scrape U.S. federal awards from the official USAspending.gov API. Query contracts, grants, loans & assistance by recipient, agency, NAICS/PSC, date & amount. One record per award — recipient, amount, agency, dates, codes + raw. Pay per award.", "version": "0.1", "x-build-id": "iPX4ahUrHLfCmvKcX" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/datamule~usaspending-gov-awards-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-datamule-usaspending-gov-awards-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/datamule~usaspending-gov-awards-scraper/runs": { "post": { "operationId": "runs-sync-datamule-usaspending-gov-awards-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/datamule~usaspending-gov-awards-scraper/run-sync": { "post": { "operationId": "run-sync-datamule-usaspending-gov-awards-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": { "awardGroup": { "title": "Award category", "enum": [ "contracts", "idvs", "grants", "loans", "other_financial_assistance", "direct_payments" ], "type": "string", "description": "Which category of federal award to search. USAspending requires all award types in one query to belong to a single category, so pick one per run. Contracts = procurement (BPA calls, purchase/delivery orders, definitive contracts). IDVs = indefinite-delivery vehicles (GWAC, IDC, FSS schedules). Grants = block/formula/project grants + cooperative agreements. Loans = direct & guaranteed loans. Other financial assistance / Direct payments = the remaining assistance types.", "default": "contracts" }, "keywords": { "title": "Keywords (free text)", "type": "string", "description": "Free-text search across the whole award record (maps to the API's keywords filter). e.g. \"cybersecurity\", \"cloud migration\", \"vaccine\". One term per line, or comma-separated. Combine with the filters below." }, "recipientSearch": { "title": "Recipient (company / organization)", "type": "string", "description": "Search by recipient name — the company, university, state, or organization that received the award (recipient_search_text). e.g. \"Lockheed Martin\", \"Johns Hopkins University\". One per line, or comma-separated." }, "awardingAgency": { "title": "Awarding agency (top-tier)", "type": "string", "description": "Filter to a single awarding top-tier agency, by its full name. e.g. \"Department of Defense\", \"Department of Health and Human Services\", \"National Aeronautics and Space Administration\". Leave empty for all agencies." }, "naicsCodes": { "title": "NAICS codes", "type": "string", "description": "Filter contracts/IDVs by one or more NAICS industry codes. e.g. \"541519\" (other computer related services), \"541512\" (computer systems design). One per line, or comma-separated. (NAICS is only populated on contract-type awards.)" }, "pscCodes": { "title": "PSC codes", "type": "string", "description": "Filter contracts/IDVs by one or more PSC (Product & Service) codes. e.g. \"D319\" (IT & telecom other), \"R425\" (engineering technical services). One per line, or comma-separated. (PSC is only populated on contract-type awards.)" }, "awardTypeCodes": { "title": "Specific award type codes (advanced)", "type": "string", "description": "Advanced: narrow to specific award type codes WITHIN the selected category. e.g. for Contracts, \"D\" = only definitive contracts; for Grants, \"04\" = only project grants. Must belong to the chosen award category. Leave empty to include every type in the category." }, "startDate": { "title": "Action date from", "type": "string", "description": "Only awards with an action date on or after this date (YYYY-MM-DD). USAspending's searchable history starts at 2007-10-01. Leave empty for no lower bound." }, "endDate": { "title": "Action date to", "type": "string", "description": "Only awards with an action date on or before this date (YYYY-MM-DD). Leave empty for no upper bound." }, "minAmount": { "title": "Minimum award amount (USD)", "type": "integer", "description": "Only awards with an amount at or above this value (US dollars). Leave empty for no minimum." }, "maxAmount": { "title": "Maximum award amount (USD)", "type": "integer", "description": "Only awards with an amount at or below this value (US dollars). Leave empty for no maximum." }, "sort": { "title": "Sort by", "enum": [ "amount", "outlays", "loanValue", "subsidyCost", "startDate", "endDate", "lastModified", "recipient", "awardId" ], "type": "string", "description": "Field to sort results by. Amount / Outlays / Start date / End date / Last modified / Recipient / Award ID apply to contracts, grants and assistance; Loan value / Subsidy cost apply to loans. If a sort field doesn't apply to the chosen award category, the actor falls back to that category's default so the query always succeeds.", "default": "amount" }, "order": { "title": "Sort order", "enum": [ "desc", "asc" ], "type": "string", "description": "Ascending or descending.", "default": "desc" }, "maxResults": { "title": "Max results", "minimum": 1, "type": "integer", "description": "Maximum number of award records to return. The actor paginates automatically at up to 100 per request until this many are collected or the result set is exhausted. Note: USAspending caps deep paging at roughly 10,000 records per query — refine your filters to reach the rest.", "default": 100 }, "limit": { "title": "Page size", "minimum": 1, "maximum": 100, "type": "integer", "description": "Awards fetched per API request (1–100). Larger pages = fewer requests. Usually leave at the default.", "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 } } } } } } } } } } ```