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.
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 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.
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.
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 |
The response is limited to a certain number of results. To navigate through the result set, the following parameters can be used:
| Parameter | Default Value | Description |
|---|---|---|
| start | 0 | Response object to start with |
| rows | 10 | Number of results to show |
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.
By just providing your search query to the q parameter, you can do a full-text search over the entire index.
Example:
HTTPS/1.1 GET
Query string: Angela Merkel
Encoded URL: /videos/?q=Angela%20Merkel
By placing an attribute of an endpoint object in front of the search query it is possible to only search in the attribute field provided.
Example:
HTTPS/1.1 GET
Query string: title:obama
Encoded URL: /videos/?q=title%3Aobama
More complex query expressions can be formed with the boolean operators AND and OR.
Example:
HTTPS/1.1 GET
Query string: title:obama AND show:heute journal
Encoded URL: /videos/?q=title%3Aobama%20AND%20show%3Aheute%20journal
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.
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,...).
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.
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. |