[DEV-14890] - New Download/v2/search endpoint by DavidMikolaKC · Pull Request #4627 · fedspendingtransparency/usaspending-api

DavidMikolaKC · 2026-04-10T16:05:41Z

Description:

Currently the Advanced Search page allows for users to download either Awards with Subawards or Transactions with Subawards; never combining Awards and Transactions. A new endpoint is needed to support a new download modal that allows users to select which of the three they want. The /api/v2/download/search endpoint will power the downloads on the Advanced Search page and support Awards, Transactions, and Subawards.

Technical Details:

Requirements for PR Merge:

Unit & integration tests updated
API documentation updated (examples listed below)
1. API Contracts
2. API UI
3. Comments
Data validation completed (examples listed below)
1. Does this work well with the current frontend? Or is the frontend aware of a needed change?
2. Is performance impacted in the changes (e.g., API, pipeline, downloads, etc.)?
3. Is the expected data returned with the expected format?
Appropriate Operations ticket(s) created
Jira Ticket(s)
1. DEV-14890

Explain N/A in above checklist:

…pending-api into ftr/dev-14890-new-download-search-endpoint

zachflanders-frb

This is looking good to me. I just have one comment about finishing up the api docs by linking to where this filter object is already defined in our docs.

zachflanders-frb

👍 LGTM

sethstoudenmier

Looks good! My comments are all related to some cleanup.

sethstoudenmier · 2026-04-17T19:00:12Z

+                + `tsv`
+                + `pstxt`
+        + `limit` (optional, number)
+        + `spending_level` (optional, enum[string])


Suggested change

+ `spending_level` (optional, enum[string])

+ `spending_level` (optional, array[enum[string]])

I believe this will pass Dredd tests for the API blueprint. This spending_level filter is slightly different from other examples because it allows multiple selections instead of a single choice.

sethstoudenmier · 2026-04-17T19:01:12Z

+                + `subawards`
+                + `transactions`
+                + `awards`
+            + Default: `transactions`


Suggested change

+ Default: `transactions`

+ Default: `["transactions"]`

Not sure about this syntax, but this is also different because it is an array of values

This default value is not accurate to the tinyshield model in the implementation: "default": ["awards", "transactions", "subawards"],

sethstoudenmier · 2026-04-17T19:02:33Z

+                    "columns": [
+
+                    ],
+                    "download_types": [
+
+                    ],
+                    "file_format": "csv",
+                    "filters": {
+
+                    },


I would update this to reflect the values in your example request above

sethstoudenmier · 2026-04-17T19:57:14Z

 |[/api/v2/download/disaster/recipients/](/api/v2/download/disaster/recipients/)|POST| Returns a zipped file containing Disaster Recipient Funding data |
 |[/api/v2/download/idv/](/api/v2/download/idv/)|POST| Returns a zipped file containing IDV data |
 |[/api/v2/download/status/](/api/v2/download/status/)|GET| gets the current status of a download job that that has been requested with the `v2/download/awards/` or `v2/download/transaction/` endpoint that same day |
+|[/api/v2/download/search/](/api/v2/download/search/)|POST|Generates zip file for download of award data in CSV format, both awards and transactions |


Two things here:

Can you move this above the /api/v2/download/status/ line for alphabetical order?

I would call out in the description that this allows you to download data for Awards, Subawards, and Transactions

sethstoudenmier · 2026-04-17T20:03:02Z


+        self._json_request["filters"] = final_award_filters
+
+    def _update_custom_award_filters(self, custom_award_filters: dict, filter_all_agencies: bool) -> list:


Won't block on this, but since this function specifically updates the filters for the purpose of agencies, I would have that reflected in the name.

sethstoudenmier · 2026-04-17T20:05:26Z

    re_path(r"^idv", views.RowLimitedIDVDownloadViewSet.as_view()),
    re_path(r"^status", DownloadStatusViewSet.as_view()),
    re_path(r"^transactions", views.RowLimitedTransactionDownloadViewSet.as_view()),
+    re_path(r"^search", views.SearchDownloadViewSet.as_view())


Can you add this above the status endpoint to preserve alphabetical order?

sethstoudenmier · 2026-04-17T20:05:58Z

+
+class SearchDownloadViewSet(BaseDownloadViewSet):
+    """
+    This route sends a request to begin generating a zip file that combines award and transaction data


Suggested change

This route sends a request to begin generating a zip file that combines award and transaction data

This route sends a request to begin generating a zip file that combines award, transaction, and subaward data

[DEV-14890] - Created initial Search Endpoint Functionality

3a2e17d

DavidMikolaKC added the do not merge [PR] shouldn't be merged label Apr 10, 2026

github-actions bot assigned DavidMikolaKC Apr 10, 2026

[DEV-14890] - Added Initial Test Cases for Search Branch

6cf72b1

DavidMikolaKC changed the title ~~[DEV-14890] - Created initial Search Endpoint Functionality~~ [DEV-14890] - New Download/v2/search endpoint Apr 14, 2026

DavidMikolaKC marked this pull request as ready for review April 14, 2026 15:10

DavidMikolaKC added 14 commits April 14, 2026 12:30

[DEV-14890] - Ruff Syntax Checks

425fe33

Fixed Endpoint doc url

207e5f4

Fixed Endpoint doc url for real

aebe46b

Added search endpoint link to markdown doc

11211a5

Fixed inccorect function call typo

e4ba41a

Updated default spending level interpretation

c5bd329

Fixed ruff check

51eaf23

Changed how download types are defined in search endpoint

e292dd4

Fixed Ruff issues

30fdab4

[DV-14890] - Fixed adding download types to search post request

f30cdf5

Appeasing the lint check

16ffa1e

Merge branch 'qat' of https://github.com/fedspendingtransparency/usas…

807b83b

…pending-api into ftr/dev-14890-new-download-search-endpoint

Added datasource test case

a372995

Ruff lint fixes

20c902e

zachflanders-frb reviewed Apr 16, 2026

View reviewed changes

Comment thread usaspending_api/api_contracts/contracts/v2/download/search.md

github-actions bot assigned zachflanders-frb Apr 16, 2026

DavidMikolaKC added 6 commits April 16, 2026 15:52

[dev-14890] - Updated search.md api contract

c285432

[DEV-14890] - Expanded Filters Fields in API Contract

5b681e8

[DEV-14890] - Fixed Syntax Error in Filters Fields in API Contract

529011e

Dredd check

125887c

Updated search timeperiods description

d44b8d0

Reformatted search download time period block

9b5c9aa

DavidMikolaKC removed the do not merge [PR] shouldn't be merged label Apr 17, 2026

zachflanders-frb previously approved these changes Apr 17, 2026

View reviewed changes

Merge branch 'qat' into ftr/dev-14890-new-download-search-endpoint

8088c80

sethstoudenmier requested changes Apr 17, 2026

View reviewed changes

github-actions bot assigned sethstoudenmier Apr 17, 2026

[DEV-14890] - Code Reviews for Pull Request

cef3286

DavidMikolaKC dismissed zachflanders-frb’s stale review via cef3286 April 17, 2026 20:45

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[DEV-14890] - New Download/v2/search endpoint#4627

[DEV-14890] - New Download/v2/search endpoint#4627
DavidMikolaKC wants to merge 24 commits intoqatfrom
ftr/dev-14890-new-download-search-endpoint

DavidMikolaKC commented Apr 10, 2026 •

edited by atlassian bot

Loading

Uh oh!

zachflanders-frb left a comment

Uh oh!

Uh oh!

zachflanders-frb left a comment

Uh oh!

sethstoudenmier left a comment

Uh oh!

sethstoudenmier Apr 17, 2026

Uh oh!

sethstoudenmier Apr 17, 2026

Uh oh!

sethstoudenmier Apr 17, 2026

Uh oh!

sethstoudenmier Apr 17, 2026

Uh oh!

sethstoudenmier Apr 17, 2026

Uh oh!

sethstoudenmier Apr 17, 2026

Uh oh!

sethstoudenmier Apr 17, 2026

Uh oh!

sethstoudenmier Apr 17, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

	+ `spending_level` (optional, enum[string])
	+ `spending_level` (optional, array[enum[string]])


		self._json_request["filters"] = final_award_filters

		def _update_custom_award_filters(self, custom_award_filters: dict, filter_all_agencies: bool) -> list:

	This route sends a request to begin generating a zip file that combines award and transaction data
	This route sends a request to begin generating a zip file that combines award, transaction, and subaward data

Conversation

DavidMikolaKC commented Apr 10, 2026 • edited by atlassian bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description:

Technical Details:

Requirements for PR Merge:

Explain N/A in above checklist:

Uh oh!

zachflanders-frb left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

zachflanders-frb left a comment

Choose a reason for hiding this comment

Uh oh!

sethstoudenmier left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

DavidMikolaKC commented Apr 10, 2026 •

edited by atlassian bot

Loading