Skip to main content
The Shovels add-on for Google Sheets adds six formulas that return building permit and contractor data from the Shovels API. Type a formula in a cell and the results fill the rows below it, ready for filters, pivot tables, and charts.
Sheets vs. CLI vs. API: The add-on calls the same Shovels REST API and uses the same API key and credits. Use it when your work happens in spreadsheets. Use the CLI for terminals, scripts, and AI agents, and the API for product integrations.

​
Install

Install Shovels from the Google Workspace Marketplace. The add-on is free to install. The formulas spend API credits from your Shovels plan. During the install, Google asks you to approve four permissions. The add-on needs them to write results into your spreadsheet, call the Shovels API, show its dialogs, and fetch results when someone edits the Sheet. See How do I install the add-on? for the full list. After the install, every Sheet has a Shovels menu under Extensions.

​
Set Your API Key

You need a Shovels API key. If you don’t have one, create a free account to get a key on the Free plan.
  1. Copy your key from the API key tab of your account.
  2. In your Sheet, choose Extensions → Shovels → Set API key…
  3. Paste the key and click OK.
Shovels API key dialog in Google Sheets The add-on checks the key and shows how many credits it has used this month. The key is saved in this Sheet, so you set it once per Sheet.
Everyone who can edit the Sheet spends your key’s credits when they add or change a Shovels formula. Share a Sheet that holds your key only with people who may use your credits. See How does the API key work?

​
Run Your First Formula

Type this formula in cell A1:
The cell shows Shovels: fetching… for a moment, then the permits for ZIP code 78701 in Austin, TX fill the Sheet, one permit per row, with a header row. Permits for ZIP code 78701 in Google Sheets
Type =SHOVELS in any cell to list the formulas. Once you pick one, Google Sheets describes each argument as you type it.

​
Narrow the Results

SHOVELS_PERMITS_BY_GEO takes four optional arguments after the location: a start date, an end date, a property type, and the maximum number of rows. This formula returns residential permits in 78701 from 2026:
Leave an argument empty to use its default. Type dates as text in quotation marks, or point to a cell that holds a date. A formula returns up to 2,500 permits unless you set the fifth argument.

​
The Six Formulas

See What formulas does the add-on provide? for every argument and default.

​
Next Steps