# USAspending Loans Scraper (`automation-lab/usaspending-loans-scraper`) Actor Export federal direct-loan and guaranteed-loan awards from USAspending by date, agency, program, recipient, and location. - **URL**: https://apify.com/automation-lab/usaspending-loans-scraper.md - **Developed by:** [Stas Persiianenko](https://apify.com/automation-lab) (community) - **Categories:** Developer tools - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing Pay per event 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 Loans Scraper Export federal direct-loan and guaranteed-loan awards from USAspending in a clean dataset. ### What does USAspending Loans Scraper do? USAspending Loans Scraper searches the public USAspending award API for loan awards. It focuses on federal award type codes `07` and `08`. Those codes represent direct loans and guaranteed or insured loans. The actor saves normalized rows that are ready for spreadsheets, BI tools, alerts, and compliance workflows. ### Who is it for? #### Lenders and capital providers - ๐Ÿฆ Track federal direct-loan and loan-guarantee activity by program, state, recipient, and date window. - ๐Ÿงพ Check whether a borrower, partner, or market segment appears in newly reported loan awards. #### Government affairs and compliance teams - ๐Ÿ›๏ธ Monitor agencies, sub-agencies, and assistance listings tied to federal lending programs. - ๐Ÿงพ Export recurring evidence for internal compliance reviews, grant/loan exposure checks, and briefing notes. #### Public finance and economic development analysts - ๐Ÿ“Š Build repeatable loan-award datasets for dashboards, policy analysis, and place-based lending research. - ๐Ÿ—๏ธ Compare activity by state, recipient location, performance location, program, and obligation date. #### Automation and data teams - ๐Ÿค– Pull USAspending loan award rows through the Apify API without maintaining pagination, filtering, or schema normalization code. - ๐Ÿ” Schedule recurring tasks that feed BI tools, spreadsheets, alerts, and downstream enrichment workflows. ### Why use this actor? The USAspending website is broad and interactive. This actor packages a narrow workflow for loan awards only. You can filter by dates, award type, recipient keyword, state, agency IDs, and assistance listing numbers. The output is one predictable table instead of a website search session. ### Data source The actor uses the public endpoint: `POST https://api.usaspending.gov/api/v2/search/spending_by_award/` No login is required. No API key is required. No browser automation is used. No proxy is used by default. ### Loan award scope - Direct loans: USAspending award type code `07`. - Guaranteed or insured loans: USAspending award type code `08`. - Both loan families can be searched together. ### Data fields | Field | Description | | --- | --- | | `awardId` | Public USAspending award identifier. | | `generatedInternalId` | USAspending generated internal identifier. | | `internalId` | Numeric internal ID from the API. | | `recipientName` | Recipient name as published by USAspending. | | `recipientUei` | Recipient UEI when available. | | `awardingAgency` | Awarding agency name. | | `awardingSubAgency` | Awarding sub-agency name. | | `fundingAgency` | Funding agency name. | | `fundingSubAgency` | Funding sub-agency name. | | `loanAwardType` | Direct loan, guaranteed loan, or mixed loan search. | | `baseObligationDate` | Base obligation date. | | `awardAmount` | Award amount when USAspending returns it. | | `loanValue` | Loan value when USAspending returns it. | | `cfdaNumber` | Assistance listing / CFDA number. | | `cfdaTitle` | Assistance listing title. | | `recipientStateCode` | Recipient state code when available. | | `placeOfPerformanceStateCode` | Place of performance state code when available. | | `description` | Public award description. | | `scrapedAt` | Timestamp when the row was saved. | ### How much does it cost to extract USAspending loan awards? The actor uses pay-per-event pricing. There is a small start charge per run. Each saved loan award row is charged as one result item. Use `maxItems` to control cost. Start with a small search, review the data, and increase the limit for recurring monitoring. | Event | When it is charged | Price | | --- | --- | --- | | Run started | Once per actor run | `$0.005` | | Item extracted | Per saved loan award row on the Bronze tier | `$0.000026016` | Example cost estimates on the Bronze tier: | Run size | Formula | Estimated actor charge | | --- | --- | --- | | 10 loan awards | `$0.005 + 10 ร— $0.000026016` | about `$0.0053` | | 100 loan awards | `$0.005 + 100 ร— $0.000026016` | about `$0.0076` | | 1,000 loan awards | `$0.005 + 1,000 ร— $0.000026016` | about `$0.0310` | A small free-plan test run is practical because the actor has low compute cost, no proxy requirement, and very small per-item charges. Use `maxItems: 10` or `maxItems: 100` while tuning filters, then raise the limit only after the dataset matches your workflow. ### How to use it 1. Open the actor on Apify. 2. Choose a date range. 3. Select direct loans, guaranteed loans, or both. 4. Add optional filters such as recipient keyword, state, agency IDs, or CFDA numbers. 5. Set `maxItems`. 6. Run the actor. 7. Export the dataset as JSON, CSV, Excel, XML, or RSS. ### Input options #### Date range Use `dateFrom` and `dateTo` in `YYYY-MM-DD` format. These map to USAspending base obligation dates. #### Award type preset Choose: - `both` - `direct_loans` - `guaranteed_loans` #### Recipient keyword Use `recipientSearchText` to search names that include a term such as `solar`, `housing`, or a company name. #### Geography filters Use two-letter state or territory codes. `recipientState` filters recipient locations. `placeOfPerformanceState` filters performance locations. #### Agency filters Use `agencyIds` for USAspending toptier awarding agency IDs. Leave it empty to search all agencies. #### Program filters Use `cfdaNumbers` for assistance listing numbers such as `10.766` or `14.021`. ### Example input ```json { "dateFrom": "2024-01-01", "dateTo": "2024-12-31", "awardTypePreset": "both", "maxItems": 100, "recipientSearchText": "solar", "recipientState": "CA", "includeDescriptions": true } ```` ### Example output ```json { "awardId": "6660089100", "recipientName": "ECOSOLAR USA ELECTRICAL LLC", "awardingAgency": "Small Business Administration", "loanAwardType": "Loan / loan guarantee", "baseObligationDate": "2024-12-05", "cfdaNumber": "59.012", "sourceApi": "https://api.usaspending.gov/api/v2/search/spending_by_award/" } ``` ### Tips for better results - Use a broad date range first to understand volume. - Add a recipient keyword when tracking one sector or company family. - Use CFDA numbers for program-specific monitoring. - Use state filters for local economic development research. - Keep `maxItems` low while tuning a saved task. ### Common workflows #### Federal loan monitoring Run the actor monthly for a date window and append the dataset to a tracking table. #### Recipient due diligence Search by recipient keyword and export matching federal loan awards. #### Program research Filter by CFDA numbers to study program activity across agencies and states. #### State-level dashboards Filter by recipient or performance state and load the results into a dashboard. ### Integrations - Send results to Google Sheets through an Apify integration. - Export CSV to a BI pipeline. - Trigger a webhook after every recurring monitoring run. - Use the dataset API from Python, Node.js, or cURL. - Connect the actor to a larger federal-spending monitoring workflow. ### API usage: Node.js ```js import { ApifyClient } from 'apify-client'; const client = new ApifyClient({ token: process.env.APIFY_TOKEN }); const run = await client.actor('automation-lab/usaspending-loans-scraper').call({ dateFrom: '2024-01-01', dateTo: '2024-12-31', awardTypePreset: 'guaranteed_loans', maxItems: 100 }); console.log(run.defaultDatasetId); ``` ### API usage: Python ```python from apify_client import ApifyClient import os client = ApifyClient(os.environ['APIFY_TOKEN']) run = client.actor('automation-lab/usaspending-loans-scraper').call(run_input={ 'dateFrom': '2024-01-01', 'dateTo': '2024-12-31', 'awardTypePreset': 'both', 'maxItems': 100, }) print(run['defaultDatasetId']) ``` ### API usage: cURL ```bash curl -X POST "https://api.apify.com/v2/acts/automation-lab~usaspending-loans-scraper/runs?token=$APIFY_TOKEN" \ -H 'Content-Type: application/json' \ -d '{"dateFrom":"2024-01-01","dateTo":"2024-12-31","awardTypePreset":"both","maxItems":100}' ``` ### MCP integration Use this actor from Claude tools through the Apify MCP server. MCP URL: `https://mcp.apify.com/?tools=automation-lab/usaspending-loans-scraper` Claude Code setup: ```bash claude mcp add apify-usaspending-loans "https://mcp.apify.com/?tools=automation-lab/usaspending-loans-scraper" ``` Claude Desktop JSON config: ```json { "mcpServers": { "apify-usaspending-loans": { "url": "https://mcp.apify.com/?tools=automation-lab/usaspending-loans-scraper" } } } ``` Example prompts: - "Run USAspending Loans Scraper for guaranteed loans in California this year." - "Find federal loan awards for recipients matching solar and summarize the agencies." - "Export the latest 100 direct-loan awards and group them by assistance listing." ### Automation ideas - Schedule a monthly run for each state in your territory. - Alert when a tracked recipient appears in a new federal loan award. - Maintain a historical table of guaranteed loan awards by agency. - Compare loan activity before and after a policy change. ### Limitations The actor returns what the public USAspending API returns. Some recipient or location fields can be null. Some records have redacted or abbreviated descriptions. Award amounts and loan values can differ by award type and reporting rules. ### Troubleshooting #### Why did I get zero items? Your filters may be too narrow. Remove recipient, agency, state, or CFDA filters and try a broader date range. #### Why are some fields null? USAspending does not populate every field for every award type. Null values are preserved so the dataset reflects the source. #### Why is the description long? USAspending award descriptions often contain program language. Set `includeDescriptions` to false if you do not need that text. ### Legality and compliance This actor uses a public government API. You are responsible for using the data according to applicable laws, policies, and USAspending terms. Do not use public award data to make decisions that require additional verification without checking official source records. ### Related scrapers Explore other automation-lab public-data actors at: - https://apify.com/automation-lab/ - https://apify.com/automation-lab/google-news-scraper - https://apify.com/automation-lab/website-contact-finder ### Changelog - Initial version: focused USAspending direct-loan and guaranteed-loan award extraction. ### Support If you need an additional filter or field from USAspending, open an issue on the actor page with an example award or query. ### FAQ #### Does this actor scrape website pages? No. It calls the public USAspending API directly. #### Does it need a proxy? No proxy is used by default. #### Can it run on a schedule? Yes. Create an Apify task with your saved input and schedule it daily, weekly, or monthly. #### Can I export to CSV? Yes. Use the Apify dataset export options after the run. #### Can I monitor a single company? Yes. Use `recipientSearchText` with a company or organization name. # Actor input Schema ## `dateFrom` (type: `string`): Include loan awards with a base obligation date on or after this date (YYYY-MM-DD). ## `dateTo` (type: `string`): Include loan awards with a base obligation date on or before this date (YYYY-MM-DD). ## `awardTypePreset` (type: `string`): Choose direct loans, guaranteed/insured loans, or both USAspending loan award code families. ## `maxItems` (type: `integer`): Maximum number of USAspending loan award rows to save. ## `recipientSearchText` (type: `string`): Optional recipient name keyword, for example solar, housing, farm, or a company name. ## `recipientState` (type: `string`): Optional two-letter recipient state or territory code, for example CA or TX. ## `placeOfPerformanceState` (type: `string`): Optional two-letter performance-location state or territory code. ## `agencyIds` (type: `array`): Optional USAspending toptier awarding agency IDs. Leave empty to search all agencies. ## `cfdaNumbers` (type: `array`): Optional assistance listing numbers such as 10.766 or 14.021. ## `includeDescriptions` (type: `boolean`): Turn off to reduce dataset size when you only need identifiers and program metadata. ## `sortField` (type: `string`): USAspending field used for result ordering. ## `sortOrder` (type: `string`): Sort descending for newest/largest first, or ascending for oldest/smallest first. ## Actor input object example ```json { "dateFrom": "2024-01-01", "dateTo": "2024-12-31", "awardTypePreset": "both", "maxItems": 20, "recipientSearchText": "solar", "recipientState": "CA", "includeDescriptions": true, "sortField": "Base Obligation Date", "sortOrder": "desc" } ``` # 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 = { "dateFrom": "2024-01-01", "dateTo": "2024-12-31", "awardTypePreset": "both", "maxItems": 20, "recipientSearchText": "solar", "recipientState": "CA", "includeDescriptions": true }; // Run the Actor and wait for it to finish const run = await client.actor("automation-lab/usaspending-loans-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 = { "dateFrom": "2024-01-01", "dateTo": "2024-12-31", "awardTypePreset": "both", "maxItems": 20, "recipientSearchText": "solar", "recipientState": "CA", "includeDescriptions": True, } # Run the Actor and wait for it to finish run = client.actor("automation-lab/usaspending-loans-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 '{ "dateFrom": "2024-01-01", "dateTo": "2024-12-31", "awardTypePreset": "both", "maxItems": 20, "recipientSearchText": "solar", "recipientState": "CA", "includeDescriptions": true }' | apify call automation-lab/usaspending-loans-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=automation-lab/usaspending-loans-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "USAspending Loans Scraper", "description": "Export federal direct-loan and guaranteed-loan awards from USAspending by date, agency, program, recipient, and location.", "version": "0.1", "x-build-id": "lCVWkhfy0tuUeLFTS" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/automation-lab~usaspending-loans-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-automation-lab-usaspending-loans-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/automation-lab~usaspending-loans-scraper/runs": { "post": { "operationId": "runs-sync-automation-lab-usaspending-loans-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/automation-lab~usaspending-loans-scraper/run-sync": { "post": { "operationId": "run-sync-automation-lab-usaspending-loans-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": { "dateFrom": { "title": "Start date", "type": "string", "description": "Include loan awards with a base obligation date on or after this date (YYYY-MM-DD).", "default": "2024-01-01" }, "dateTo": { "title": "End date", "type": "string", "description": "Include loan awards with a base obligation date on or before this date (YYYY-MM-DD).", "default": "2024-12-31" }, "awardTypePreset": { "title": "Loan award types", "enum": [ "both", "direct_loans", "guaranteed_loans" ], "type": "string", "description": "Choose direct loans, guaranteed/insured loans, or both USAspending loan award code families.", "default": "both" }, "maxItems": { "title": "Maximum loan awards", "minimum": 1, "maximum": 10000, "type": "integer", "description": "Maximum number of USAspending loan award rows to save.", "default": 20 }, "recipientSearchText": { "title": "Recipient keyword", "type": "string", "description": "Optional recipient name keyword, for example solar, housing, farm, or a company name." }, "recipientState": { "title": "Recipient state", "type": "string", "description": "Optional two-letter recipient state or territory code, for example CA or TX." }, "placeOfPerformanceState": { "title": "Place of performance state", "type": "string", "description": "Optional two-letter performance-location state or territory code." }, "agencyIds": { "title": "Awarding agency IDs", "type": "array", "description": "Optional USAspending toptier awarding agency IDs. Leave empty to search all agencies.", "items": { "type": "integer" } }, "cfdaNumbers": { "title": "Assistance listing / CFDA numbers", "type": "array", "description": "Optional assistance listing numbers such as 10.766 or 14.021.", "items": { "type": "string" } }, "includeDescriptions": { "title": "Include award descriptions", "type": "boolean", "description": "Turn off to reduce dataset size when you only need identifiers and program metadata.", "default": true }, "sortField": { "title": "Sort field", "enum": [ "Base Obligation Date", "Award Amount", "Recipient Name", "Awarding Agency" ], "type": "string", "description": "USAspending field used for result ordering.", "default": "Base Obligation Date" }, "sortOrder": { "title": "Sort order", "enum": [ "desc", "asc" ], "type": "string", "description": "Sort descending for newest/largest first, or ascending for oldest/smallest first.", "default": "desc" } } }, "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 } } } } } } } } } } ```