Public vs private API¶
pyventim wraps two distinct internal Eventim APIs. Understanding the difference helps you choose the right method and set realistic expectations about stability.
Public API¶
The public API is a set of JSON REST endpoints that Eventim exposes to power its own website search. They are "public" in the sense that they require no authentication token, not in the sense that Eventim has documented or endorsed their use.
Methods that use the public API:
| Method | Endpoint |
|---|---|
product_groups() |
/api/event/v2/productGroups |
attractions() |
/api/event/v1/attractions |
locations() |
/api/event/v1/locations |
content() |
/api/event/v1/content |
These return clean JSON which pyventim validates into Pydantic models. They are relatively stable because Eventim's own search UI depends on them.
Private API¶
The private API is what pyventim calls Eventim's component system: HTML pages that embed per-event JSON blobs inside script tags. These pages are used by Eventim's frontend to render individual event calendars.
Methods that use the private API:
| Method | Mechanism |
|---|---|
products() |
Fetches HTML, parses embedded JSON |
Because products() relies on HTML scraping, it is more fragile than the public API methods. A layout or markup change on Eventim's side can break parsing without any change to the URL or JSON schema.
Why two APIs?¶
The public API endpoints do not expose individual event dates, pricing tiers, or granular ticket availability — only top-level product group metadata. To get that information, pyventim must fall back to the component API.
This split is reflected in the exception hierarchy: PyventimPublicError covers the JSON endpoints; PyventimPrivateError covers the HTML scraping path.