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 [email protected]
Is there a free trial? Yes. Free trials include access to the last 12 months of data and 250 API credits.
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 credit limit? The free trial includes 250 credits. Paid plans have custom limits—no hard rate limits are enforced, but we monitor usage. Contact [email protected]
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.
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.
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 approvalactive : Approved, work can proceedfinal : Completed, passed inspectioninactive : 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.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.
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) 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.
