Permits

Search US building permits for an address

Search building-permit index records for one US street address through the Shovels source (v2). Supply address={formatted or line1+city,country:US}; permit_from/permit_to bound the permit date window (defaults: ten years back to today) and limit bounds returned records (default10). The source resolves the address to its geo_id then returns indexed jurisdiction filings; each returned record bills provider usage, checked against the configured run allowance. Success costs50 credits and stores one account-owned prop_shovels_ observation24h; retained property/record/permit reads1, errors/replay0. Permits are provider-indexed filings, not a complete permit history, title or contractor verification; coverage varies by jurisdiction. Source: Shovels pay-per-record API. Documentation-backed beta; not fresh live-source verification.

POST

permits

curl --request POST \
  --url https://api.example.com/v1/permits/search \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "address": {
    "formatted": "<string>",
    "country": "<string>"
  }
}
'

import requests

url = "https://api.example.com/v1/permits/search"

payload = { "address": {
        "formatted": "<string>",
        "country": "<string>"
    } }
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({address: {formatted: '<string>', country: '<string>'}})
};

fetch('https://api.example.com/v1/permits/search', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "data": [
    {
      "id": "<string>",
      "property_id": "<string>",
      "source": {
        "platform": "<string>",
        "provider": "<string>",
        "observed_at": "2023-11-07T05:31:56Z",
        "access_class": "public_portal",
        "country": "<string>",
        "native_id": "<string>",
        "url": "<string>",
        "source_updated_at": "2023-11-07T05:31:56Z",
        "retrieved_at": "2023-11-07T05:31:56Z"
      },
      "permit_number": "<string>",
      "permit_type": "<string>",
      "description": "<string>",
      "status": "<string>",
      "jurisdiction": "<string>",
      "event_dates": {
        "filed": "2023-12-25",
        "issued": "2023-12-25",
        "started": "2023-12-25",
        "ended": "2023-12-25",
        "finaled": "2023-12-25"
      },
      "durations_days": {
        "total": 123,
        "construction": 123,
        "approval": 123
      },
      "inspection_pass_rate": 123,
      "job_value": {
        "amount": "<string>",
        "currency": "<string>",
        "kind": "asking",
        "min": "<string>",
        "max": "<string>",
        "unit_code": "<string>",
        "period": "night",
        "per_area_unit": "<string>",
        "display_text": "<string>"
      },
      "fees": {
        "amount": "<string>",
        "currency": "<string>",
        "kind": "asking",
        "min": "<string>",
        "max": "<string>",
        "unit_code": "<string>",
        "period": "night",
        "per_area_unit": "<string>",
        "display_text": "<string>"
      },
      "tags": [
        "<string>"
      ],
      "contractor_id": "<string>"
    }
  ],
  "meta": {
    "request_id": "<string>",
    "schema_version": "<string>",
    "generated_at": "2023-11-07T05:31:56Z",
    "completeness": "complete",
    "sources": [
      {
        "platform": "<string>",
        "status": "success",
        "provider": "<string>",
        "error_code": "<string>",
        "truncated": true,
        "observed_at": "2023-11-07T05:31:56Z"
      }
    ],
    "warnings": [
      {
        "code": "<string>",
        "message": "<string>",
        "field": "<string>"
      }
    ],
    "pagination": {
      "next_cursor": "<string>",
      "has_more": true,
      "returned": 123,
      "total": 123,
      "total_relation": "exact"
    },
    "property_groups": [
      {
        "property_id": "<string>",
        "listing_ids": [
          "<string>"
        ],
        "match_method": "<string>",
        "status": "matched",
        "confidence": 123
      }
    ]
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "details": [
      {
        "platform": "<string>",
        "status": "success",
        "provider": "<string>",
        "error_code": "<string>",
        "truncated": true,
        "observed_at": "2023-11-07T05:31:56Z"
      }
    ]
  },
  "request_id": "<string>"
}

Search building-permit index records for one US street address through the Shovels pay-per-record source (v2). Supply address={formatted:...} or address={line1,city,region or postal_code,country:\"US\"}; optional permit_from/permit_to bound the permit date window (default: ten years back to today) and limit caps returned records (default10). Success costs50 credits and stores one account-owned prop_shovels_ observation for24 hours; retained property, record and permit reads cost1 credit each, errors/no-match0. The source first resolves the address to a provider geo_id, then returns indexed jurisdiction permit filings with file/issue/start/end/final dates, status, job value, fees, tags and contractor id. Provider usage bills per returned record, so the requested window is also bounded by the configured run allowance. Permits are provider-indexed filings — not a complete permit history, title, contractor verification or code-compliance proof; coverage varies across ~20k US jurisdictions and absence of records does not establish absence of work. This binding is documentation-backed beta.

Check live capabilities before calling this operation.

Requires SHOVELS_API_KEY, SHOVELS_PLAN_CONFIRMED and a bounded REALTYCRAWL_SHOVELS_RUN_MAX_USD.

Authorizations

x-api-key

string

header

required

Query Parameters

fields

string

Response-only comma-separated field paths relative to data items; up to 32 paths. Source requests and billing are unchanged.

Maximum string length: 4127

format

enum<string>

default:json

Response-only export format. JSON retains the envelope; CSV/NDJSON contain data records, with request/credit metadata in headers. Errors stay JSON.

Available options:

json,

csv,

ndjson

Body

application/json

address

object

required

Option 1
Option 2

Show child attributes

permit_from

string<date>

Earliest permit start date (file/issue/start); defaults to ten years before today.

permit_to

string<date>

Latest permit end bound; defaults to today.

limit

integer

default:10

Maximum permit records to return; each returned record bills provider usage, so the effective bound is also allowance-capped.

Required range: 1 <= x <= 100

Response

Successful response; meta discloses source completeness

data

object[]

required

Show child attributes

meta

object

required

Show child attributes

Search US building permits for an address

curl --request POST \
  --url https://api.example.com/v1/permits/search \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "address": {
    "formatted": "<string>",
    "country": "<string>"
  }
}
'

import requests

url = "https://api.example.com/v1/permits/search"

payload = { "address": {
        "formatted": "<string>",
        "country": "<string>"
    } }
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({address: {formatted: '<string>', country: '<string>'}})
};

fetch('https://api.example.com/v1/permits/search', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "data": [
    {
      "id": "<string>",
      "property_id": "<string>",
      "source": {
        "platform": "<string>",
        "provider": "<string>",
        "observed_at": "2023-11-07T05:31:56Z",
        "access_class": "public_portal",
        "country": "<string>",
        "native_id": "<string>",
        "url": "<string>",
        "source_updated_at": "2023-11-07T05:31:56Z",
        "retrieved_at": "2023-11-07T05:31:56Z"
      },
      "permit_number": "<string>",
      "permit_type": "<string>",
      "description": "<string>",
      "status": "<string>",
      "jurisdiction": "<string>",
      "event_dates": {
        "filed": "2023-12-25",
        "issued": "2023-12-25",
        "started": "2023-12-25",
        "ended": "2023-12-25",
        "finaled": "2023-12-25"
      },
      "durations_days": {
        "total": 123,
        "construction": 123,
        "approval": 123
      },
      "inspection_pass_rate": 123,
      "job_value": {
        "amount": "<string>",
        "currency": "<string>",
        "kind": "asking",
        "min": "<string>",
        "max": "<string>",
        "unit_code": "<string>",
        "period": "night",
        "per_area_unit": "<string>",
        "display_text": "<string>"
      },
      "fees": {
        "amount": "<string>",
        "currency": "<string>",
        "kind": "asking",
        "min": "<string>",
        "max": "<string>",
        "unit_code": "<string>",
        "period": "night",
        "per_area_unit": "<string>",
        "display_text": "<string>"
      },
      "tags": [
        "<string>"
      ],
      "contractor_id": "<string>"
    }
  ],
  "meta": {
    "request_id": "<string>",
    "schema_version": "<string>",
    "generated_at": "2023-11-07T05:31:56Z",
    "completeness": "complete",
    "sources": [
      {
        "platform": "<string>",
        "status": "success",
        "provider": "<string>",
        "error_code": "<string>",
        "truncated": true,
        "observed_at": "2023-11-07T05:31:56Z"
      }
    ],
    "warnings": [
      {
        "code": "<string>",
        "message": "<string>",
        "field": "<string>"
      }
    ],
    "pagination": {
      "next_cursor": "<string>",
      "has_more": true,
      "returned": 123,
      "total": 123,
      "total_relation": "exact"
    },
    "property_groups": [
      {
        "property_id": "<string>",
        "listing_ids": [
          "<string>"
        ],
        "match_method": "<string>",
        "status": "matched",
        "confidence": 123
      }
    ]
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "details": [
      {
        "platform": "<string>",
        "status": "success",
        "provider": "<string>",
        "error_code": "<string>",
        "truncated": true,
        "observed_at": "2023-11-07T05:31:56Z"
      }
    ]
  },
  "request_id": "<string>"
}

Overview

Meta

Listings

Platform listings

Properties

Buildings

Developments

Agents

Agencies

Auctions

Markets

Stays

Locations

Jobs

Observations

Addresses

Permits

Search US building permits for an address

Authorizations

Query Parameters

Body

Response