Client¶

client ¶

Synchronous yente / OpenSanctions client.

BEST_ALGORITHM `module-attribute` ¶

BEST_ALGORITHM: Final[str] = 'best'

Canonical algorithm name resolving to whichever matching algorithm the server currently recommends. Stable across algorithm version bumps — pass algorithm=BEST_ALGORITHM for forward-compatibility.

Client ¶

Client(
    *,
    api_key: str | None = None,
    base_url: str = DEFAULT_BASE_URL,
    app_name: str | None = None,
    user_agent: str | None = None,
    timeout: float | Timeout | None = None,
    verify: bool | str = True,
    proxy: str | None = None,
    headers: dict[str, str] | None = None,
    transport: BaseTransport | None = None,
)

Synchronous client for the yente / OpenSanctions API.

Use as a context manager for deterministic cleanup of the underlying httpx.Client.

user_agent `property` ¶

user_agent: str

Return the User-Agent header this client sends on every request.

adjacent ¶

adjacent(
    entity_id: str,
    *,
    prop: None = None,
    limit: int | None = None,
    offset: int = 0,
    sort: list[str] | None = None,
) -> AdjacentResponse

adjacent(
    entity_id: str,
    *,
    prop: str,
    limit: int | None = None,
    offset: int = 0,
    sort: list[str] | None = None,
) -> AdjacentPropertyResponse

adjacent(
    entity_id: str,
    *,
    prop: str | None = None,
    limit: int | None = None,
    offset: int = 0,
    sort: list[str] | None = None,
) -> AdjacentResponse | AdjacentPropertyResponse

Fetch the adjacency map for an entity, optionally restricted to one property.

Without prop: returns the full adjacency map keyed by property name. With prop: returns paginated results for that one property.

algorithms ¶

algorithms() -> AlgorithmsResponse

Fetch the list of enabled matching algorithms and the server's defaults.

close ¶

close() -> None

Close the underlying httpx.Client.

datasets ¶

datasets() -> DatasetsResponse

Fetch the indexed datasets and their freshness state.

Calls the wire endpoint GET /catalog; the SDK surface uses the datasets name because that's what the response carries. Revalidates via ETag when the server provides one (yente doesn't yet; see opensanctions/yente#1202).

fetch ¶

fetch(entity_id: str, *, nested: bool = True) -> Entity

Fetch a single entity by ID.

Follows 308 redirects transparently when entity_id is a referent of a canonical entity. Pass nested=False for a lighter response that omits adjacent entities like sanctions and ownership links.

healthz ¶

healthz() -> StatusResponse

Probe server liveness.

Returns {"status": "ok"} whenever the server process is up. Useful for Kubernetes liveness probes. See :meth:readyz for index readiness, which can fail independently.

match ¶

match(
    entity: EntityInput,
    *,
    filters: MatchFilters | None = None,
    threshold: float | None = None,
    algorithm: str | None = None,
    weights: dict[str, float] | None = None,
    config: dict[str, Any] | None = None,
    limit: int | None = None,
    **filter_kwargs: Any,
) -> MatchResponse

Match an entity against a dataset by example.

Builds a single-query payload and unwraps the response into a flat :class:MatchResponse.

Pass filter fields either via filters=MatchFilters(...) or as kwargs (datasets=[...], topics=[...], exclude_entities=[...]); kwargs win on any field they specify.

Parameters:

Name	Type	Description	Default
`algorithm`	`str \| None`	Server-side algorithm name. Common values: `"best"` (use `BEST_ALGORITHM`), `"logic-v2"`, `"name-matcher"`. The full set is dynamic via :meth:`algorithms`.	`None`

Raises:

Type	Description
`ConfigurationError`	`entity`'s schema is not a matchable target (e.g. `Document`, `Article`). Yente would reject the query with a 4xx; the client refuses it before the round-trip to give a clearer error.

programs ¶

programs() -> ProgramsResponse

Fetch the sanctions-program catalog — resolves programId codes.

Sanctioned entities carry a programId property naming the program under which they were designated (e.g. "EU-UKR"); this catalog maps those codes to the program's title, issuer, policy summary, and measures. Fetched from :data:PROGRAMS_URL on the public OpenSanctions data bucket — an absolute URL, so it works regardless of base_url (including against a self-hosted yente). Long-lived clients revalidate via ETag: repeat calls cost a bodiless 304 round-trip, not the full artifact.

readyz ¶

readyz() -> StatusResponse

Probe whether the search index is ready to serve queries.

Returns the same shape as :meth:healthz, but the server returns 503 (mapped to :class:ServerError) until the index is loaded.

search ¶

search(
    q: str,
    *,
    filters: SearchFilters | None = None,
    limit: int | None = None,
    offset: int = 0,
    sort: list[str] | None = None,
    fuzzy: bool = False,
    simple: bool = False,
    facets: list[str] | None = None,
    **filter_kwargs: Any,
) -> SearchResponse

Run a full-text search across one or more datasets.

Pass filter fields either via filters=SearchFilters(...) or as kwargs (datasets=[...], schema=, countries=[...], …); kwargs win on any field they specify. The datasets filter is translated to the v1 wire as /search/<first-dataset> with the rest passed as repeated include_dataset query params.

statements ¶

statements(
    *,
    dataset: str | None = None,
    entity_id: str | None = None,
    canonical_id: str | None = None,
    prop: str | None = None,
    value: str | None = None,
    schema: str | None = None,
    sort: list[str] | None = None,
    limit: int | None = None,
    offset: int = 0,
) -> StatementsResponse

Read raw entity data as statements — for lineage and diagnostics.

Use this for tracking where a value came from, when it was first observed, and which dataset asserted it. See the statement-based data model <https://www.opensanctions.org/docs/statements/>_ for context.

Typically you want canonical_id=, passing the ID returned by :meth:match / :meth:search / :meth:fetch. It returns every source fragment that was deduplicated into the canonical entity. entity_id= returns only one source's pre-deduplication fragment — useful for source-level audits, but the same person across five sanctions lists has five distinct entity_id values and only one canonical_id.

Only the OpenSanctions API serves this endpoint — it is backed by a Postgres instance that yente doesn't ship. A yente instance returns 404, which surfaces here as :class:NotFoundError with a pointed message.