API reference

LINDAS

zefix_parser.parse_entity_page(content)

The companies in a detail or combined-page response.

One company spans several rows, one per language-tagged literal, so rows are grouped by entity URI and folded down. Entities lacking a legal name, or carrying neither a UID nor an EHRAID, are dropped: there is nothing to match them against, and the register emits a few.

Parameters:

content (bytes)

Return type:

list[RegistryEntity]

zefix_parser.parse_uri_page(content)

The entity URIs of a build_uri_page_query() response, deduplicated.

Parameters:

content (bytes)

Return type:

list[str]

zefix_parser.parse_count(content)

The integer answer to build_count_query(), or None.

Parameters:

content (bytes)

Return type:

int | None

zefix_parser.parse_sparql_json(content)

The results.bindings list of a SPARQL JSON response.

Raises:

ParserError: if content is not a SPARQL JSON results document.

Parameters:

content (bytes)

Return type:

list[dict]

zefix_parser.compute_fingerprint(entity)

A stable digest of the fields that describe entity itself.

Two fetches of an unchanged company produce the same value, so you can skip the write. The digest covers the descriptive fields only: chid, ehra_id and alternate_names sit outside it.

Parameters:

entity (RegistryEntity)

Return type:

str

zefix_parser.build_combined_page_query(*, cursor_after=None, limit=500)

A query for one keyset page of full records, URIs and details in one round trip.

Parameters:

  • cursor_after (str | None)

  • limit (int)

Return type:

str

zefix_parser.build_uri_page_query(*, cursor_after=None, limit=500)

A query for one keyset page of entity URIs.

Pass the last URI of the previous page as cursor_after to get the next page. Omit it for the first page.

Parameters:

  • cursor_after (str | None)

  • limit (int)

Return type:

str

zefix_parser.build_detail_query(entity_uris)

A query for the full record of each URI in entity_uris.

Parameters:

entity_uris (list[str])

Return type:

str

zefix_parser.build_detail_query_by_uids(uids)

A query for the full record of each UID in uids.

LINDAS stores UIDs unpunctuated, so the values are normalized for you. "CHE-123.456.789" and "CHE123456789" both match.

Parameters:

uids (list[str])

Return type:

str

zefix_parser.build_count_query()

A query returning the number of companies in the dataset.

Return type:

str

zefix_parser.QUERY_VERSION

Version of the SPARQL query templates. Bumped whenever a template changes in a way that alters the parsed output, so a stored crawl can be told apart from one made under different queries.

PublicREST

zefix_parser.parse_company(data)

Parse one /company/... response into a Company.

The API returns a single company as an object from some endpoints and as a one-element list from others. Both are accepted.

Raises:

ParserError: if data is neither of those shapes.

Parameters:

data (dict | list)

Return type:

Company

zefix_parser.parse_companies(data)

Parse a /company/search response into a list of companies.

Parameters:

data (list | dict)

Return type:

list[Company]

zefix_parser.parse_sogc(data)

Parse one /sogc/... response into a SogcPublication.

Parameters:

data (dict | list)

Return type:

SogcPublication

zefix_parser.parse_sogc_list(data)

Parse a /sogc/bydate/... response into a list of publications.

Parameters:

data (list | dict)

Return type:

list[SogcPublication]

zefix_parser.meaningful_old_names(company)

The entries of company.old_names that are real former names.

The register re-typesets a name whenever anything else about the company changes, so oldNames fills up with entries that differ from the current name only in casing, punctuation or spacing: “QualiCasa AG” against “Qualicasa AG”. Apply those and you retire the company’s live name. This drops them, along with duplicates, and returns the rest oldest first.

Parameters:

company (Company)

Return type:

list[OldName]

zefix_parser.normalize_name(name)

name casefolded with punctuation and extra whitespace removed.

The comparison key behind meaningful_old_names().

Parameters:

name (str)

Return type:

str

zefix_parser.PARSER_VERSION

Version string identifying this parser, for recording alongside anything you persist.

Data model

class zefix_parser.RegistryEntity(zefix_uri, uid, chid, ehra_id, legal_name, alternate_names=<factory>, legal_form_code='', legal_form_name='', municipality_id='', municipality_name='', canton='', street_address='', postal_code='', locality='', purpose='', purpose_language='', fingerprint='')

One company as published on LINDAS.

Multi-valued and language-tagged predicates are already folded down to a single deterministic value per field; see zefix_parser.parse_entity_page().

Parameters:

  • zefix_uri (str)

  • uid (str)

  • chid (str)

  • ehra_id (str)

  • legal_name (str)

  • alternate_names (list[str])

  • legal_form_code (str)

  • legal_form_name (str)

  • municipality_id (str)

  • municipality_name (str)

  • canton (str)

  • street_address (str)

  • postal_code (str)

  • locality (str)

  • purpose (str)

  • purpose_language (str)

  • fingerprint (str)

class zefix_parser.Company(name, ehraid, uid='', chid='', canton='', status='', capital_nominal=None, capital_currency='CHF', deletion_date=None, cantonal_excerpt_web='', head_offices=<factory>, further_head_offices=<factory>, branch_offices=<factory>, has_taken_over=<factory>, was_taken_over_by=<factory>, audit_companies=<factory>, old_names=<factory>)

One company as returned by the Zefix PublicREST API.

Parameters:
class zefix_parser.RelatedEntity(name, ehraid, uid='', chid='', legal_seat='', status='')

A company reference inside a relationship field (auditor, branch, …).

Parameters:
class zefix_parser.OldName(name, sequence_nr)

A superseded company name, oldest first by sequence_nr.

Parameters:

  • name (str)

  • sequence_nr (int)

class zefix_parser.SogcPublication(sogc_id, publication_date=None, name='', uid='', ehraid=0, canton='', mutation_type_id=0, mutation_type='', message='')

A SOGC/SHAB publication reference as returned by the /sogc endpoints.

Parameters:

  • sogc_id (int)

  • publication_date (date | None)

  • name (str)

  • uid (str)

  • ehraid (int)

  • canton (str)

  • mutation_type_id (int)

  • mutation_type (str)

  • message (str)

class zefix_parser.RawPage(page_number, cursor_after, content, content_type, fetched_at, row_count)

One SPARQL response with the provenance needed to replay it.

Parameters:

Enumerations

class zefix_parser.CompanyStatus(*values)

Legal status as reported by the PublicREST API.

ACTIVE = 'ACTIVE'
IN_LIQUIDATION = 'IN_LIQUIDATION'
DELETED = 'DELETED'
class zefix_parser.RelationType(*values)

Kinds of corporate relation the REST detail record carries.

HEAD_OFFICE = 'head_office'
FURTHER_HEAD_OFFICE = 'further_head_office'
BRANCH_OFFICE = 'branch_office'
HAS_TAKEN_OVER = 'has_taken_over'
WAS_TAKEN_OVER_BY = 'was_taken_over_by'
AUDITOR = 'auditor'
class zefix_parser.Language(*values)

Languages the register publishes labels in.

DE = 'de'
FR = 'fr'
IT = 'it'
EN = 'en'

Identifiers

zefix_parser.normalize_uid(uid)

uid with punctuation removed and uppercased: "CHE123456789".

Use this as an index key, and is_valid_uid() to decide whether the value is a real UID.

Parameters:

uid (str)

Return type:

str

zefix_parser.format_uid(uid)

uid in the punctuated form "CHE-123.456.789".

This is the form the PublicREST API expects in its path; the unpunctuated form returns 404. Anything other than nine digits behind a CHE prefix comes back normalized and otherwise untouched.

Parameters:

uid (str)

Return type:

str

zefix_parser.clean_uid(value)

The first UID embedded anywhere in value, or "".

For free-text fields that wrap the UID in other content, such as "VAT: CHE-109.807.630 MWST".

Parameters:

value (str)

Return type:

str

zefix_parser.is_valid_uid(uid)

Whether uid is a CHE number with a valid check digit.

A mistyped UID can never match the register, so it is worth rejecting before you spend a request on it. Placeholders such as CHE123456789 fail this check.

Parameters:

uid (str)

Return type:

bool

zefix_parser.uid_check_digit_ok(digits)

Whether nine digits carry a valid UID check digit.

Parameters:

digits (str)

Return type:

bool

zefix_parser.normalize_chid(chid)

chid with punctuation removed and uppercased: "CH12345678901".

Parameters:

chid (str)

Return type:

str

zefix_parser.format_chid(chid)

chid in the punctuated form "CH-123.4.567.890-1".

The CHID is the older cantonal register number that Zefix still returns alongside the UID. Anything other than eleven digits behind a CH prefix comes back normalized and otherwise untouched.

Parameters:

chid (str)

Return type:

str

HTTP clients

class zefix_parser.client.LindasClient(endpoint='https://ld.admin.ch/query', *, page_size=500, timeout=60.0, min_interval=0.5, max_retries=4, user_agent='python-zefix-parser/0.1')

Client for the Zefix dataset on the LINDAS SPARQL endpoint.

No credentials are needed. The dataset carries the whole commercial register, so iter_entities() is a long walk: roughly 800,000 companies at the default page size.

Args:

endpoint: SPARQL endpoint. Defaults to DEFAULT_LINDAS_ENDPOINT. page_size: Entities per request, at most MAX_PAGE_SIZE. timeout: Per-request timeout in seconds. min_interval: Minimum seconds between requests. max_retries: Attempts per request, including the first. user_agent: User-Agent header to send.

Parameters:
count()

How many companies the dataset holds, or None if it will not say.

Return type:

int | None

fetch_by_uids(uids)

The companies with these UIDs, in one request.

Keep batches to a few hundred; the endpoint times out on very large VALUES clauses.

Parameters:

uids (list[str])

Return type:

list[RegistryEntity]

iter_pages(*, cursor_after=None)

Walk the register one page at a time, yielding raw responses.

Each RawPage carries the cursor it was fetched with. Persist that value and pass it back as cursor_after to resume an interrupted crawl.

Parameters:

cursor_after (str | None)

Return type:

Iterator[RawPage]

iter_entities(*, cursor_after=None)

Walk the whole register, yielding one company at a time.

Parameters:

cursor_after (str | None)

Return type:

Iterator[RegistryEntity]

query(sparql)

Send sparql to the endpoint and return the raw response body.

Raises:

TransportError: on a malformed query, which no retry will fix.

Parameters:

sparql (str)

Return type:

bytes

close()

Close the underlying connection pool.

Return type:

None

class zefix_parser.client.ZefixRestClient(base_url='https://www.zefix.admin.ch/ZefixPublicREST/api/v1', *, username='', password='', timeout=30.0, min_interval=0.5, max_retries=3, user_agent='python-zefix-parser/0.1')

Client for the Zefix PublicREST API.

Args:

base_url: API root. Defaults to DEFAULT_REST_BASE_URL. username: HTTP Basic username issued by zefix@bj.admin.ch. password: HTTP Basic password. timeout: Per-request timeout in seconds. min_interval: Minimum seconds between requests. max_retries: Attempts per request, including the first. user_agent: User-Agent header to send.

Parameters:
get_by_uid(uid)

The company with this UID, or None if the register has none.

uid is punctuated for you, so "CHE123456789" and "CHE-123.456.789" both work; the API only accepts the latter.

Parameters:

uid (str)

Return type:

Company | None

get_by_ehraid(ehraid)

The company with this EHRAID, or None.

Parameters:

ehraid (int)

Return type:

Company | None

get_by_chid(chid)

The company with this CHID, or None.

Parameters:

chid (str)

Return type:

Company | None

search(name, *, active_only=True, max_entries=30, offset=0)

Companies whose name starts with name.

The endpoint matches the start of the name and caps how much it returns. There is no cursor, so shorten the prefix when you need more results.

Parameters:
Return type:

list[Company]

sogc_by_date(day)

Every SOGC/SHAB publication issued on day.

Parameters:

day (date)

Return type:

list[SogcPublication]

sogc(publication_id)

One SOGC/SHAB publication by its id, or None.

Parameters:

publication_id (int)

Return type:

SogcPublication | None

close()

Close the underlying connection pool.

Return type:

None

zefix_parser.client.DEFAULT_LINDAS_ENDPOINT

"https://ld.admin.ch/query"

zefix_parser.client.DEFAULT_REST_BASE_URL

"https://www.zefix.admin.ch/ZefixPublicREST/api/v1"

zefix_parser.client.MAX_PAGE_SIZE

Largest page LindasClient will request.

Exceptions

class zefix_parser.ZefixError

Base class for every error this library raises.

class zefix_parser.ParserError

A response could not be parsed into the expected shape.

class zefix_parser.TransportError

An HTTP request failed and will not succeed on retry.

class zefix_parser.RetryableError

An HTTP request failed transiently and may succeed on retry.

class zefix_parser.AuthenticationError

The PublicREST API rejected the credentials, or none were supplied.