> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shovels.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Shovels for Google Sheets Quickstart Guide

> Install the Shovels add-on for Google Sheets, set your API key, and pull building permits into a spreadsheet with one formula.

**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.

> [!NOTE]
>
> **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](https://docs.shovels.ai/docs/shovels-cli-quickstart.md) for terminals, scripts, and AI agents, and the [API](https://docs.shovels.ai/docs/shovels-api-introduction.md) for product integrations.

## Install

Install **Shovels** from the [Google Workspace Marketplace](https://workspace.google.com/marketplace/app/shovels/946108628231). 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?](https://docs.shovels.ai/docs/knowledge-base/sheets/installation.md) 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](https://app.shovels.ai/login?mode=register) to get a key on the Free plan.

1. Copy your key from the [API key tab of your account](https://app.shovels.ai/account?tab=apikey).
2. In your Sheet, choose **Extensions → Shovels → Set API key…**
3. Paste the key and click **OK**.

![Shovels API key dialog in Google Sheets](https://mintcdn.com/shovelsai/NT_L31wVoo9Afh_e/assets/screenshots/sheets-api-key-dialog.png?fit=max\&auto=format\&n=NT_L31wVoo9Afh_e\&q=85\&s=4a5be7822ab49c5ae4ffc92cf185d929)

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.

> [!WARNING]
>
> 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?](https://docs.shovels.ai/docs/knowledge-base/sheets/api-key.md)

## Run Your First Formula

Type this formula in cell A1:

```
=SHOVELS_PERMITS_BY_GEO("78701")
```

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](https://mintcdn.com/shovelsai/NT_L31wVoo9Afh_e/assets/screenshots/sheets-permits-by-zip.png?fit=max\&auto=format\&n=NT_L31wVoo9Afh_e\&q=85\&s=dd49a01a7c88b2db8a149de38ef8be3e)

> [!TIP]
>
> 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:

```
=SHOVELS_PERMITS_BY_GEO("78701", "2026-01-01", , "residential")
```

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

| Formula | Returns |
| - | - |
| `SHOVELS_PERMITS_BY_GEO` | Permits for an address, a ZIP code, a state code, or a geo\_id |
| `SHOVELS_PERMITS_BY_CONTRACTOR` | Permits of one contractor, by Shovels contractor ID |
| `SHOVELS_CONTRACTOR` | One row of contractor details for a name and a state |
| `SHOVELS_CONTRACTOR_ID` | The Shovels ID of a contractor name in a state |
| `SHOVELS_COUNTY` | The geo\_id of a county, such as `"Harris, TX"` |
| `SHOVELS_ADDRESS` | The geo\_id of a street address |

See [What formulas does the add-on provide?](https://docs.shovels.ai/docs/knowledge-base/sheets/formulas.md) for every argument and default.

## Next Steps

* [Look up a list of contractors by name](https://docs.shovels.ai/docs/knowledge-base/sheets/contractor-lookups.md)
* [Get permits for an address, ZIP code, county, or state](https://docs.shovels.ai/docs/knowledge-base/sheets/permits-by-location.md)
* [Understand credits, caching, and refreshing](https://docs.shovels.ai/docs/knowledge-base/sheets/credits-and-refreshing.md)
* [Fix a cell that shows "fetching…" or an error](https://docs.shovels.ai/docs/knowledge-base/sheets/troubleshooting.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.