Skip to main content
Fast, concise answers to the most frequently asked questions about Shovels.

​
Pricing & Plans

​
How much does Shovels cost?

Shovels Online and API pricing starts with a free tier. View current plans at app.shovels.ai. Enterprise Data License (EDL) pricing requires contacting sales@shovels.ai.

​
Is there a free trial?

Yes. Shovels Online free trials include access to the last 12 months of data. The API free trial includes 250 requests with access to the full historical dataset.

​
How do I cancel my subscription?

Log in at app.shovels.ai → Account Settings → Manage Subscription → Cancel in the Stripe billing portal. Access continues until the end of the billing period. See How to cancel.

​
What is Shovels’ refund policy?

Refunds are reviewed case-by-case for charges within the last 30 days. Email support@shovels.ai with your account email and charge details. See Refund Policy.

​
What can I do with Shovels data?

Internal business use: research, prospecting, lead generation, and product integration. You cannot upload it to ad platforms (Facebook, Google, etc.), resell, or redistribute it. See Data usage terms.

​
What’s the difference between API and EDL?

API: Best for lookups, integrations, and local lead lists. EDL: Best for bulk data analysis. Full dataset delivered to your data warehouse.

​
Charlie AI

​
What is Charlie AI?

Charlie is Shovels’ AI research agent at charlie.shovels.ai. Ask permit data questions in plain English and get instant answers — no filters, downloads, or code required. Uses your API credits. See What is Charlie AI?.

​
API Basics

​
What is my API limit?

The free trial includes 250 requests (each API call = 1 request, regardless of records returned). Paid plans use a credit system with custom credit limits where each record returned counts against your credits. Contact sales@shovels.ai for details.

​
How many records per API call?

Search endpoints return up to 100 records per page (default: 50). Detail endpoints accept up to 50 IDs per call.

​
How do API credits work?

Each record returned counts against your credits. A search returning 100 permits uses 100 credits; a single permit lookup uses 1 credit.

​
Where do I find my API key?

Log in at app.shovels.ai/profile-settings and find it in the API Key section.

​
What does a 422 error mean?

A required parameter is missing. Most commonly, you need to resolve an address to a geo_id first using the Address Search endpoint.

​
CLI (Command Line)

​
How do I install the CLI?

Run the install script: curl -LsSf https://shovels.ai/install.sh | sh. The script downloads the correct binary for your platform and installs it to ~/.shovels/bin. Add to PATH if needed.

​
How do I configure my API key?

Two options: (1) Environment variable: export SHOVELS_API_KEY=your-key, or (2) Config file (persistent): shovels config set api-key your-key. Verify with shovels config show.

​
What’s the difference between CLI and API?

The CLI wraps the Shovels REST API but handles authentication headers, cursor pagination, rate-limit retries, and credit tracking automatically. Use the CLI from terminals, shell scripts, or AI agents. Use the API directly for application integrations.

​
How do I get all results instead of just 50?

Use --limit all. The CLI automatically handles pagination and fetches up to 10,000 records by default (configurable with --max-records).

​
What commands are available?

Main commands: permits search, permits get, contractors search, contractors get, contractors permits, contractors employees, contractors metrics, addresses search, cities search, tags list, usage, config. Run shovels --help for full list.

​
Can I use the CLI with scripts and AI agents?

Yes. The CLI outputs JSON to stdout and errors to stderr with meaningful exit codes (0=success, 1=client error, 2=auth error, 3=rate limited, 4=credits exhausted, 5=server error). Perfect for piping to jq or scripting.

​
What does exit code 2 mean?

Exit code 2 is an authentication error—your API key is missing or invalid. Set it with shovels config set api-key YOUR_KEY or via the SHOVELS_API_KEY environment variable.

​
Data Coverage

​
What areas does Shovels cover?

Approximately 2,000 jurisdictions covering about 85% of the US population.

​
How far back does the data go?

At least 2010 for all jurisdictions. Many jurisdictions have data going back further.

​
How often is data updated?

Monthly. We add 5-10 million new records and 1-5 million status updates each month.

​
Why am I getting so few results?

Common causes: limited jurisdiction coverage, filters too narrow, recent permits not yet indexed (1–2 month lag), or limited digitization in the local jurisdiction. See Why am I getting so few results?.

​
Where does Shovels get its data?

Directly from jurisdictions through relationships with local governments, online permitting portals, and public records requests. We don’t purchase data from other vendors.

​
Permits

​
What is a geo_id?

A unique geographic identifier that can represent a state (CA), zip code (94103), city, county, or specific address. Use the Address Search API to get a geo_id.

​
What are the permit statuses?

  • in_review: Application submitted, awaiting approval
  • active: Approved, work can proceed
  • final: Completed, passed inspection
  • inactive: Stalled, expired, or abandoned

​
Why do some permits have no address?

New construction permits are often filed before official addresses exist. These permits have state and jurisdiction info but no address ID.

​
What’s the difference between permit ID and permit number?

Permit ID: Globally unique identifier generated by Shovels. Permit number: Assigned by the jurisdiction—may duplicate across different cities.

​
Decisions

​
What are Shovels Decisions?

Structured records of municipal zoning and land use decisions from city councils and planning boards across the US. Decisions give you earlier visibility into development activity—often months before permits are filed.

​
What types of decisions does Shovels track?

Four primary categories: Spot Rezoning (changes to specific properties), Area Rezoning (broader geographic changes), Zoning Code Modifications (changes to the rules themselves), and Special Use Permits (conditional approvals for specific activities).

​
How do Decisions relate to permits?

Decisions precede permits in the development lifecycle. A rezoning approval or special use permit typically comes weeks to months before the developer applies for building permits.

​
How early can I see projects with Decisions?

Depends on project complexity: 2-4 weeks for minor commercial renovations, 1-3 months for new homes, 3-6 months for multifamily, and 6-12 months for large commercial projects.

​
What information is in a decision record?

Property location and coordinates, zoning changes (previous and new), involved parties (applicant, owner, developer, representative), project value and lot size, allowed uses, a “why it matters” summary, and a link to the source meeting record.

​
Which plans include Decisions?

All of them. Decisions are included in the API free trial and in every paid plan at no additional charge. Decisions are currently in beta.

​
How do I query Decisions in the API?

Use the Search Decisions endpoint. It requires a date range (decision_from, decision_to) and a geo_id. To fetch specific records, use Get Decisions By ID with up to 50 IDs.

​
What’s the Decisions coverage?

At launch, Decisions covered 600+ cities and nearly 200,000 records—about half the jurisdictions where Shovels has permit coverage—and continues to expand. See the Coverage Dashboard.

​
Contractors

​
How is contractor data organized?

Each contractor has a unique contractor ID (deduplicated within each state). Related contractors share a group ID linking them to parent organizations.

​
What contact information is available?

Business name, address, phone numbers (primary and all known), email addresses, license numbers, and employee data (via API endpoint).

​
Are contractors deduplicated across states?

No. The same contractor operating in multiple states has separate IDs per state. National deduplication is in development.

​
Shovels Online

​
What can I do with the free trial?

Search permits and contractors, use filters, and explore the last 12 months of data. CSV downloads require a paid plan.

​
How does search work?

Searches use AND logic—results match ALL selected criteria. You can search by geography, date range, permit type, keywords, and more.

​
Enterprise (EDL)

​
What formats are available?

Parquet (preferred), CSV, or JSON. Typical delivery size is 15-20 GB.

​
Where can data be delivered?

Snowflake, BigQuery, Databricks, or as downloadable files.

​
How do I track new records in monthly deliveries?

Use the first_seen_date field. Records with first_seen_date after your last delivery are new.

​
Contact

​
How do I contact Shovels?