houses-client 1.4.0

Python SDK for the Mayo Clinic HOUSES API

houses-client

Python SDK for the Mayo Clinic HOUSES API.

Requirements

Python 3.11+

Installation

pip install houses-client

Usage

Synchronous lookup (small batches up to 25 addresses)

from houses_client import HousesClient

client = HousesClient(
    api_endpoint="https://houses.konfidential.io",
    client_id="my oidc client id",
    client_secret="my oidc client secret",
)

result = client.lookup(
    addresses=[
        {"id": "1", "address": "123 Main St", "city": "Rochester", "state": "MN", "zip": "55905"},
        {"id": "2", "address": "456 Main St Anytown NY 55555"},
    ],
    year=2021,
)
print(result["results"])

Async batch (any size, file-based)

client.batch(
    input_path="myinput.csv",
    output_path="myoutput.csv",
    year=2021,
    delimiter=",",
)

Index metadata

client.metadata()  # available years and index versions

Self-hosted mode (no auth)

client = HousesClient(api_endpoint="http://localhost:9002", self_hosted=True)

Errors

The SDK raises typed exceptions you can catch:

Exception	Raised when
ConfigurationError	Missing required constructor arguments
AuthenticationError	OIDC login or token refresh fails
APIError	The API returns a non-2xx status (status_code, body)
TaskError	An async batch task reports ERROR status
HousesError	Base class for all of the above

from houses_client import HousesClient, APIError, TaskError

try:
    client.batch(input_path="in.csv", output_path="out.csv", year=2021)
except APIError as e:
    print(f"API failed: status={e.status_code}, body={e.body}")
except TaskError as e:
    print(f"Task failed: {e}")

Constructor options

Property	Type	Default	Description
api_endpoint	str	required	HOUSES API base URL
client_id	str	None	OIDC Client ID (required unless self_hosted=True)
client_secret	str	None	OIDC Client Secret (required unless self_hosted)
self_hosted	bool	False	Skip OIDC; uses anonymous auth
log_level	str	"INFO"	One of DEBUG, INFO, WARNING, ERROR
timeout	float	60.0	Per-request HTTP timeout in seconds

CLI

After installing, the houses-client console script is available:

houses-client \
    -e http://localhost:9002 \
    -i sample1.csv \
    -o sample1_output.csv \
    -y 2021 \
    -d , \
    --selfhosted

Run houses-client --help for the full option list.

Input data schema

Single-string address

id,address,year
1,"123 main st anytown ny 5555",2019
2,"456 main st anytown ny 55555",2018

The address string should include at least one of: city+state, city, state, or zip. The year column is optional and overrides the request-level year. Add a referenceAddress column to override per-row.

Component address

id,address,secondary,city,state,zip,year
1,"123 main st","Apt 4B","Anytown","NY","55555",2019

Build

python3 -m pip install --upgrade build
python3 -m build

The version is read from houses_client.__version__. Bump it in houses_client/__init__.py before building.