pyventim

Testing Documentation Contributor Covenant Python PyPI Latest Release PyPI Downloads Coverage

[!NOTE] Consider the whole project as unstable until version 1.0.0 is reached.

pyventim

A Python module to fetch usable data with a reverse engineered Eventim API.

Description

The pyventim.eventim.com/">Eventim API has some public endpoints but also hidden data in the HTML responses. The project goal is to provide away to fetch this data with simple to use python objecs.

[!IMPORTANT] Be aware that the APIs of Eventim can change without notice and therefore break the module.

Getting Started

Dependencies

  • Python >= 3.10
  • Requests >= 2.31.0
  • lxml >= 5.2.2
  • Pydantic >= 2.7.0

Installing

pip install pyventim

Quick start

To find attractions we can use the exploration endpoint:

import pyventim

# Create the Eventim class
eventim = pyventim.Eventim()

# Returns an iterator that fetches all pages off the search endpoint.
attractions = eventim.explore_attractions(search_term="Landmvrks")

# We can loop over each attraction. The module handles fetching pages automatically.
for attraction in attractions:
    print(attraction["attractionId"], attraction["name"])

Next we use the product group endpoint to fetch events for our attraction and get the events of the html endpoint.

# We loop over each product group and fetch the events automatically.
for product_group in eventim.explore_product_groups(search_term="Landmvrks"):
    product_group_id = product_group["productGroupId"]
    for event in eventim.get_product_group_events_from_calendar(product_group_id):
        print(event["title"], event["eventDate"], event["price"], event["ticketAvailable"], sep=" | ")

For a more detailed information please refer to the documentation.

License

This project is licensed under the MIT License - see the LICENSE.md file for details

Code of conduct

Please follow our code of conduct.

Finding help

The code documentation can be found here. However if you encounter a unexpected behaviour: Feel free to open an issue.

Contributing

All contributions, bug reports, bug fixes, documentation improvements, enhancements, and ideas are welcome.

If youre looking to work on the pyventim codebase:

  1. Fork the repository.
  2. Make your changes and follow common code practices as well as Python PEP standards.
  3. Open a merge request and follow the instructions.
  4. Be awesome!

For bug reports: Please head over to the issues page.

As contributors and maintainers to this project, you are expected to abide by pyeventim' code of conduct. More information can be found at: Contributor Code of Conduct

Thank you!

Thank you for contributing to this project!

Maintainers

*Preferred method of contact.

Acknowledgments

Examples

Exploration Endpoint

The exploration endpoint can be used to discover attractions and locations. This is the same api used by the fuzzy search on the website. Therefore the limit is quite high.

explore_attractions

The explore_attractions returns matching attractions based on the search_term parameter (In the Eventim-Universe that's a musical, artist, band, etc..)

# Returns an iterator that fetches all pages off the search endpoint.
attractions = eventim.explore_attractions(search_term="The Rolling Stones", sort=sort)

# We can loop over each attraction and print the item. The module handles fetching pages automatically.
for attraction in attractions:
    print(attraction)

A sample attraction can be found here:

{
  "attractionId": "662",
  "name": "The Rolling Stones",
  "description": "The Rolling Stones sind zweifellos eine der legend\u00e4rsten Rockbands der Welt \u2013 und das liegt auch an ihren spektakul\u00e4ren Live-Shows.",
  "link": "https://wwwpyventim.eventim.de/artist/the-rolling-stones/",
  "url": {
    "path": "/artist/the-rolling-stones/",
    "domain": "https://www.eventim.de"
  },
  "imageUrl": "https://wwwpyventim.eventim.de/obj/media/DE-eventim/galery/222x222/r/rolling-stones-tickets-2022-02-neu.jpg",
  "rating": {
    "count": 460,
    "average": 4.284800052642822
  }
}

explore_locations

The explore_attractions returns matching locations based on the search_term parameter. A location can be a thing like an arena, a bar or a theatere.

# Returns an iterator that fetches all pages off the search endpoint.
locations = eventim.explore_locations("Stage Theater im Hafen Hamburg")

# We can loop over each location and print the item. The module handles fetching pages automatically.
for location in locations:
    print(location)

A sample location can be found here:

{
  "locationId": "vg_3880",
  "name": "Stage Theater im Hafen Hamburg",
  "description": "Erleben Sie live wie Kunst, Phantasie, Traum und Wirklichkeit miteinander verschmelzen.",
  "city": "Hamburg",
  "link": "https://wwwpyventim.eventim.de/city/hamburg-7/venue/stage-theater-im-hafen-hamburg-3880/",
  "url": {
    "path": "/city/hamburg-7/venue/stage-theater-im-hafen-hamburg-3880/",
    "domain": "https://www.eventim.de"
  },
  "imageUrl": "https://wwwpyventim.eventim.de/obj/media/DE-eventim/teaser/venue/222x222/2012/stage-theater-im-hafen-tickets-hamburg.jpg",
  "rating": {
    "count": 2842,
    "average": 4.585855007171631
  }
}

explore_product_groups

The explore_attractions returns matching product groups with the 5 most relevant products based on the provided parameters. A product group is something like a tour, musical, festival, etc. A product is a concert, festical day pass, musical performance

Please note that time_from and time_to are matched against the event start date. Therefore the below will return the product groups and 5 latest products for "Disneys DER KÖNIG DER LÖWEN" between 2024-12-01 and 2024-12-31 with a start time between 3pm and 6pm.

    product_groups = eventim.explore_product_groups(
        search_term="Disneys DER KÖNIG DER LÖWEN",
        sort="DateDesc",
        categories=["Musical & Show"],
        date_from=datetime.date(2024, 12, 1),
        date_to=datetime.date(2024, 12, 31),
        time_from=datetime.time(15, 00),
        time_to=datetime.time(18, 00),
    )

    for product_group in product_groups:
        print(product_group)

A sample product group can be found here:

{
  "productGroupId": "473431",
  "name": "Disneys DER K\u00d6NIG DER L\u00d6WEN",
  "description": "Das Musical bringt die farbenpr\u00e4chtige Welt Afrikas mit wilden Tieren und der wundersch\u00f6nen Serengeti nach Hamburg.\n",
  "startDate": "2024-03-19T18:30:00+01:00",
  "endDate": "2025-12-21T18:30:00+01:00",
  "productCount": 678,
  "link": "https://wwwpyventim.eventim.de/artist/disneys-der-koenig-der-loewen/",
  "url": {
    "path": "/artist/disneys-der-koenig-der-loewen/",
    "domain": "https://www.eventim.de"
  },
  "imageUrl": "https://wwwpyventim.eventim.de/obj/media/DE-eventim/teaser/222x222/2022/disneys-koenig-der-loewen-musical-tickets-2022.jpg",
  "currency": "EUR",
  "rating": {
    "count": 5265,
    "average": 4.660600185394287
  },
  "categories": [
    {
      "name": "Musical & Show"
    },
    {
      "name": "Musical",
      "parentCategory": {
        "name": "Musical & Show"
      }
    }
  ],
  "tags": ["TICKETDIRECT", "FANTICKET", "MOBILE_TICKET", "FANSALE"],
  "status": "Available",
  "products": [
    {
      "productId": "18637122",
      "name": "Disneys DER K\u00d6NIG DER L\u00d6WEN",
      "type": "LiveEntertainment",
      "status": "Available",
      "link": "https://wwwpyventim.eventim.de/event/disneys-der-koenig-der-loewen-stage-theater-im-hafen-hamburg-18637122/",
      "url": {
        "path": "/event/disneys-der-koenig-der-loewen-stage-theater-im-hafen-hamburg-18637122/",
        "domain": "https://www.eventim.de"
      },
      "typeAttributes": {
        "liveEntertainment": {
          "startDate": "2024-12-31T17:00:00+01:00",
          "location": {
            "name": "Stage Theater im Hafen Hamburg",
            "city": "Hamburg",
            "geoLocation": {
              "longitude": 9.995280019552826,
              "latitude": 53.545300001826604
            }
          }
        }
      },
      "rating": {
        "count": 5265,
        "average": 4.660600185394287
      },
      "tags": ["TICKETDIRECT", "FANTICKET", "MOBILE_TICKET"],
      "hasRecommendation": false
    }
  ]
}

Component Endpoint

This endpoint can be used to get data to specifict attractions. An example would be all events by an artist. The data is fetched by a lxml parser to look for key words in the HTML code that include interesting data.

Functionality can break without notice because this is parsed via HTML.

get_attraction_events

This endpoint fetches data about upcomming events in the https://schema.org/MusicEvent schema. Attraction ids can be found in the explore_attractions function.

Note: This only returns the next 90 events. If you need more events consider using the get_attraction_events_from_calendar function which is faster in any case.

# The attraction id for "Disneys DER KÖNIG DER LÖWEN"
attraction_id = 473431

# Return the next 7 days
now = datetime.datetime.now()
date_from = now.date()
date_to = (now + datetime.timedelta(days=7)).date()

# Make the request and loop over attraction events
attraction_events = eventim.get_attraction_events(
    attraction_id=attraction_id,
    date_from=date_from,
    date_to=date_to,
)

for attraction_event in attraction_events:
    print(attraction_event)

A sample attraction event can be found here:

{
  "@context": "https://schema.org",
  "@type": "MusicEvent",
  "description": "Das Musical bringt die farbenpr\u00e4chtige Welt Afrikas mit wilden Tieren und der wundersch\u00f6nen Serengeti nach Hamburg.\n",
  "endDate": "2024-05-21T18:30:00.000+02:00",
  "image": [
    "https://wwwpyventim.eventim.de/obj/media/DE-eventim/teaser/222x222/2022/disneys-koenig-der-loewen-musical-tickets-2022.jpg",
    "https://wwwpyventim.eventim.de/obj/media/DE-eventim/teaser/222x222/2022/disneys-koenig-der-loewen-musical-tickets-2022.jpg",
    "https://wwwpyventim.eventim.de/obj/media/DE-eventim/teaser/artworks/2024/disneys-der-koenig-der-loewen-musical-tickets-header.jpg"
  ],
  "location": {
    "name": "Stage Theater im Hafen Hamburg",
    "sameAs": "https://wwwpyventim.eventim.de/city/hamburg-7/venue/stage-theater-im-hafen-hamburg-3880/",
    "address": {
      "streetAddress": "Norderelbstrasse 6",
      "postalCode": "20457",
      "addressLocality": "Hamburg",
      "addressRegion": "",
      "addressCountry": "DE",
      "@type": "PostalAddress"
    },
    "@type": "Place"
  },
  "name": "Disneys DER K\u00d6NIG DER L\u00d6WEN",
  "offers": {
    "category": "primary",
    "price": 96.99000000000001,
    "priceCurrency": "EUR",
    "availability": "InStock",
    "url": "https://wwwpyventim.eventim.de/event/disneys-der-koenig-der-loewen-stage-theater-im-hafen-hamburg-16825147/",
    "validFrom": "2023-03-28T10:00:00.000+02:00",
    "@type": "Offer"
  },
  "performer": {
    "name": "Disneys DER K\u00d6NIG DER L\u00d6WEN",
    "@type": "PerformingGroup"
  },
  "startDate": "2024-05-21T18:30:00.000+02:00",
  "url": "https://wwwpyventim.eventim.de/event/disneys-der-koenig-der-loewen-stage-theater-im-hafen-hamburg-16825147/"
}

get_attraction_events_from_calendar

This function will return all available events for the attraction with similar data like the get_attraction_events function. Attraction ids can be found in the explore_attractions function.

# The attraction id for "Disneys DER KÖNIG DER LÖWEN"
attraction_id = 473431

# Return the next 7 days
now = datetime.datetime.now()
date_from = now.date()
date_to = (now + datetime.timedelta(days=7)).date()

# Make the request and loop over attraction calendar events
attraction_calendar_events = eventim.get_attraction_events_from_calendar(
    attraction_id=attraction_id,
    date_from=date_from,
    date_to=date_to,
)

for attraction_calendar_event in attraction_calendar_events:
    print(attraction_calendar_event)

A sample calendar attraction event can be found here:

{
  "id": "16825147",
  "title": "Disneys DER K\u00d6NIG DER L\u00d6WEN",
  "url": "/event/disneys-der-koenig-der-loewen-stage-theater-im-hafen-hamburg-16825147/",
  "start": "2024-05-21T18:30:00",
  "eventTime": "18:30",
  "price": "ab \u20ac\u00a096,99",
  "eventDate": "21.05.2024",
  "tileFirstLine": "\u00a0",
  "priceAvailable": true,
  "ticketAvailable": true,
  "ticketStatusMessage": "Verf\u00fcgbar",
  "eventState": 2,
  "voucher": false,
  "promotionContained": false,
  "subscriptionPackage": false,
  "subscriptionPackageData": null,
  "venueName": "\u00a0",
  "first": "Disneys DER K\u00d6NIG DER L\u00d6WEN",
  "second": "HAMBURG",
  "third": "Stage Theater im Hafen Hamburg",
  "eventWeekday": "Dienstag",
  "identicalCity": true,
  "identicalVenue": true,
  "marketingLabels": [],
  "clubIcon": {
    "iconVisible": false,
    "marketingLabel": null,
    "ticketTypeInfoVisible": false,
    "ticketTypeInfo": "",
    "iconColor": ""
  },
  "subListings": [],
  "externalOffers": false,
  "tdlId": 3357219,
  "formattedDay": "21",
  "formattedMonthYear": "Mai 2024",
  "formattedWeekdayTime": "Di. 18:30",
  "formattedIsoDate": "2024-05-21T18:30:00.000+02:00",
  "continuousEventData": null,
  "eventFavoritesItem": null,
  "imagePath": null,
  "linkToModalLayer": null,
  "medalIcon": null,
  "genderIcon": null,
  "formattedDateTime": null,
  "desc1": null,
  "desc2": null,
  "crossedOutPrice": "",
  "bookable": true,
  "availabilityIndicator": -1,
  "willCall": false,
  "ticketDirect": true,
  "eventimPass": false,
  "mobileTicket": true,
  "fanticket": true,
  "red": false,
  "trackingData": {
    "label": "1",
    "id": "16825147",
    "name": "Disneys DER KÖNIG DER LÖWEN"
  }
}

Seatmap Endpoint

This endpoint can be used to get seatmap data of specific attraction.

Functionality can break without notice because this is parsed via HTML.

get_event_seatmap_information

This function can return data about the seatmap if found in the HTML of the event page. If no seat map is found then None will be returned.

# This will fetch the html for the given event. Note the url must match the structure in the example!
result = eventim.get_event_seatmap_information("/event/disneys-der-koenig-der-loewen-stage-theater-im-hafen-hamburg-18500464/")

A sample for the seatmap information can be found here (Note this is truncated.):

{
  "fansale": { <- ... -> },
  "seatmapOptions": { <- ... -> },
  "seatmapIsDefault": false,
  "packageData": { <- ... -> },
  "price": { <- ... -> },
  "maxAmountForEvent": 10,
  "minAmountForEvent": 1,
  "maxAmountForPromo": 0,
  "preselectedPcId": 0,
  "showBackLink": false,
  "backLink": "/event/disneys-der-koenig-der-loewen-stage-theater-im-hafen-hamburg-16828914/",
  "eventName": "Disneys DER K\u00d6NIG DER L\u00d6WEN",
  "restrictions": { <- ... -> },
  "cartData": { <- ... -> },
  "panoramaOptions": { <- ... -> },
  "imageviewerOptions": { <- ... -> },
  "ccEnabled": true,
  "initialRequestPath": "/api/shoppingCart/?affiliate=EVE&token=518ACD577869FB764ED195DF569D347C",
  "captchaActive": false,
  "captchaAPIPath": "//www.google.com/recaptcha/api.js?hl=de",
  "captchaSiteKey": "",
  "pcFlyoutExpanded": true,
  "pcUpgradeActiveClass": "js-pc-upgrade-active",
  "pricePlaceholder": "#PRICE#",
  "hasPriceDisclaimerHint": false,
  "hasCorporateBenefits": false,
  "hasCombinedTicketTypes": false,
  "hasAllCategoriesToggleText": true,
  "reducedAvailabilityWidgetLink": "",
  "hasOptionsFilter": false,
  "ticketTypeFilterMap": { <- ... -> },
  "api": "/api/corporate/benefit/limits/?affiliate=EVE",
  "useParis24Styles": false,
  "messages": { <- ... -> }
}

get_event_seatmap

This function returns seatmap data with avialible seats and their pricing data. This could be used to generate a seatmap image or make yield analytics.

# This will fetch the html for the given event. Note the url must match the structure in the example!
result = eventim.get_event_seatmap_information("/event/disneys-der-koenig-der-loewen-stage-theater-im-hafen-hamburg-18500464/")
seatmap = eventim.get_event_seatmap(result["seatmapOptions"])

A sample for the seatmap information can be found here (Note this is fictional data):

{
  "seatmap_key": "web_1_16828914_0_EVE_0",
  "seatmap_timestamp": 1716717879990,
  "seatmap_individual_seats": 2051,
  "seatmap_dimension_x": 8192,
  "seatmap_dimension_y": 8192,
  "seatmap_seat_size": 59,
  "blocks": [
    {
      "block_id": "b1",
      "block_name": "Parkett links",
      "block_description": "Parkett links",
      "block_rows": [
        {
          "row_code": "r4",
          "row_seats": [
            {
              "seat_code": "s515",
              "seat_price_category_index": 1,
              "seat_coordinate_x": 3846,
              "seat_coordinate_y": 1699
            }
          ]
        }
      ]
    }
  ],
  "price_categories": [
    {
      "price_category_id": "p32919041",
      "price_category_name": "Kat. 1 Premium",
      "price_category_color": "#f1075e"
    }
  ]
}

 1"""
 2.. include:: ../../README.md
 3.. include:: ../../docs/examples.md
 4.. include:: ../../docs/exploration_endpoint.md
 5.. include:: ../../docs/component_endpoint.md
 6.. include:: ../../docs/seatmap_endpoint.md
 7"""
 8
 9from .eventim import Eventim
10
11from . import models
12from . import exceptions
13from . import utils