ENDPOINTS

videos

The videos endpoint is the heart of the API by giving access to the video index of fernsehsuche.de with meta data on videos from more than 20 german tv channels.

A video here is defined as a single media entity with a concrete URL which can be watched online via a media center. This can be both whole episodes of shows as well as clips dividing a show episode (e.g. a political news magazine) into several videos around specific topics.

Here a some examples:

  • “ZDF heute-Sendung vom 08. Oktober 2013” (17min) (Show: ZDF heute)
  • “Die verpackte Republik” (28min) (Show: hitec (3sat))
  • “US-Haushaltsstreit berührt Außenpolitik” (01:47) (Show: ZDF heute)
  • “ISOTEC Gebäudesanierung” (44min) (Show: Undercover Boss)

Endpoint

https://api.fernsehsuche.de/[APIVERSION]/videos/

Example

Request:

HTTPS/1.1 GET
Query string: genre:RD AND duration:[2010-01-01T00:30:00Z TO *]
Parameter sort: air_date DESC,air_time DESC
Encoded URL: /videos/?q=genre%3ARD%20AND%20duration%3A%5B2010-01-01T00%3A30%3A00Z%20TO%20%2A%5D&sort=air_date%20DESC%2Cair_time%20DESC

This will give back all videos from the genre RD (“Dokumentationen”) which have a duration of 30 minutes or longer starting with the newest videos.

An extract of the response should look similar to the following.

Response:

{
        response:{
                numFound:1607,
                start:0,
                docs:{
                        show: "Dokumentation und Reportage",
                        duration: "2010-01-01T01:29:13Z",
                        title: "Abenteuer Harz",
                        channel_group: "T",
                        channel_url: "http://www.ardmediathek.de/",
                        thumbnail: "/media/thumbnails/dds/aaa496f02df9995543ee6840e52c5b27b27b8e91.jpg",
                        channel: "rbb",
                        description: "Dokumentation und Reportage - Eine einzigartige Naturlandschaft und ein Ferienparadies zugleich: das ist der Harz. Mit seinen geheimnisvollen Wäldern, reißenden Flüssen, tiefen Tälern und Schluchten gehört Deutschlands nördlichstes Gebirge zu den beliebtesten Urlaubsregionen der Deutschen.",
                        air_date: "2013-10-12T00:00:00Z",
                        show_id: 103,
                        air_time: "2010-01-01T15:30:00Z",
                        genre: "RD",
                        show_url: "http://www.ardmediathek.de/sendung/dokumentation-und-reportage?documentId=3822114",
                        url: "http://www.ardmediathek.de/rbb-fernsehen/dokumentation-und-reportage/abenteuer-harz?documentId=17483332",
                        video_id: 194005,
                        channel_id: 3
                }
        }
}

Field description

In the following table you can find a description of the fields returned together with a result object.

Field name Data type Available Description
show String Always Show name
duration Date Always Duration of a video (see Range queries for notes how to use)
duration_en Date Always Simplified duration format (only XML)
title String Always The title of a video
channel_group Enum Always Group of the corresponding channel (e.g. (M|”Hauptsender”))
channel_url URL Always Media center URL of the corresponding channel
thumbnail URL Mostly Path for thumbnail image (105x70px), download via http://api-resources.fernsehsuche.de
channel String Always Channel name
description String Mostly Description of the video content
air_date Date Always Air date of a video
air_date_en Date Always Simplified air_date format (only XML)
show_id Integer Always ID of the corresponding show
air_time Date Always Air time of a video
air_time_en Date Always Simplified air_time format (only XML)
genre Enum Always Genre of the corresponding show of a video
show_url URL Always Media center URL of the corresponding show of a video
url URL Always URL of the video in the media center
video_id Integer Always ID of a video
channel_id Integer Always ID of the corresponding channel

Note

You can use double quotes to get exact matches for fields like show or channel. (example: show:"ZDF heute", encoded: show%3A%22ZDF%20heute%22).

Note

Image resources like thumbnails can be downloaded both via HTTP and HTTPS.

Query video by ID

There is an extra endpoint for an alternative method to make an API request for a certain video:

https://api.fernsehsuche.de/[APIVERSION]/videos/{ID}/

By appending the id of a video to the videos endpoint you get directly to the desired video.

shows

A show in the terminology of fernsehsuche.de is defined as chronological series of videos or clips around a certain topic, concept or story. The german equivalent of it would be something like “Fernsehsendung”.

Here are some examples:

  • “ZDF heute” (Channel: ZDF)
  • “Undercover Boss” (Channel: RTL)
  • “Weissensee” (Channel: Das Erste)
  • “n-tv Dokumentation” (Channel: n-tv)
  • “Fernsehfilme im Ersten” (Channel: Das Erste)

Like you can see in the last two examples, depending on how the TV channels structure their media center program, a show can also sometimes be a collection of videos around a certain genre or a special daytime during the weeks where similar videos/episodes (e.g. movies) are broadcasted.

Endpoint

https://api.fernsehsuche.de/[APIVERSION]/shows/

Example

Request:

HTTPS/1.1 GET
Query string: show_exact:"rbb aktuell"
Encoded URL: /shows/?q=show_exact%3A%22rbb%20aktuell%22

This will give back show meta data for the show “rbb AKTUELL” from the channel rbb.

An extract of the response should look similar to the following.

Response:

{
        response:{
                numFound:1,
                start:0,
                docs:{
                        name: "rbb AKTUELL",
                        info_url: "http://www.ardmediathek.de/ard/servlet/content/8056926",
                        channel_group: "T",
                        show_id: 458,
                        thumbnail: "/media/thumbnails/dds/8787fbf1530cbb1269339043b479f63f1b687c47.jpg",
                        channel_id: 3,
                        url: "http://www.ardmediathek.de/sendung/rbb-aktuell?documentId=3907840",
                        genre: "NA",
                        channel_url: "http://www.ardmediathek.de/",
                        channel: "rbb",
                        description: "rbb AKTUELL: rbb AKTUELL ist die Nachrichtenmarke des rbb Fernsehens."
                }
        }
}

Field description

In the following table you can find a description of the fields returned together with a result object.

Field name Data type Available Description
name String Always Name of the show
info_url URL Often URL of an associated show homepage
channel_group Enum Always Group of the corresponding channel (e.g. (M|”Hauptsender”))
show_id Integer Always ID of a show
thumbnail URL Mostly Path for thumbnail image (105x70px), download via http://api-resources.fernsehsuche.de
channel_id Integer Always ID of the corresponding channel
url URL Always URL of the show in the media center
genre Enum Always Genre of a show
channel_url URL Always Media center URL of the corresponding channel
channel String Always Channel name
description String Mostly Description of a show

Note

You can use double quotes to get exact matches for fields like name or channel. (example: name:"ZDF heute", encoded: show%3A%22ZDF%20heute%22).

Note

Image resources like thumbnails can be downloaded both via HTTP and HTTPS.

Query show by ID

There is an extra endpoint for an alternative method to make an API request for a certain show:

https://api.fernsehsuche.de/[APIVERSION]/shows/{ID}/

By appending the id of a show to the shows endpoint you get directly to the desired show.

channels

A channel is a TV station with its own broadcasting schedule. Different channels can use the same media centre, which is e.g. the case for the german “Dritte Programme” like WDR or BR all using one ARD media centre.

Some examples for channels:

  • Das Erste
  • ZDF
  • RTL
  • WDR
  • n-tv
  • VOX
  • Arte

Endpoint

https://api.fernsehsuche.de/[APIVERSION]/channels/

The channels endpoint is a simple endpoint which returns a list of all channels available. It takes no extra arguments.

The returning result will look like the following.

Response:

{
        response:{
                numFound:22,
                start:0,
                docs:[
                {
                        name: "Das Erste",
                        channel_group: "M",
                        url: "http://mediathek.daserste.de/",
                        info_url: "http://www.daserste.de/",
                        channel_id: 4
                },
                {
                        #More channels
                }
                ]
        }
}

Field description

In the following table you can find a description of the fields returned together with a result object.

Field name Data type Available Description
name String Always Name of the channel
channel_group Enum Always Group of the channel (e.g. (M|”Hauptsender”))
url URL Always URL of the media center of the channel
info_url URL Always URL of the info (main) page of the channel
channel_id Integer Always ID of the channel

genres

The endpoint genres is a utility endpoint for getting a list of available genres structuring show or video results into genres and for mapping genre short names like “NA” to a human-readable variant like “Nachrichten”.

Some examples for genres:

  • Nachrichten
  • Dokumentationen
  • Serien
  • Krimis
  • Kochsendungen

Endpoint

https://api.fernsehsuche.de/[APIVERSION]/genres/

The genres endpoint is a simple endpoint which returns a list of all genres available. It takes no extra arguments.

The returning result will look like the following.

Response:

{
        response:{
                numFound:18,
                start:0,
                docs:[
                {
                        name: "Nachrichten",
                        genre_id: "NA",
                        slug: "nachrichten",
                        name_plural: "Nachrichten"
                },
                {
                        #More genres
                }
                ]
        }
}

Field description

In the following table you can find a description of the fields returned together with a result object.

Field name Data type Available Description
name String Always Name of the genre
genre_id Enum Always ID string of the genre
slug String Always URL compatible name version
name_plural String Always Simplified plural name version