GETTING STARTED

Introduction

The fernsehsuche.de API is a restful API queried with HTTPS GET requests. The main entry point to the API is defined by the following domain in combination with the current version of the API.

Syntax:

HTTPS/1.1 GET
https://api.fernsehsuche.de/[APIVERSION]/

This API is based on Apache Solr, so it is possible, that additional features from the Apache Solr docs will also work for this API, though only features described in this documentation are officially supported and are safe to rely on.

Authentication / Security

To access this API, an API key is needed which is passed as a GET parameter for authentication. All requests (except for requesting resources like images) have to be done over a secure HTTS connection.

Syntax:

HTTPS/1.1 GET
https://api.fernsehsuche.de/[APIVERSION]/?api_key={api_key}

Encoding

Encoding for both requests and responses is UTF-8. Both reserved characters and UTF-8 chars in GET requests have to be percent-encoded (Wikipedia).

Here is an example for a request where title:göttingen shall be passed to the parameter q:

https://api.fernsehsuche.de/[APIVERSION]/videos/?q=title%3Ag%C3%B6ttingen

The reserved character : is percent-encoded as %3A, the unicode character ö is percent-encoded as %C3%B6.

There are several online services available to test URL encoding, e.g. here.

Responses

The following is an example for a complete request against the fernsehsuche.de API.

Example:

HTTPS/1.1 GET
https://api.fernsehsuche.de/v1/videos/?q=Merkel

The request is querying against the APIVERSION named v1 and the endpoint videos and is using the q search parameter to get the latest videos from media centers about the german chancelor Angela Merkel.

The response to this request will look similar to the following.

Example:

{
        response:{
                numFound:739,
                start:0,
                maxScore:1.9724882,
                docs:{
                        show:"ARD-Sondersendung",
                        duration:"2010-01-01T00:41:00Z",
                        title:"ARD-Sondersendung: Die Regierungserklärung von Bundeskanzlerin Merkel",
                        channel_group:"M",
                        channel_url:"http://mediathek.daserste.de/",
                        thumbnail:"/media/thumbnails/dds/0ba3a69095d04ca864a7c1fb6b4dca10ab3580b4.jpg",
                        channel:"Das Erste",
                        description:"ARD-Sondersendung: Die Regierungserklärung von Bundeskanzlerin Merkel",
                        air_date:"2012-10-18T00:00:00Z",
                        show_id:1,
                        air_time:"2010-01-01T09:00:00Z",
                        genre:"NA",
                        show_url:"http://mediathek.daserste.de/sendungen_a-z/3304234_ard-sondersendung",
                        url:"http://mediathek.daserste.de/sendungen_a-z/3304234_ard-sondersendung/12164324_ard-sondersendung-die-regierungserklaerung-von",
                        video_id:61348,
                        channel_id:4
                }
        }
}

A response is enveloped by a key response providing some information about the response with attributes like numFound displaying the number of the found results. The key docs contains the actual query result objects.

Output Format

The standard output format for a request is JSON. It is also possible to change the output format with an additional GET parameter format:

Parameter Possible Values Description
format json, xml Output in JSON or XML format

Search Queries

Data from all endpoints can be accessed via a Solr full text search by using the q parameter in your request. This makes especially sense for the videos endpoint.

Range queries

Especially for date or time fields it often makes sense to pass a range to get the desired search results. The format of a range query looks like the following: field:[* TO 100]. So this would be a query to search for videos containing “Obama” in the title and being newer

Example:

HTTPS/1.1 GET
Query string: title:merkel AND air_date:[2013-09-01T00:00:00Z TO *]
Encoded URL: /videos/?q=title%3Amerkel%20AND%20air_date%3A%5B2013-09-01T00%3A00%3A00Z%20TO%20%2A%5D

Note

At the moment time fields are stored in the systems as date fields with a static date component, e.g. air_time: "2010-01-01T21:45:00Z". So ranges for time fields like air_time or duration are queried by leaving the static date component 2010-01-01 as is and just changing the time part T21:45:00Z.

Highlighting

Matches of search terms in different fields of a document can be shown with the higlighting feature. If hl=true is provided as a query param the highlighted fields are shown in the results, e.g. for a search for videos in XML format:

<doc>
   <show>Die Wahl bei uns</show>
   ...
   <highlighted>
      <title>"Frau <em>Merkel</em> ist am Zug"</title>
   </highlighted>
</doc>
Parameter Description
hl Highlighting of results

More information about configuration of highlighting can be found in the corresponding Solr documentation section. One difference to Solr behaviour is, that highlighting fields can’t be selected with the hl.fl parameter. Instead the api is always showing all matches for the content fields where highlighting makes sense (e.g. title, description, show_name,...).

Sorting

Normally results of API requests are ordered by an internal boost factor indicating the quality of a match. A request with a search parameter q=Merkel for example will have the results pushed to the top where Angela Merkel is mentioned most often in the text.

This behaviour can be changed with the sort parameter:

Parameter Description
sort Sorting of search results

The sort parameter can be given any attribute of the endpoint you are requesting results from together with the keywords desc or asc for the sorting order. It is also possible to provide more than one attribute as a sorting directive, which is especially useful if you want to sort by air_date and air_time together (which is a common use case).

Querying all videos about Angela Merkel with the newest videos on top would look like the following.

Example:

HTTPS/1.1 GET
Query string: title:merkel
Parameter sort: air_date DESC,air_time DESC
Encoded URL: /videos/?q=title%3Amerkel&sort=air_date%20DESC%2Cair_time%20DESC

This will sort by air_date in a descending order. For equal air dates, it will sort by air_time in a descending order.

Error Handling

The most common malformed requests are responded with an appropriate HTTP code together with a message informing you what went wrong. E.g. if you forget the API key as a parameter the response will send back an HTTP 401 Unauthorized response code.

For a JSON request a response looks like this:

{
    "error" : {
        "msg": "Authorization required.",
        "code": 401
    }
}

For an XML request a response looks like this:

<error>
    <msg>Authorization required.</msg>
    <code>401</code>
</error>

The following error messages are available:

Code Message
401 Authorization required.
403 Access not allowed, eventually you have to turn on https.
404 Page could not be found.
410 This api version is outdated and is no longer maintained.
500 Server error, service temporarily unavailable.