Fetch Shovels data with one API

Search building-permit index records for one US street address through the Shovels pay-per-record API (v2): a provider address match resolves a geo_id, then indexed jurisdiction filings return with dates, status, job value, fees, tags and contractor id. Permits are provider-indexed filings — not a complete permit history, title, contractor verification or code-compliance proof; coverage varies across ~20k jurisdictions. Documentation-backed beta.

Read the docs How it works Try a request

What Shovels endpoints does RealtyCrawl ship?

Search supported Shovels listings and read retained observations with source identifiers, typed values and collection times. The catalog lists source detail and specialist operations separately. Each endpoint has a documented request, response schema, and credit cost.

Read a saved permit property

1 credits

GET /v1/properties/{property_id}

Read your account’s saved permit-search property observation.

property_id

Read a saved permit record

1 credits

GET /v1/properties/{property_id}/records

Read the address-resolution record saved with your permit-search property.

property_id

Search building permits for an address

50 credits

POST /v1/permits/search

Search Shovels building-permit index records for one resolved US street address.

address

Read saved building permits

1 credits

GET /v1/properties/{property_id}/permits

Read the permit observations saved with your Shovels property.

property_id

Check live capabilities for operation and market availability. Unavailable requests are not charged.

Checking current source coverage…

Source request · Fetches the source through the enabled adapter.

Shovels API

4 endpoints documented

View docs

POST/v1/permits/searchGet API key

address

curl -X POST 'https://realtycrawl.dev/v1/permits/search' \
  -H "x-api-key: $REALTYCRAWL_API_KEY" \
  -H 'X-Max-Credits: 50' \
  -H "Idempotency-Key: YOUR_IDEMPOTENCY_KEY" \
  -H "content-type: application/json" \
  -d '{"address":{"formatted":"123 Example Street, Austin, TX","country":"US"}}'

API key required

// Live requests require a RealtyCrawl API key.
// Copy the request to your backend and set REALTYCRAWL_API_KEY.
// Check source and operation availability before running a request.

How the Shovels API works

Integrate a source-linked real estate API with standard HTTP requests, one API key, and structured JSON responses.

Authenticate every call

Send your RealtyCrawl API key in the x-api-key header. Keep it in your server environment.

GET and POST requests

Use path and query parameters for GET requests. Send a JSON body for POST operations.

One credit system

Source requests cost 50 credits per successful call. Saved reads cost 1 credit per observation, including successful saved-batch items. Failed calls are refunded; usage and balance appear in the response headers.

JSON and data exports

JSON keeps data and meta together. Field projection and CSV/NDJSON exports are response options; export request and credit metadata stays in headers.

The usual integration chain

From a supported source operation to data in your application.

1CheckGET /v1/meta/capabilitiesConfirm coverage and accepted selectors.
2RequestPOST /v1/permits/searchSend the inputs for the selected operation.
3Readdata + metaInspect results, source outcomes, and warnings.
4ConnectYour applicationPreserve identifiers and observation times.

Request

curl --request POST 'https://realtycrawl.dev/v1/permits/search' \
  --header "x-api-key: $REALTYCRAWL_API_KEY" \
  --header 'X-Max-Credits: 50' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: YOUR_IDEMPOTENCY_KEY' \
  --data '{"address":{"formatted":"123 Example Street, Austin, TX","country":"US"}}'

Illustrative response

{
  "data": [{"id":"permit_shovels_4b825dc642cb6eb9a060e54bf8d69288","property_id":"prop_shovels_4b825dc642cb6eb9a060e54bf8d69288","source":{"platform":"shovels","provider":"shovels","country":"US","access_class":"licensed_feed","observed_at":"2026-01-01T12:00:00Z","retrieved_at":"2026-01-01T12:00:00Z","native_id":"prm_9f8e7d6c","url":null},"permit_number":"2024-118234","permit_type":"Residential - Solar Panel Installation","description":"INSTALL ROOF-MOUNTED PHOTOVOLTAIC SYSTEM 9.6 KW","status":"final","jurisdiction":"Bexar County","event_dates":{"filed":"2024-06-03","issued":"2024-06-14","started":"2024-07-01","ended":"2024-07-08","finaled":"2024-07-12"},"durations_days":{"total":39,"construction":7,"approval":11},"inspection_pass_rate":1,"job_value":{"amount":"18500","currency":"USD","kind":"unknown","period":"one_time","min":null,"max":null,"unit_code":null,"display_text":null},"fees":{"amount":"312","currency":"USD","kind":"unknown","period":"one_time","min":null,"max":null,"unit_code":null,"display_text":null},"tags":["solar","electrical","roof"],"contractor_id":"ctr_51d2e9f4"}],
  "meta": {
    "request_id": "example_request",
    "schema_version": "1.0.0",
    "generated_at": "2026-01-01T12:00:00Z",
    "completeness": "unknown",
    "sources": [
      {
        "platform": "shovels_permits",
        "status": "success"
      }
    ]
  }
}

What lands in data

Source context stays with the property observations.

Listing: id · native_id · transaction · status
Property: address · property_type · bedrooms · areas
Price: amount · currency · kind · period
Source: platform · provider · observed_at · access_class

Inside the gateway

One request keeps the source, operation, and result connected.

Operation selection

Your path selects the platform and operation. Capabilities describe accepted selectors and markets.

Source collection

The gateway routes supported requests to the configured source and records its outcome.

Contract normalization

Property attributes, prices, and units are mapped into a shared JSON schema.

Response metadata

Completeness, warnings, and source timestamps help your application interpret the result.

Billing rules that make evaluation clear

Source requests cost 50 credits per successful call. Saved reads cost 1 credit per observation, including successful saved-batch items.
500 signup trial credits
Failed calls are refunded
Usage in response headers
Set an X-Max-Credits budget
One key across the catalog

How we get the data

A source request becomes a structured observation, with its origin and collection time attached.

What your request targets

Shovels building permit records records through a supported listing operation. Catalog markets: United States.

How records are returned

Search returns normalized listing IDs for saved reads. Use URL or native-ID detail only where that source operation is documented and enabled.

What comes with each result

Operation-specific resource fields sit alongside source identifiers, collection times, and completeness metadata.

What an observation means

Collection time and source update time describe different events. Stored observations expire after 24 hours without triggering a fresh crawl.

SOURCE → SHARED SCHEMA

Listing identifier

→ source.native_id

Published asking price

→ price.amount + currency

Collection timestamp

→ source.observed_at

What this API
is used for

Source-linked data for property products and research.

documented operations

1–50

credits per call / batch item

property workflows

Search supported Shovels listings and read retained observations with source identifiers, typed values and collection times. The catalog lists source detail and specialist operations separately.

Coverage and field availability vary by source. Check capabilities before you start a workload.

What people build with the Shovels API

Turn building permit records observations into tools your team can use.

Use case examples

Connect one source to the tools and workflows you already use.

Search applications

REST · application backend

Search returns normalized listing IDs for saved reads. Use URL or native-ID detail only where that source operation is documented and enabled.

Research pipelines

JSON · notebooks · BI

Compare property observations with their currencies, area units, and timestamps.

Assistant workflows

MCP · tools · agents

Give an assistant supported data operations with explicit request budgets.

Make your first request

Choose an operation, supply its inputs, and send your API key from your backend.

Read a saved permit property

curl --request GET 'https://realtycrawl.dev/v1/properties/prop_shovels_4b825dc642cb6eb9a060e54bf8d69288' \
  --header "x-api-key: $REALTYCRAWL_API_KEY" \
  --header 'X-Max-Credits: 1'

Read a saved permit record

curl --request GET 'https://realtycrawl.dev/v1/properties/prop_shovels_4b825dc642cb6eb9a060e54bf8d69288/records' \
  --header "x-api-key: $REALTYCRAWL_API_KEY" \
  --header 'X-Max-Credits: 1'

Search building permits for an address

curl --request POST 'https://realtycrawl.dev/v1/permits/search' \
  --header "x-api-key: $REALTYCRAWL_API_KEY" \
  --header 'X-Max-Credits: 50' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: YOUR_IDEMPOTENCY_KEY' \
  --data '{"address":{"formatted":"123 Example Street, Austin, TX","country":"US"}}'

Read saved building permits

curl --request GET 'https://realtycrawl.dev/v1/properties/prop_shovels_4b825dc642cb6eb9a060e54bf8d69288/permits' \
  --header "x-api-key: $REALTYCRAWL_API_KEY" \
  --header 'X-Max-Credits: 1'

Shovels API

Same key as the rest of the catalog

Get an API key Read the docs ↗

Endpoints

What data does the Shovels API return?

JSON responses preserve the operation data and request metadata. Supported data operations also offer response field projection and CSV/NDJSON exports.

Read a saved permit property

Read your account’s saved permit-search property observation.

Read a saved permit record

Read the address-resolution record saved with your permit-search property.

Search building permits for an address

Search Shovels building-permit index records for one resolved US street address.

Read saved building permits

Read the permit observations saved with your Shovels property.

Comparison

How does RealtyCrawl structure Shovels data?

Keep the source context while using the same request and response conventions across your integration.

Source context and RealtyCrawl conventions
Your application needs	Source context	RealtyCrawl contract
Resource identity	Source-scoped resource identifier	Source reference and RealtyCrawl ID
Operation data	Source-specific fields and units	Typed resource schemas and explicit missing values
Freshness	Collection and update times	Explicit observation timestamps
Missing information	Source-dependent attributes	Nullable fields and field_status
Coverage	Operation and market availability	Live capabilities and source outcomes
Diagnostics	Source warnings and errors	Request IDs and completeness metadata
Authentication	A request to RealtyCrawl	One API key across supported platforms

FAQ

Have a question?
We got answers

Find answers to common questions about the Shovels API, credits, and coverage.

How do I start using the Shovels API?

Get a RealtyCrawl API key, check Shovels in /v1/meta/capabilities, and send a supported request from your backend with the x-api-key header.

Are all Shovels operations available?

The catalog describes request contracts. Live enablement, accepted location selectors, and supported markets are declared per operation in /v1/meta/capabilities. Check the exact operation before running a workload.

How much does a Shovels request cost?

Source requests cost 50 credits per successful call. Saved reads cost 1 credit per observation, including successful saved-batch items. Signup includes 500 trial credits. Failed calls are refunded. Read the credit headers for the charge and remaining balance.

Will every observation contain every field?

No. Data varies by source, market, and operation. Nullable fields and field_status distinguish missing, unsupported, restricted, and temporarily unavailable values. Keep response warnings with the result.

Is a stored observation a fresh source crawl?

Stored listing, media, and history observations expire after 24 hours and do not trigger a new crawl. Inspect observed_at, source_updated_at, and response metadata to understand the age of a record.

Is this an official Shovels API?

RealtyCrawl is an independent data API and is not affiliated with Shovels. Source availability and supported operations are declared in the capabilities endpoint.

Can I use the same key for another platform?

Yes. One RealtyCrawl API key authenticates supported operations across the catalog. Check capabilities when adding a platform because availability and accepted inputs vary.

Related APIs and tools

Explore more sources and build on the same RealtyCrawl integration.

RentCast API All platforms Unified property schema Quickstart MCP server

Fetch Shovels data with one API

What Shovels endpoints does RealtyCrawl ship?

Read a saved permit property

Read a saved permit record

Search building permits for an address

Read saved building permits

How the Shovels API works

Authenticate every call

GET and POST requests

One credit system

JSON and data exports

The usual integration chain

What lands in data

Inside the gateway

Operation selection

Source collection

Contract normalization

Response metadata

Billing rules that make evaluation clear

How we get the data

What your request targets

How records are returned

What comes with each result

What an observation means

What this APIis used for

property workflows

What people build with the Shovels API

Permit history screening

Work-type and cost signals

Use case examples

Search applications

Research pipelines

Assistant workflows

Make your first request

Same key as the rest of the catalog

What data does the Shovels API return?

Read a saved permit property

Read a saved permit record

Search building permits for an address

Read saved building permits

How does RealtyCrawl structure Shovels data?

Have a question?We got answers

Related APIs and tools

What this API
is used for

Have a question?
We got answers