{ "openapi": "3.1.1", "info": { "title": "Public Spending Explorer API", "version": "1.0.0", "summary": "Search government contracts and grants: who pays whom, totals per agency and vendor.", "description": "Every endpoint performs the same calculation as the human page and returns inputs, result, units, assumptions, sources, warnings and computedAt. MCP endpoint: /mcp." }, "servers": [ { "url": "https://publicspendingexplorer.usefulweb.site" } ], "paths": { "/api/v1/calculate": { "post": { "operationId": "calculate", "summary": "Search government contracts and grants: who pays whom, totals per agency and vendor.", "description": "Searches US federal awards on USAspending.gov (contracts, IDVs, grants, other assistance) or EU contract award notices on TED, then totals the results per agency/buyer and per recipient and draws the agency → recipient relationship graph. Paste a saved API response to analyse it offline.\n\nMethodology:\n- USAspending: POST https://api.usaspending.gov/api/v2/search/spending_by_award/ with filters {keywords, recipient_search_text, award_type_codes (one group), time_period}, sorted by \"Award Amount\" descending. \"Award Amount\" is the award's total obligated value, not only the money obligated inside the period.\n- For live USAspending searches the tool also calls spending_by_category/awarding_agency and /recipient (obligations of all matching transactions inside the period) and spending_by_award_count (counts per award group), so the totals are not limited to the listed page.\n- TED: POST https://api.ted.europa.eu/v3/notices/search (anonymous, no key) with an expert query restricted to contract award notices (can-standard, can-social, can-desg, can-tran) and the publication-date range. Multilingual names prefer English. Notice values are not split between several winners and are summed per currency — currencies are never converted.\n- Per-buyer and per-recipient totals sum only the awards listed (top N by amount for USAspending, newest N for TED). The graph links each buyer/agency to its recipients (edge = summed listed value), keeping the largest relationships up to 60 nodes.\n\nAward data is reported by agencies and may be revised; amounts are nominal and unconverted.", "tags": [ "public-data" ], "x-mcp-tool": "public_spending_explorer", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicSpendingExplorerInput" }, "examples": { "example1": { "summary": "Pasted USAspending response: largest \"wildfire\" grants FY2026", "value": { "source": "pasted", "pastedJson": "{\"limit\":8,\"results\":[{\"Award ID\":\"06D01725\",\"Recipient Name\":\"FLORIDA DEPARTMENT OF ENVIRONMENTAL PROTECTION\",\"Award Amount\":844671000.0,\"Awarding Agency\":\"Environmental Protection Agency\",\"Awarding Sub Agency\":\"Environmental Protection Agency\",\"Start Date\":\"2025-07-01\",\"End Date\":\"2032-06-30\",\"Description\":\"DESCRIPTION:THIS ACTION PROVIDES FUNDING IN THE AMOUNT OF $844,671,000 TO FLORIDA DEPARTME\",\"generated_internal_id\":\"ASST_NON_06D01725_068\"},{\"Award ID\":\"06D01826\",\"Recipient Name\":\"FLORIDA DEPARTMENT OF ENVIRONMENTAL PROTECTION\",\"Award Amount\":806392000.0,\"Awarding Agency\":\"Environmental Protection Agency\",\"Awarding Sub Agency\":\"Environmental Protection Agency\",\"Start Date\":\"2025-07-01\",\"End Date\":\"2032-06-30\",\"Description\":\"DESCRIPTION:THIS ACTION PROVIDES FUNDING IN THE AMOUNT OF $806,392,000 TO THE FLORIDA DEPA\",\"generated_internal_id\":\"ASST_NON_06D01826_068\"},{\"Award ID\":\"06D08726\",\"Recipient Name\":\"GEORGIA ENVIRONMENTAL FINANCE AUTHORITY\",\"Award Amount\":359487000.0,\"Awarding Agency\":\"Environmental Protection Agency\",\"Awarding Sub Agency\":\"Environmental Protection Agency\",\"Start Date\":\"2026-07-01\",\"End Date\":\"2033-06-30\",\"Description\":\"DESCRIPTION:THIS ACTION PROVIDES FUNDING IN THE AMOUNT OF $359,487,000 TO THE GEORGIA ENVI\",\"generated_internal_id\":\"ASST_NON_06D08726_068\"},{\"Award ID\":\"05D51125\",\"Recipient Name\":\"NORTH CAROLINA DEPARTMENT OF ENVIRONMENTAL QUALITY\",\"Award Amount\":253681000.0,\"Awarding Agency\":\"Environmental Protection Agency\",\"Awarding Sub Agency\":\"Environmental Protection Agency\",\"Start Date\":\"2025-07-01\",\"End Date\":\"2032-06-30\",\"Description\":\"DESCRIPTION:THIS ACTION APPROVES AN AWARD IN THE AMOUNT OF $253,681,000 TO PROVIDE FUNDING\",\"generated_internal_id\":\"ASST_NON_05D51125_068\"},{\"Award ID\":\"06D08526\",\"Recipient Name\":\"GEORGIA ENVIRONMENTAL FINANCE AUTHORITY\",\"Award Amount\":124892000.0,\"Awarding Agency\":\"Environmental Protection Agency\",\"Awarding Sub Agency\":\"Environmental Protection Agency\",\"Start Date\":\"2026-07-01\",\"End Date\":\"2033-06-30\",\"Description\":\"DESCRIPTION:THIS ACTION APPROVES FUNDING IN THE AMOUNT OF $124,892,000 TO THE GEORGIA ENVI\",\"generated_internal_id\":\"ASST_NON_06D08526_068\"},{\"Award ID\":\"DEGD0000892\",\"Recipient Name\":\"MIDWEST ENERGY, INC\",\"Award Amount\":96922280.0,\"Awarding Agency\":\"Department of Energy\",\"Awarding Sub Agency\":\"Department of Energy\",\"Start Date\":\"2024-10-01\",\"End Date\":\"2029-09-30\",\"Description\":\"BIPARTISAN INFRASTRUCTURE LAW (BIL) - TRANSMISSION LINE REBUILD/REPLACEMENT FOR WILDFIRE M\",\"generated_internal_id\":\"ASST_NON_DEGD0000892_089\"},{\"Award ID\":\"DEGD0000885\",\"Recipient Name\":\"HOLY CROSS ELECTRIC ASSOCIATION, INC\",\"Award Amount\":96746446.0,\"Awarding Agency\":\"Department of Energy\",\"Awarding Sub Agency\":\"Department of Energy\",\"Start Date\":\"2024-08-21\",\"End Date\":\"2029-08-20\",\"Description\":\"BIPARTISAN INFRASTRUCTURE LAW (BIL) - WILDFIRE ASSESSMENT AND RESILIENCE FOR NETWORKS (WAR\",\"generated_internal_id\":\"ASST_NON_DEGD0000885_089\"},{\"Award ID\":\"DEGD0000884\",\"Recipient Name\":\"XCEL ENERGY SERVICES INC.\",\"Award Amount\":95876582.0,\"Awarding Agency\":\"Department of Energy\",\"Awarding Sub Agency\":\"Department of Energy\",\"Start Date\":\"2024-10-01\",\"End Date\":\"2029-09-30\",\"Description\":\"BIPARTISAN INFRASTRUCTURE LAW (BIL) - WILDFIRE MITIGATION AND EXTREME WEATHER RESILIENCE F\",\"generated_internal_id\":\"ASST_NON_DEGD0000884_089\"}],\"page_metadata\":{\"page\":1,\"hasNext\":true}}", "limit": 50 } } } } } }, "responses": { "200": { "description": "Calculation result envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicSpendingExplorerResult" } } } }, "400": { "description": "Malformed JSON body.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid input (see errors[]).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded (see Retry-After).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/api/v1/tool": { "get": { "operationId": "getToolDefinition", "summary": "Inputs, output schema and examples for this tool", "responses": { "200": { "description": "Tool definition.", "content": { "application/json": { "schema": { "type": "object" } } } } } } } }, "components": { "schemas": { "Problem": { "type": "object", "description": "RFC 9457 problem details. 422 responses include per-field `errors`.", "required": [ "type", "title", "status", "detail" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } } }, "PublicSpendingExplorerInput": { "type": "object", "additionalProperties": false, "properties": { "source": { "title": "Data source", "type": "string", "enum": [ "usaspending", "ted", "pasted" ], "default": "usaspending" }, "keyword": { "title": "Keyword", "description": "Full-text keyword (award description / notice text).", "type": "string", "maxLength": 200 }, "recipient": { "title": "Recipient / vendor name", "description": "Optional. USAspending: recipient_search_text; TED: winner-name contains.", "type": "string", "maxLength": 200 }, "awardType": { "title": "Award type (USAspending)", "type": "string", "enum": [ "contracts", "idvs", "grants", "other_financial_assistance" ], "default": "contracts" }, "startDate": { "title": "From", "description": "Default: 365 days before today.", "type": "string", "format": "date" }, "endDate": { "title": "To", "description": "Default: today.", "type": "string", "format": "date" }, "buyerCountry": { "title": "Buyer country (TED, ISO 3166 alpha-3)", "type": "string", "maxLength": 3 }, "limit": { "title": "Max results", "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "pastedJson": { "title": "Pasted JSON response", "description": "Response of USAspending POST /api/v2/search/spending_by_award/ or TED POST /v3/notices/search.", "type": "string", "maxLength": 2000000 } }, "required": [] }, "PublicSpendingExplorerResult": { "type": "object", "additionalProperties": false, "required": [ "schemaVersion", "tool", "computedAt", "inputs", "summary", "result", "units", "assumptions", "sources", "warnings", "presentation", "links" ], "properties": { "schemaVersion": { "type": "string", "const": "1.0" }, "tool": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "version" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "version": { "type": "string" } } }, "computedAt": { "type": "string", "format": "date-time" }, "inputs": { "type": "object", "description": "Normalised inputs actually used, including applied defaults." }, "summary": { "type": "string" }, "result": { "type": "object", "additionalProperties": false, "required": [ "source", "query", "awards", "totals", "byBuyer", "byRecipient", "officialTotals", "awardCounts", "hasMore" ], "properties": { "source": { "type": "string", "enum": [ "usaspending", "ted", "pasted-usaspending", "pasted-ted" ] }, "query": { "type": [ "object", "null" ], "description": "Exact request sent to the API (null for pasted data)." }, "awards": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "id", "buyer", "subBuyer", "recipient", "amount", "currency", "startDate", "endDate", "description", "url" ], "properties": { "id": { "type": "string" }, "buyer": { "type": "string" }, "subBuyer": { "type": [ "string", "null" ] }, "recipient": { "type": "string" }, "amount": { "type": [ "number", "null" ] }, "currency": { "type": "string" }, "startDate": { "type": [ "string", "null" ] }, "endDate": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] } } } }, "totals": { "type": "object", "additionalProperties": false, "required": [ "awards", "withAmount", "currency", "amount", "otherCurrencies" ], "properties": { "awards": { "type": "integer" }, "withAmount": { "type": "integer" }, "currency": { "type": "string" }, "amount": { "type": "number" }, "otherCurrencies": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "currency", "amount", "count" ], "properties": { "currency": { "type": "string" }, "amount": { "type": "number" }, "count": { "type": "integer" } } } } } }, "byBuyer": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "name", "amount", "count" ], "properties": { "name": { "type": "string" }, "amount": { "type": "number" }, "count": { "type": "integer" } } } }, "byRecipient": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "name", "amount", "count" ], "properties": { "name": { "type": "string" }, "amount": { "type": "number" }, "count": { "type": "integer" } } } }, "officialTotals": { "type": [ "object", "null" ], "description": "USAspending spending_by_category totals over ALL matching transactions in the period (not just the listed awards).", "additionalProperties": false, "required": [ "byAgency", "byRecipient" ], "properties": { "byAgency": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "name", "amount" ], "properties": { "name": { "type": "string" }, "amount": { "type": "number" } } } }, "byRecipient": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "name", "amount" ], "properties": { "name": { "type": "string" }, "amount": { "type": "number" } } } } } }, "awardCounts": { "type": [ "object", "null" ], "additionalProperties": { "type": "integer" } }, "hasMore": { "type": "boolean" } } }, "units": { "type": "object", "additionalProperties": { "type": "string" } }, "assumptions": { "type": "array", "items": { "type": "string" } }, "sources": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "title" ], "properties": { "title": { "type": "string" }, "url": { "type": "string" }, "publisher": { "type": "string" }, "retrievedAt": { "type": "string" }, "note": { "type": "string" } } } }, "warnings": { "type": "array", "items": { "type": "string" } }, "presentation": { "type": "array", "items": { "type": "object" }, "description": "Display blocks used by the human page (same data)." }, "links": { "type": "object", "additionalProperties": false, "required": [ "human", "api", "openapi", "methodology" ], "properties": { "human": { "type": "string", "format": "uri" }, "api": { "type": "string", "format": "uri" }, "openapi": { "type": "string", "format": "uri" }, "methodology": { "type": "string", "format": "uri" } } } } } } } }