ZDF APIzdf.de ↗
Access ZDF Mediathek content via API: search episodes, get show metadata, live streams, TV schedules for ZDF, ZDFneo, 3sat, arte, and more.
What is the ZDF API?
The ZDF Mediathek API exposes 8 endpoints covering content search, episode and show metadata, live streams, and broadcast schedules across seven German-language TV channels. The get_tv_program endpoint returns full EPG data for ZDF, ZDFinfo, ZDFneo, 3sat, KI.KA, PHOENIX, and arte for any given date, while search_content lets you query the entire Mediathek catalogue with cursor-based pagination.
curl -X GET 'https://api.parse.bot/scraper/932501ef-d2bf-467c-8114-dfaf39646c29/search_content?limit=5&query=Tatort' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace zdf-de-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""ZDF Mediathek SDK — search, browse categories, check live streams."""
from parse_apis.zdf_mediathek_api import ZDFMediathek, CollectionId, EpisodeNotFound
client = ZDFMediathek()
# Search for videos; limit caps total items fetched across pages.
for video in client.videosummaries.search(query="Tatort", limit=3):
print(video.title, video.canonical, video.current_media_type)
# Drill into the first hit for full episode details.
hit = client.videosummaries.search(query="Markus Lanz", limit=1).first()
if hit:
full = hit.details()
print(full.title, full.current_media_type, len(full.guests), "guests")
# Browse a category using the CollectionId enum.
for show in client.contentclusters.list_category(collection_id=CollectionId.SERIEN, limit=3):
print(show.cluster_label, show.cluster_id)
# Fetch a show by slug and inspect its metadata.
show = client.shows.get(canonical="markus-lanz-114")
print(show.title, show.collection_id)
# Typed error: attempt to get a non-existent episode.
try:
client.videos.get(canonical="does-not-exist-999")
except EpisodeNotFound as exc:
print(f"Episode not found: {exc.canonical}")
print("exercised: search / details / list_category / shows.get / videos.get")
Full-text search over ZDF Mediathek content. Returns paginated search results including video items with metadata such as title, canonical slug, editorial date, and teaser info. Paginates via cursor (endCursor from pageInfo).
| Param | Type | Description |
|---|---|---|
| after | string | Pagination cursor for next page, obtained from previous response's pageInfo.endCursor. |
| limit | integer | Number of results to return per page. |
| queryrequired | string | Search query string. |
{
"type": "object",
"fields": {
"results": "array of search result objects with video metadata including id, title, canonical, currentMediaType, editorialDate",
"pageInfo": "pagination object with hasNextPage, endCursor, startCursor",
"endCursor": "flattened cursor string for next page (from pageInfo.endCursor)",
"hasNextPage": "boolean indicating if more pages exist"
},
"sample": {
"data": {
"results": [
{
"id": "948dc982-e371-48f7-906f-a7ebd92a1ea4",
"title": "Tatort",
"canonical": "page-video-ard-tatort-100",
"editorialDate": "2026-05-25T17:00:00.000000+00:00",
"currentMediaType": "EPISODE"
}
],
"pageInfo": {
"endCursor": "NQ==",
"hasNextPage": true
},
"endCursor": "NQ==",
"hasNextPage": true
},
"status": "success"
}
}About the ZDF API
Content Search and Discovery
The search_content endpoint accepts a query string and returns an array of video items with metadata alongside a pageInfo object containing hasNextPage and endCursor for paginated traversal. Pass the endCursor value back as the after parameter to retrieve subsequent pages. The get_homepage_highlights endpoint requires no inputs and returns curated clusters — named content sections with their constituent items — reflecting what ZDF is currently featuring.
Show and Episode Metadata
get_show_details takes a canonical slug (e.g. die-chefin-114) and returns the show title, a collectionId that identifies the episode collection, and an episodes object with individual episode items. That collectionId can then be passed to list_category_content as a collection_id to paginate through episodes or related content. get_episode_details returns richer per-episode data: cast and crew arrays for fiction titles, a guests array for talk-show formats, the parent smartCollection reference, and a currentMediaType field indicating whether the item is an EPISODE or another type.
Live Streams and TV Schedule
get_live_streams returns a nodes array of currently active streams, each with a canonical slug, currentMediaType, and teaser title — no inputs required. The get_tv_program endpoint accepts an optional date parameter in YYYY-MM-DD format (defaults to today) and returns an epg array structured per broadcaster, with now/next entries and full broadcast lists for each channel.
Catalogue Browsing
list_shows_az returns the full A-Z catalogue with alphabetical tabs (each including item counts) and a paginated content node list. Use the offset or end_cursor parameters to page through results. list_category_content accepts a collection_id such as pub-form-10010 (Serien) or pub-form-10006 (Nachrichten) and returns smartCollections with show metadata, genre tabs for filtering, and pageInfo for pagination.
The ZDF API is a managed, monitored endpoint for zdf.de — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when zdf.de changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official zdf.de API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Build a German-language TV guide app using
get_tv_programEPG data across ZDF, ZDFneo, 3sat, and arte - Index the ZDF Mediathek catalogue for a search interface using
search_contentwith cursor pagination - Populate a show database with cast, crew, and guest metadata from
get_episode_details - Track currently airing content by polling
get_live_streamsfor active stream objects - Generate an A-Z directory of ZDF shows using
list_shows_azalphabetical tabs and paginated nodes - Classify content by genre or publication form using
list_category_contentwith known collection IDs - Surface trending ZDF content by reading
clustersfromget_homepage_highlights
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does ZDF offer an official developer API?+
What does `get_tv_program` return, and which channels does it cover?+
epg array where each element corresponds to one broadcaster. Covered channels are ZDF, ZDFinfo, ZDFneo, 3sat, KI.KA, PHOENIX, and arte. Each broadcaster block includes now/next broadcast metadata and a full broadcast list for the requested date. Pass a date string in YYYY-MM-DD format to query a specific day; omitting the parameter defaults to the current date.Can I retrieve streaming URLs or video playback links from these endpoints?+
How does pagination work across the different endpoints?+
search_content and list_category_content use cursor-based pagination: pass the endCursor value from a response's pageInfo into the after parameter of the next request. list_shows_az supports both offset-based pagination via offset and cursor-based pagination via end_cursor. The hasNextPage boolean in pageInfo indicates whether additional results exist.