boringapi 0.1.0

Python SDK for the Boring API — U.S. building permit data

boringapi

Python SDK for the Boring API — U.S. building permit data. One API.

pip install boringapi

Quick start

from boringapi import BoringAPI

client = BoringAPI("bp_live_sk_...")

# List permits
permits = client.permits.list(state="CA", limit=10)
for permit in permits.data:
    print(permit.id, permit.status, permit.address.full)

# Get a single permit
permit = client.permits.get("pmt_abc123")

# Search
results = client.permits.search("solar panel installation")

# Nearby permits
nearby = client.permits.nearby(latitude=37.7749, longitude=-122.4194, radius_miles=0.5)

# Bulk fetch
permits = client.permits.bulk(["pmt_abc123", "pmt_def456"])

client.close()

Auto-pagination

Iterate through all results automatically:

for permit in client.permits.auto_paging_iter(state="CA", status="issued"):
    print(permit.permit_number)

Jurisdictions

jurisdictions = client.jurisdictions.list(state="CA")
jurisdiction = client.jurisdictions.get("jur_san_francisco")

Account

account = client.accounts.me()
usage = client.accounts.usage()

API keys

keys = client.keys.list()
new_key = client.keys.create(name="CI Pipeline")
print(new_key.key)  # Only shown once
client.keys.revoke("key_abc123")

Webhooks

webhook = client.webhooks.create(
    url="https://example.com/webhook",
    events=["permit.created", "permit.status_changed"],
)
print(webhook.secret)  # Save this for signature verification

webhooks = client.webhooks.list()
deliveries = client.webhooks.deliveries(webhook.id)
client.webhooks.delete(webhook.id)

Context manager

with BoringAPI("bp_live_sk_...") as client:
    permits = client.permits.list(state="TX")

Error handling

from boringapi._exceptions import NotFoundError, RateLimitError

try:
    permit = client.permits.get("pmt_nonexistent")
except NotFoundError as e:
    print(e.message)
except RateLimitError:
    print("Slow down!")

Configuration

client = BoringAPI(
    "bp_live_sk_...",
    base_url="https://api.boringapi.dev/v1",  # default
    timeout=30.0,                               # seconds, default
)