Pricing & Plans
How much does Shovels cost?
Shovels Online and API pricing starts with a free tier. View current plans at shovels.ai/pricing. 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 → 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.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: 10). 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/account and find it on the API key tab.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, properties search, properties get, contractors search, contractors get, contractors permits, contractors employees, contractors metrics, decisions search, decisions get, addresses search, cities search, tags list, schema, usage, config. Run shovels --help for full list.
How do I query properties from the CLI?
Useshovels properties search (added in v0.8.0). It needs --geo-id, --legal-owner, or both — not both a geo and a date range like permits search. Example: shovels properties search --geo-id 92024 --permit-tags "-solar" --limit 10. See Querying properties from the CLI.
How do I find properties with no permit of a given type in the CLI?
Prefix the tag with- inside --permit-tags: --permit-tags "-solar". Combine presence and absence in one value, e.g. --permit-tags "roofing,-solar". Every absence row carries a trust object. See Absence searches and trust fields.
Why does my properties result have several trust_summaries?
Because each entry covers one API page.--limit 205 fetches three pages, so you get three summaries. The CLI deliberately doesn’t merge them — each rate is row-weighted over its own page, so averaging them would be wrong. Read the worst page instead: jq '[.meta.trust_summaries[].expected_miss_rate] | max'.
Why is there no —permit-to on properties search?
A property record keeps only the latest permit date per work type, so a closed date window can’t be answered correctly. Only “ever” and “since date D” (--permit-from) are expressible. Use shovels permits search for date windows.
How do I search one owner’s properties nationwide?
shovels properties search --legal-owner "INVITATION HOMES" — no --geo-id needed. Repeat the flag for up to 10 owners; values are never split on commas, so "SMITH, JOHN" stays one owner.
Why did properties get fail when only one ID was bad?
An ID that’s well-formed but unknown is fine — it’s omitted and listed inmeta.missing with exit 0. But an ID that can’t be decoded as an address ID, or a city/county/jurisdiction geo_id, fails the whole request with exit 1. Validate before batching 50.
How do I see a command’s response fields without spending credits?
shovels schema properties search prints every field with its type, unit, and description, plus a jq-ready field_index. It runs offline and needs no API key. --dry-run similarly prints the resolved HTTP request without calling the API.
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 tojq or scripting.
What does exit code 2 mean?
Exit code 2 is an authentication error—your API key is missing or invalid. Set it withshovels 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.Properties
What is the Properties API?
Two beta endpoints covering roughly 159 million US properties. Each record is one property with its permit history summarized on it: permit counts, work-type tags, latest activity dates, contractors, job values, and property attributes. See How to search for properties.How do I find properties with no permit of a given type?
Prefix the tag with- in permit_tags (e.g. permit_tags=-solar). Every absence answer carries trust fields—including the page-level expected_miss_rate—that tell you how confident the “no permit on record” claim is. See Absence search.
Can I search properties by a date window or “before” a date?
No. A property record keeps only the latest permit date per work type, so only “ever” and “since date D” queries are supported. For date windows or upper bounds, use Search Permits. See Properties vs Permits.Can I search properties by owner?
Yes—legal_owner is the one filter that works nationwide with no location. Pass up to 10 owner names to get their properties across the US.
Can I search properties by parcel number (APN)?
No. APN is returned on every record for mapping into your own systems, but it’s not searchable: APNs are county-specific, millions collide across counties, and about 30% of properties have none.Can I search properties by jurisdiction?
No. Jurisdiction is recorded on only a minority of property records, so scoping to it would silently drop properties that were never permitted. Jurisdiction geo_ids are rejected — scope by city, county, state, ZIP, or address instead.Why do my property attribute filters return nothing?
Attribute data (value, size, year, units, type) covers roughly 60-70% of properties, and a property with no value for an attribute never matches a range filter on it. Stacking several filters can empty a result that returns plenty of rows without them. Loosen or drop one filter at a time.Can I query properties from the CLI?
Yes, as of CLI v0.8.0:shovels properties search and shovels properties get. See Querying properties from the CLI.
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.What is Charlie?
Charlie is the AI agent inside Shovels Online, opened with the Agent button. Ask permit data questions in plain English instead of building a search with filters. Included on every plan, with usage limits that scale with your plan. See What is Charlie?.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 thefirst_seen_date field. Records with first_seen_date after your last delivery are new.
Contact
How do I contact Shovels?
- Support: support@shovels.ai
- Sales: sales@shovels.ai
- Phone: 1-800-511-7457
- Address: 3515 Mt. Diablo Blvd, Unit #51, Lafayette, CA 94549
Related Resources
- Full Glossary - Detailed term definitions
- API Reference - Complete API documentation
- Data Dictionary - Field definitions