Types

property_radar.types

Shared public typing contracts for PropertyRadar requests and responses.

Criterion

Bases: _RequiredCriterion

A generic PropertyRadar criteria object.

Criterion-specific values evolve independently in the vendor catalog, so this type preserves that value while enforcing the stable object shape.

ResponseEnvelope

Bases: TypedDict

Stable fields shared by documented PropertyRadar response envelopes.

StatusLabelsResponse

Bases: TypedDict

Response shapes selected by the status-label Layout parameter.

ImportItem

Bases: TypedDict

One item accepted by the list import matching endpoint.

Transaction history

The transaction-history module exposes the immutable field contract, structured current-owner identity model, provider limitations, billing evidence, and strict parser. Package-root imports are supported for every public symbol.

property_radar.transaction_history

Immutable typed parsing for PropertyRadar transaction-history responses.

TRANSACTION_HISTORY_FIELDS: tuple[TransactionHistoryField, ...] = ('DocTypeUI', 'Status', 'Purpose', 'LoanPosition', 'DocNumber', 'RecDate', 'Grantor', 'Grantee', 'Amount', 'LTVorDown', 'hasDocumentImage', 'isFirstCurrentOwnerRecord', 'isParentType', 'DocumentID') module-attribute

Official ordered positive fields for properties.transactions.

PROPERTY_PERSON_IDENTITY_FIELDS: tuple[PropertyPersonIdentityField, ...] = ('RadarID', 'PersonKey', 'PersonType', 'FirstName', 'MiddleName', 'LastName', 'Suffix', 'EntityName', 'OwnershipRole') module-attribute

Official fields for the bounded property-current-owner composition.

TRANSACTION_HISTORY_CONTRACT = _freeze_mapping({None: _CONTRACT_FINGERPRINT_SOURCE, 'contract_fingerprint': _fingerprint_contract(_CONTRACT_FINGERPRINT_SOURCE)}) module-attribute

Deeply immutable official schema catalog and strict parser policy.

TransactionParty dataclass

One structured provider identity without invented name information.

aliases is None for the current provider contract because no alias field is documented. A tuple remains available for a future provider-supplied alias source without conflating unavailable with empty.

__post_init__() -> None

Reject mutable or malformed identity containers.

__repr__() -> str

Return metadata only, never names or provider identifiers.

TransactionBillingEvidence dataclass

Immutable billing evidence for one transaction-history response.

__post_init__() -> None

Reject mutable or contradictory manually constructed evidence.

__repr__() -> str

Return non-personal billing metadata without the request identifier.

TransactionHistoryRecord dataclass

One immutable transaction with opaque group displays.

The official endpoint does not expose individual party boundaries. grantors and grantees are therefore None for parsed provider records, while the exact scalar displays remain available separately. The tuple-capable fields allow future structured provider parties without constraining either side to zero-or-one.

__post_init__() -> None

Reject mutable party and field containers.

__repr__() -> str

Return shape metadata without record values or party names.

TransactionHistory dataclass

Immutable transactions, current-owner identities, and billing evidence.

current_owners is None when no property-person response was composed, an empty tuple when the provider returned no owners, and an ordered tuple otherwise. These identities are property-level evidence and are deliberately not attached to a particular transaction party.

total_cost: Decimal property

Return the quoted or returned provider cost.

quantity_free_remaining: int | None property

Return preview-only free quantity when supplied.

result_count: int property

Return the provider result count.

total_result_count: int property

Return the non-paginated result count compatibility view.

purchase_requested: bool | None property

Return the known request purchase flag, or None.

billing_status: TransactionBillingStatus property

Return preview, charged, or unknown request status.

currency: str | None property

Return provider currency, currently unavailable.

request_id: str | None property

Return a sanitized official request identifier when available.

__post_init__() -> None

Reject mutable record and identity containers.

__repr__() -> str

Return aggregate metadata without licensed record values.

parse_transaction_history(envelope: Mapping[str, object], *, purchase_requested: bool | None = None, property_persons: Mapping[str, object] | None = None, radar_id: str | None = None, request_id: str | None = None) -> TransactionHistory

Parse official transaction and optional property-person envelopes.

The parser never infers party boundaries from Grantor or Grantee. When property_persons is supplied, its ordered identities are exposed separately as current-owner evidence after every returned RadarID is checked against radar_id.

Parameters:

Name	Type	Description	Default
envelope	Mapping[str, object]	Decoded JSON returned by properties.transactions when requesting :data:TRANSACTION_HISTORY_FIELDS.	required
purchase_requested	bool | None	The request's exact Purchase choice. Use None for a detached response whose request context is unknown.	None
property_persons	Mapping[str, object] | None	Optional decoded response from properties.persons using :data:PROPERTY_PERSON_IDENTITY_FIELDS.	None
radar_id	str | None	Exact property identifier used for both requests. Required when property_persons is supplied.	None
request_id	str | None	Official correlation identifier when a success response source supplies one. Unsafe shapes are discarded.	None

Returns:

Type	Description
TransactionHistory	Immutable transaction records, optional ordered current-owner
TransactionHistory	identities, and typed billing evidence.

Raises:

Type	Description
InvalidResponseError	If either envelope violates the bound contract.

Buyer-transfer match

The buyer-transfer module exposes a fixed request scope, immutable property/location and broad property-type evidence, explicit provider limitations, billing evidence, and a strict zero-or-one parser.

property_radar.buyer_transfer

Typed buyer/grantee search linkage with immutable property location.

BUYER_TRANSFER_PROPERTY_FIELDS: tuple[BuyerTransferPropertyField, ...] = ('RadarID', 'PType', 'Address', 'City', 'State', 'ZipFive', 'County', 'FIPS', 'APN', 'Latitude', 'Longitude') module-attribute

Ordered public fields requested for one buyer-transfer property match.

BUYER_TRANSFER_MATCH_CONTRACT = _freeze_mapping({None: _CONTRACT_FINGERPRINT_SOURCE, 'contract_fingerprint': _fingerprint_payload(_CONTRACT_FINGERPRINT_SOURCE)}) module-attribute

Deeply immutable buyer-transfer linkage and parser contract.

BuyerTransferMatchCriteria dataclass

Bounded criteria for linking one buyer/grantee query to one property.

__post_init__() -> None

Validate exact caller-normalized criteria and bounded windows.

__repr__() -> str

Return query-shape metadata without names or property identity.

BuyerTransferProperty dataclass

One immutable property identity and location returned for the match.

is_residential: bool | None property

Classify the documented broad property type without guessing Unknown.

__post_init__() -> None

Validate immutable field order and documented primitive shapes.

__repr__() -> str

Return completeness metadata without property values.

BuyerTransferLinkage dataclass

Provider evidence that one Buyer criterion returned one property.

__post_init__() -> None

Validate scope identity and explicit unavailable linkage fields.

__repr__() -> str

Return linkage shape without identity or fingerprint values.

BuyerTransferBillingEvidence dataclass

Immutable billing evidence for one exact buyer-transfer search.

__post_init__() -> None

Validate billing state and exact-target result cardinality.

__repr__() -> str

Return non-personal billing metadata.

BuyerTransferMatchResult dataclass

One exact buyer/grantee criterion outcome and its billing evidence.

matched: bool property

Return whether the provider linked the Buyer criterion to a property.

__post_init__() -> None

Bind the linkage and billing evidence to one public contract.

__repr__() -> str

Return outcome metadata without provider or person values.

build_buyer_transfer_match_criteria(criteria: BuyerTransferMatchCriteria) -> tuple[Criterion, ...]

Build the exact public PropertyRadar criteria for one property match.

buyer_transfer_scope_fingerprint(criteria: BuyerTransferMatchCriteria) -> str

Return a stable digest of the exact bounded request scope.

parse_buyer_transfer_match(envelope: Mapping[str, object], *, criteria: BuyerTransferMatchCriteria, purchase_requested: bool | None = None) -> BuyerTransferMatchResult

Parse one exact Buyer-criterion property-search response.

The linkage means only that PropertyRadar returned the exact property for its documented Buyer Name (Grantee) criterion and the supplied bounded windows. It does not invent a transaction identifier, exact-name matching semantics, or party boundaries.