GET Discours

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.

GET Personne

Person IDs are always a Wikidata ID.

GET Organisation

Organisation IDs are always a Wikidata ID.

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.

GET Terme

Terme IDs are always a Wikidata ID.

GET Législature

Législature IDs can safely be referenced by the parliament shortcode plus the respective number.

GET Session

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

GET Point de l'ordre du jour

Point de l'ordre du jour 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.

• General Statistics
• Entity Statistics
• Word Trends
• Entity Counts

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