PropRaven Python SDK

The official Python client for the PropRaven property-intelligence API: US parcels with ownership, valuation, permits, deeds, risk and market data.

• Sync (PropRaven) and async (AsyncPropRaven) clients, Python 3.9+.
• One runtime dependency: httpx.
• Every response is typed as a TypedDict (plain dicts at runtime, no validation step).
• Automatic retries with Retry-After support, typed RFC 7807 errors, auto-pagination and webhook signature verification.

Documentation: developer hub · REST API v1 reference · hosted MCP server

Installation

pip install propraven

Quick start

from propraven import PropRaven

client = PropRaven()  # reads PROPRAVEN_API_KEY from the environment

parcel = client.parcels.get("37:119:12104406")
print(parcel.get("address"), parcel.get("owner_name"))

page = client.search.parcels(
    bounds={"north": 35.215, "south": 35.205, "east": -80.855, "west": -80.865},
    filters={"valueRange": {"min": 100_000}},
    limit=50,
)
print(page["total"], len(page["data"]))

Methods mirror the API: client.<namespace>.<method>(path_params..., **params). Path parameters are positional; query parameters, header parameters and JSON body fields are keyword arguments with their wire names (county_fips, min_value, ...). A keyword left as None is not sent. Every method also accepts extra_headers, extra_query, extra_body (body endpoints), timeout and max_retries.

Async

import asyncio
from propraven import AsyncPropRaven


async def main() -> None:
    async with AsyncPropRaven() as client:
        usage = await client.account.usage()
        async for row in client.deals.absentee_iter(county_fips="37119", max_items=100):
            print(row.get("parcel_id"))


asyncio.run(main())

Authentication

Pass api_key="pz_..." or set PROPRAVEN_API_KEY. The key is sent as Authorization: Bearer <key>. Keys start with pz_; the client warns (but still sends the request) when a key does not. The key is optional: key-optional endpoints work anonymously (100 calls a day per IP), and endpoints that need a key answer 401, raised as AuthenticationError.

Server-side only. API keys are secrets and the REST API sends no CORS headers, so use this SDK from servers, scripts and notebooks, never from code shipped to browsers or end-user devices.

Configuration

client = PropRaven(
    api_key="pz_...",                  # default: PROPRAVEN_API_KEY
    base_url="https://propraven.com",  # default: PROPRAVEN_BASE_URL or https://propraven.com
    timeout=60.0,                      # seconds or an httpx.Timeout; per request: timeout=...
    max_retries=2,                     # per request: max_retries=...
    default_headers={"X-Team": "ops"},
    http_client=None,                  # bring your own httpx.Client / httpx.AsyncClient
)

client.request("GET", "/api/v1/freshness") calls any endpoint directly with the same auth, retries and error handling.

Errors

Error responses are RFC 7807 problem documents. Each status maps to an exception class, all subclasses of propraven.APIError (itself a propraven.PropRavenError):

Every APIError has status, type, title, detail, code, errors (a list of {param, message}), request_id, headers and body; str(err) is "<status> <code>: <detail>". Network failures raise APIConnectionError, and timeouts raise its subclass APITimeoutError.

import propraven

try:
    client.deals.absentee(county_fips="37119", limit=0)
except propraven.BadRequestError as err:
    print(err.code, err.errors)  # invalid_parameter [{'param': 'limit', 'message': ...}]
except propraven.RateLimitError as err:
    print("retry in", err.retry_after)
except propraven.APIError as err:
    print(err.status, err.detail, err.request_id)

The SDK never signs x402 payments; a paid resource without payment raises PaymentRequiredError.

Retries

Requests are retried up to max_retries times (default 2) on network errors and timeouts and on 429, 503 and 504 for every HTTP method. Other 5xx responses are retried only for GET, HEAD, DELETE and OPTIONS. Other 4xx responses are never retried, 402 included.

The wait is Retry-After (seconds or an HTTP date) when present. Without it, the client waits until X-RateLimit-Reset when X-RateLimit-Remaining is 0, and otherwise backs off exponentially (0.5 s × 2^attempt, ±25 % jitter). One wait is capped at 60 s: if the server asks for longer (a monthly cap's Retry-After is measured in days), the error is raised at once.

Pagination

Every paginated method m has an auto-paginating sibling m_iter (a generator, or an async generator on AsyncPropRaven) that fetches pages on demand:

for parcel in client.deals.absentee_iter(county_fips="37119", page_size=100, max_items=1000):
    ...

for hit in client.search.full_iter(q="main st", page_size=50):  # cursor-paginated
    ...

Offset pagination advances offset by the page length. It stops on a short or empty page, when offset >= total, or when has_more is false. Cursor pagination (search.full) passes after=<nextCursor> until nextCursor is null or absent, or hasMore is false. page_size is sent as limit, and max_items caps the number of items returned.

Webhooks

Verify deliveries with the raw request body and the X-PropRaven-Signature header (t=<unix_ms>,v1=<hex hmac-sha256>, signed over "<t>.<raw body>" with your whsec_... secret):

from propraven import WebhookVerificationError
from propraven.webhooks import verify

try:
    event = verify(raw_body, headers["X-PropRaven-Signature"], secret)  # tolerance=300 s
except WebhookVerificationError:
    return 400
print(event["type"])

propraven.verify_webhook is an alias. Multiple v1= signatures are accepted (secret rotation), and signatures are compared in constant time.

Rate-limit info

client.last_rate_limit holds the X-RateLimit-Limit / -Remaining / -Reset headers of the most recent response as a RateLimit(limit, remaining, reset) (reset is a Unix epoch in seconds), or None when that response had none.

Types

Response and request shapes live in propraven.types, one TypedDict per schema in the OpenAPI spec, plus <Namespace><Method>Response for every operation (ParcelsPermitsResponse, SearchParcelsResponse, ...). They are plain dicts at runtime, so unknown keys pass through untouched. Numeric fields are typed as numbers, and identifiers (parcel_id, apn, county_fips, state_fips, zip) as strings. Responses that are CSV (search.export) are returned as str.

Methods

70 operations. Every method exists on both PropRaven and AsyncPropRaven; methods marked iter also have an auto-paginating <method>_iter(...) sibling.

Regenerating

The typed layer (src/propraven/types, src/propraven/resources, the table above) is generated from openapi.json:

curl -fsSL https://propraven.com/openapi.json -o openapi.json   # or copy a new spec in
python scripts/generate.py                                      # standard library only
python -m pytest -q

python scripts/generate.py --check fails when the generated files are stale. The Regenerate from OpenAPI workflow does this daily and opens a spec-sync pull request when the published spec changes.

License

Apache-2.0