{"uid":"cap_MI20eoIFI4fBGE0bUYkWu","slug":"shovels-api-building-permit-search-6bf71641","name":"Shovels API — Building Permit Search","description":"Pay-per-call access to the Shovels building-permits search API over x402 and MPP. Search US building permits by date, location, and contractor — no accounts, no subscriptions, pay per request.","url":"https://stable-shovels.dev/api/permits/search","method":"POST","headers":{},"bodySchema":{"type":"object","properties":{"size":{"type":"integer","maximum":100,"minimum":1,"description":"Records to return per page (1–100, default 50). Determines the price — each record returned costs one credit."},"cursor":{"type":"string","description":"Pagination cursor — pass the `next_cursor` from a prior page."},"geo_id":{"type":"string","minLength":1,"description":"Geographic filter: a state code (e.g. \"CA\"), a ZIP code, or a Shovels geolocation id (resolve one via the city/county/jurisdiction search endpoints)."},"permit_q":{"type":"string","maxLength":50,"description":"Substring search over permit text (max 50 chars)."},"permit_to":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Return permits that started on or before this date (YYYY-MM-DD)."},"permit_from":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Return permits that started on or after this date (YYYY-MM-DD)."},"permit_tags":{"type":"array","items":{"type":"string"},"description":"Filter by permit classification tags (e.g. \"solar\", \"roofing\"). Prefix a tag with '-' to exclude it."},"include_count":{"type":"boolean","description":"Include a `total_count` of matching permits (first page only)."},"permit_status":{"type":"array","items":{"type":"string"},"description":"Filter by permit status: one or more of final, in_review, inactive, active."},"property_type":{"type":"array","items":{"type":"string"},"description":"Filter by property type (e.g. \"residential\", \"commercial\")."},"contractor_name":{"type":"string","minLength":3,"description":"Filter by contractor name (min 3 chars)."},"contractor_license":{"type":"string","description":"Filter by contractor license number."},"permit_min_job_value":{"type":"number","minimum":0,"description":"Only return permits with at least this job value (USD)."},"permit_has_contractor":{"type":"boolean","description":"Only return permits that have an associated contractor."}}},"responseSchema":null,"example":null,"exampleRequest":null,"tags":["x402"],"displayCostAmount":"0.5","displayCostAsset":"USDC","priceDynamic":false,"priceHint":null,"priceStatus":"priced","priceSource":"settled","requiresHandshake":false,"reviewCount":1,"rating":{"score":"0.75","successRate":"1.00","reviews":1,"stars":"4.0","state":"rated"},"availabilityStatus":"unknown","priceObserved":null,"sessionDeposit":null,"pricing":{"kind":"static","summary":"$0.5/call","primary":{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.5","per":"call","confidence":"exact"},"accepted":[{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.5","per":"call","confidence":"exact"}]},"paymentMethods":[{"uid":"pm_tufJEvboM96pR95OJdoSl","protocol":"x402","methodType":"crypto","chain":"base","mode":"charge","costAmount":"0.5","costPer":"request","priority":0,"asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","unit":"request","depositMicros":null,"planRef":null}],"brandName":null,"brandSlug":null,"brandBaseUrl":null,"brandDocsUrl":null,"whatItDoes":"Search US building permits by date range, location, and contractor with pay-per-call pricing via x402/USDC","exampleAgentPrompt":"Search Shovels for building permits filed in Austin, Texas between January 1 and March 31 of 2024, filtered to permits pulled by roofing contractors.","exampleUseCases":[{"title":"Track competitor construction activity by location","prompt":"Search Shovels for all building permits filed in the Denver metro area over the last six months and show me which contractors pulled the most permits."},{"title":"Find active electrical contractors in a region","prompt":"Look up building permits on Shovels for electrical work filed in California's Bay Area zip codes 94301 through 94306 in the past year to identify contractors doing that type of work."},{"title":"Monitor renovation permits for real estate leads","prompt":"Search Shovels for residential renovation and remodeling permits filed in Miami-Dade County in the last 90 days and give me the contractor names and permit dates."}],"resultDescription":"Returns a list of matching US building permit records including permit dates, locations, contractor names, permit types, and related metadata for permits matching the specified date, location, and contractor filters.","failureModes":["Payment not included or insufficient USDC — returns HTTP 402 requiring x402 payment","Invalid or missing search parameters — returns 400 bad request","No permits found matching the filters — returns empty results set","Rate limiting or server overload — returns 429 or 503","Location not covered in Shovels dataset — returns empty or partial results"],"whenToPreferThis":"Use this endpoint when you need on-demand, no-subscription access to US building permit data and want to pay only per query. Ideal for agents that need occasional permit lookups without committing to a monthly plan, or for workflows where permit searches are infrequent. Best suited for searches scoped by geography, contractor, and date range.","instructions":null,"reviewSummary":null,"reviewSummaryHighlights":null,"reviewSummaryConcerns":null,"reviewSummaryGeneratedAt":null,"activationCount":3,"lastUsedAt":"2026-07-15T14:36:58.415Z","lastSuccessfullyRanAt":"2026-07-13T02:49:48.665Z","lastHealthCheckAt":"2026-09-15T12:41:56.866Z","isFirstParty":false}