API Documentation

All data on Open Parliament TV can be requested via our Open Data API. There is currently no limit on requests nor do you need an api key. But please get in touch if you plan to copy our entire dataset. Instead of making millions of api requests you can just get an SQL dump from us.
Entity URIs are based on the respective platform URL and can be formed by simply adding /api/v1 before the entity part.

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

GET Speech

Media IDs contain info about the parliament, electoral period and session. You should however not try to guess those IDs (eg. based on the order of speeches). This might work in some cases, it will not in many others.

Endpoint: /api/v1/media/ID
Example: Speech
URI

GET Person

Person IDs are always a Wikidata ID.

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

GET Organisation

Organisation IDs are always a Wikidata ID.

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

GET Document

Document IDs are internal incremental IDs and contain no reference to the document numbers (like "Drucksache 19/1234"). The rationale for this is that documents can be official documents as well as law texts and potentially other types of documents, sometimes applying to a specific parliament, sometimes generic, sometimes having a Wikidata ID, sometimes not. If you want to get a document by its official document number, you can use the document search.

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

GET Term

Term IDs are always a Wikidata ID.

URI

GET Electoral Period

Electoral Period IDs can safely be referenced by the parliament shortcode plus the respective number.

Endpoint: /api/v1/electoralPeriod/ID
Example: Electoral Period 19 of the German Bundestag (ID: "DE-019")
URI

GET Session

Session IDs can safely be referenced by the parliament shortcode plus the respective numbers.

Endpoint: /api/v1/session/ID
Example: Session 61 in Electoral Period 19 of the German Bundestag (ID: "DE-0190061")
URI

GET Agenda Item

Agenda Item IDs are built of the parliament shortcode and an incremental ID. You should not try to guess those IDs (eg. based on the order of agenda items). This might work in some cases, it will not in many others.

Endpoint: /api/v1/agendaItem/ID
Example: Agenda Item "Gesetzliche Rentenversicherung" in Session 61 in Electoral Period 19 of the German Bundestag (ID: "DE-454")
URI
The API structure is based on the JSON:API Specification. Whether or not we will fully implement the standard (also for PATCH requests / data updates) is to be discussed.

Paths

API Documentation
/api

API Endpoint Base URL
/api/v1

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"
  }
}