How Advanced Search works
The filter panel, the charts, the results table, and the shareable URL, call by call.
Advanced Search is the busiest page on usaspending.gov and the best map of the search API. Everything on it is driven by one filter object. The page builds that object as you pick filters, then sends the same object to several endpoints at once: one for each chart and one for each results tab.
The pattern to copy
- Build a single
filtersobject. The filter object page covers every key. - Ask for counts first with
spending_by_award_count. The site uses the counts to label its tabs and skip empty ones. - Request results one award group at a time with
spending_by_award, since contracts, grants, and loans return different columns. - Send the same filters to
spending_over_time,spending_by_category, andspending_by_geographyfor charts.
Sharing a search
A search URL on the site ends in a short hash. When you share a search, the page stores the filter object with references/filter and gets the hash back. Opening that URL later calls references/hash to turn it back into filters. You can use the same pair to save searches in your own app.
The calls, in order
On load, if the URL has a search hash
Turns the hash back into the saved filter object.
On load
The "data as of" date above the results.
While typing in the Agency filter
While typing in the Recipient filter
When the Product and Service Code tree opens
Each level of the tree is its own call.
After filters are applied
The counts on the Contracts, Grants, Loans, and other tabs.
For the results table
One call per tab, one page at a time.
For the Time chart
For the Categories chart
The site calls a category-specific path, such as spending_by_category/awarding_agency/.
For the Map
When you share or bookmark a search
Stores the filter object and returns the hash for the URL.
Sources
Traced from these files in the public usaspending-website repo: