API Dokumentation

Alle Daten auf Open Parliament TV können über unsere Open Data API abgefragt werden. Es gibt im Moment weder ein Limit für Anfragen noch benötigst du einen API Key. Aber bitte melde dich bei uns wenn du vor hast, unser gesamtes Datenset zu kopieren. Anstatt Millionen von Anfragen an unsere API zu senden, kannst du einfach einen SQL Dump von uns bekommen.
Entitäten URIs basieren auf der entsprechenden Plattform-URL und können gebildet werden, indem /api/v1 vor der Entität eingefügt wird.

Beispiel:
https://de.openparliament.tv/person/Q567
https://de.openparliament.tv/api/v1/person/Q567

GET Redebeitrag

Redebeitrag IDs enthalten Informationen über das Parlament, die Wahlperiode und die Sitzung. Du solltest aber nicht versuchen, diese IDs zu erraten (z.B. basierend auf der Reihenfolge der Reden). Dies mag in manchen Fällen funktionieren, in vielen Fällen aber nicht.

Endpoint: /api/v1/media/ID
Beispiel: Redebeitrag
URI

GET Person

Person IDs sind immer eine Wikidata ID.

Endpoint: /api/v1/person/ID
Beispiel: Angela Merkel (Wikidata ID Q567)
URI

GET Organisation

Organisation IDs sind immer eine Wikidata ID.

Endpoint: /api/v1/organisation/ID
Beispiel: Fraktion BÜNDNIS 90/DIE GRÜNEN (Wikidata ID Q1007353)
URI

GET Dokument

Dokument IDs sind interne inkrementelle IDs und enthalten keinerlei Referenz auf Drucksachen-Nummern (wie "Drucksache 19/1234"). Der Hintergrund ist, dass Dokumente sowohl Drucksachen als auch Gesetzestexte oder potentiell auch andere Typen von Dokumenten sein können, welche sich manchmal auf ein Parlament beziehen, manchmal allgemein sind, manchmal eine Wikidata ID haben, manchmal nicht. Um Dokumente basierend auf der Drucksachen-Nummer zu suchen, verwende bitte die Dokumenten-Suche.

Endpoint: /api/v1/document/ID
Beispiel: Drucksache 19/1184
URI

GET Begriff

Begriff IDs sind immer eine Wikidata ID.

URI

GET Wahlperiode

Wahlperiode IDs können zuverlässig über das Parlaments-Kürzel und die ensprechende Nummer referenziert werden.

Endpoint: /api/v1/electoralPeriod/ID
Beispiel: Wahlperiode 19 des Deutschen Bundestages (ID: "DE-019")
URI

GET Sitzung

Sitzung IDs können zuverlässig über das Parlaments-Kürzel und den ensprechenden Nummern referenziert werden.

Endpoint: /api/v1/session/ID
Beispiel: Sitzung 61 in Wahlperiode 19 des Deutschen Bundestages (ID: "DE-0190061")
URI

GET Tagesordnungspunkt

Tagesordnungspunkt IDs bestehen aus dem Parlaments-Kürzel und einer inkrementellen ID. Du solltest jedoch nicht versuchen, diese IDs zu erraten (z.B. basierend auf der Reihenfolge der Tagesordnungspunkte). Dies mag in manchen Fällen funktionieren, in viele Fällen aber nicht.

Endpoint: /api/v1/agendaItem/ID
Beispiel: Tagesordnungspunkt "Gesetzliche Rentenversicherung" in Sitzung 61 in Wahlperiode 19 des Deutschen Bundestages (ID: "DE-454")
URI
Die API Struktur basiert auf der JSON:API Spezifikation. Ob wir diesen Standard vollständig implementieren (auch für PATCH Anfragen / Daten-Updates) ist noch in der Diskussion.

Pfade

API Dokumentation
/api

API Endpoint Base URL
/api/v1

Um widersprüchliche Versionen zu vermeiden existiert die Spezifikation nur auf Englisch.

API Responses

Responses MUST include the following properties for any request (GET and POST):

{
  "meta": {
	"api": {
	  "version": "1.0",
	  "documentation": "https://de.openparliament.tv/api",
	  "license": {
		"label": "ODC Open Database License (ODbL) v1.0",
		"link": "https://opendatacommons.org/licenses/odbl/1-0/"
	  }
	},
	"requestStatus": "success" // OR "error"
  },
  "data": [], // {} OR []
  "errors": [], // EITHER "data" OR "errors"
  "links": {
	"self": "https://de.openparliament.tv/api/v1/search/media?q=Rente" // request URL
  }
}

Successful requests MUST include the following properties:

{
  "meta": {
	"api": {
	  "version": "1.0",
	  "documentation": "https://de.openparliament.tv/api",
	  "license": {
		"label": "ODC Open Database License (ODbL) v1.0",
		"link": "https://opendatacommons.org/licenses/odbl/1-0/"
	  }
	},
	"requestStatus": "success"
  },
  "data": {},
  "links": {
	"self": "https://de.openparliament.tv/api/v1/search/media?q=Rente" // request URL
  }
}

Errors MUST include the following properties:

{
  "meta": {
	"api": {
	  "version": "1.0",
	  "documentation": "https://de.openparliament.tv/api",
	  "license": {
		"label": "ODC Open Database License (ODbL) v1.0",
		"link": "https://opendatacommons.org/licenses/odbl/1-0/"
	  }
	},
	"requestStatus": "error"
  },
  "errors": [
	{
	  "meta": {
		"domSelector": "" // optional
	  },
	  "status": "422", // HTTP Status   
	  "code": "3", 
	  "title":  "Invalid Attribute",
	  "detail": "First name must contain at least three characters."
	}
  ],
  "links": {
	"self": "https://de.openparliament.tv/api/v1/search/media?q=Rente" // request URL
  }
}

Data Objects

Data Objects MUST always include the properties:

  • id
  • type
  • attributes (data item specific properties)

Additionally Data Objects CAN include the properties:

  • links ("self" = link to the respective API request URL)
  • relationships (properties derived from other data items)

Depending on the context, the attributes object can only include a subset of all properties. The full set can then be retrieved via an API request to links > self.

This principle SHOULD be applied on all levels of the data structure.

Examples

Example for an Entity Response:

{
  "meta": {
	"api": {
	  "version": "1.0",
	  "documentation": "https://de.openparliament.tv/api",
	  "license": {
		"label": "ODC Open Database License (ODbL) v1.0",
		"link": "https://opendatacommons.org/licenses/odbl/1-0/"
	  }
	},
	"requestStatus": "success"
  },
  "data": {
	"type": "media",
	"id": "DE-198765837",
	"attributes": {},
	"relationships": {
	  "documents": {
		"data": [
		  {
			"type": "document",
			"id": "201",
			"attributes": {},
			"links": {
			  "self": "https://de.openparliament.tv/api/v1/document/201"
			}
		  }
		],
		"links": {
		  "self": "https://de.openparliament.tv/api/v1/searchAnnotations?mediaID=DE-198765837&type=document"
		}
	  }
	},
	"links": {
	  "self": "https://de.openparliament.tv/api/v1/media/DE-198765837"
	}
  }
}

Example for a Search Response:

{
  "meta": {
	"api": {
	  "version": "1.0",
	  "documentation": "https://de.openparliament.tv/api",
	  "license": {
		"label": "ODC Open Database License (ODbL) v1.0",
		"link": "https://opendatacommons.org/licenses/odbl/1-0/"
	  }
	},
	"requestStatus": "success",
	"results": {
	  "count": 25,
	  "total": 128,
	  "rangeStart": 51,
	  "rangeEnd": 75,
	  "maxScore": 4.7654785 /* float or null */
	}
  },
  "data": [],
  "links": {
	"self": "https://de.openparliament.tv/api/v1/search/people?party=CDU&page[number]=3&page[size]=25",
	"first": "https://de.openparliament.tv/api/v1/search/people?party=CDU&page[number]=1&page[size]=25",
	"prev": "https://de.openparliament.tv/api/v1/search/people?party=CDU&page[number]=2&page[size]=25",
	"next": "https://de.openparliament.tv/api/v1/search/people?party=CDU&page[number]=4&page[size]=25",
	"last": "https://de.openparliament.tv/api/v1/search/people?party=CDU&page[number]=13&page[size]=25"
  }
}