API

Provides programmable access to coded election programmes from the Manifesto Corpus and to the Manifesto Project's Main Dataset. The API returns JSON and you don't need to specify ".json" at the end of an API URL. All functions (except for list_core_versions, list_metadata_versions, get_core_codebook, get_core_citation, get_corpus_citation) must provide a valid api_key parameter value.

Prerequisites

  • Manifesto Project Database Account (simply sign up on this webpage)
  • Manifesto Project Database API Key (simply login to your account, go to your profile page and generate an API key)

Functions

  • list_core_versions: list all core dataset versions
    • optional parameter: kind (can be "south_america" to get the south american datasets)
  • list_metadata_versions: list all corpus metadata versions
    • optional parameter: tag (can be "true" to separate version numbers (e.g. "20150522123537") and version tags (e.g. "2015-1") into two different attributes "name" and "tag" for each version)
    • optional parameter: details (can be "true" to get also - if existing - the release notes as an additional attribute "description" for each version; this parameter ignores the provided value for the tag parameter and automatically sets the tag parameter to "true")
  • get_core: get core dataset
    • parameter: key (e.g. "key=MPDS2015a")
    • optional parameter: kind (can be dta, xlsx or sav); the binary content of these files is base64 encoded in the content-node of the json; depending on the availability of further application-version specific datasets on the download page (e.g. stata14 for MPDS2016a) you can also query these files (by using their names, which in the example would be stata14)
    • optional parameter: raw (can be true, all other values are treated as false); sends the file directly without wrapping in json
  • metadata: get corpus metadata for a list of parties in elections
    • parameter: keys (e.g. "keys[]=41320_200909&keys[]=41320_200509"); valid key values are provided by get_core, but you need to combine the party and the date column
    • parameter: version (e.g. "version=2015-3"); valid values are provided by list_metadata_versions
  • texts_and_annotations: get texts and annotations of the coded manifestos:
    • parameter: keys (e.g. keys[]=41320_2009); valid key values are provided by the manifesto_id properties of metadata responses (hint: this key value returned by metadata can be different to the key initially used to query metadata)
    • parameter: version (e.g. "version=2015-3"); valid values are provided by list_metadata_versions
  • get_core_codebook: get codebook (chapter) for core dataset; esp. get codes, labels and detailed definitions for all the coded categories.
    • parameter: key (e.g. "key=MPDS2017b"); version of the core dataset (currently only codebooks from MPDS2017b onwards are available)
    • optional parameter: kind (can be categories); which part of the codebook should be retrieved (currently only the categories part is implemented)
  • get_core_citation: get citation for core dataset
    • parameter: key (e.g. "key=MPDS2015a")
  • get_corpus_citation: get citation for corpus dataset
    • parameter: key (e.g. "key=2015-3")

Access

  • All functions are rooted below https://manifesto-project.wzb.eu/api/v1/, thus the API is basically versioned but so far only version 1 is existing.
  • Examples of API-requests can be found in the examples section below.

Hints

  • Version Names: Keep in mind that we have two different version naming systems in place and that some of the functions require the one for the dataset (e.g. MPDS2015a) or others the one for the corpus (e.g. 2015-3).
  • GET Request Limits: To avoid problems with regard to the size of your GET requests you can also use POST requests for the two possibly parameter-heavy API functions metadata and texts_and_annotations.

Changelog

  • 2021-05-27: the kind value of items of texts_and_annotations responses is changed to an empty string as document metadata should generally be queried directly via metadata instead of being indirectly exposed by the text retrieval functions (and so far the kind value was also wrong for documents without annotations)
  • 2021-02-01: changed default api root to https://manifesto-project.wzb.eu/api/v1/ (which is a 1-to-1 copy of the old one at https://manifesto-project.wzb.eu/tools/ only the prefix api_ of all api-functions has been removed and the .json suffix is now optional)
  • 2018-07-04: added details parameter for list_metadata_versions
  • 2018-03-23: added get_core_codebook function
  • 2016-04-21: added raw parameter for get_core
  • 2016-03-01: added kind parameter for get_core
  • 2015-09-14: initial stable API release

Examples

  • https://manifesto-project.wzb.eu/api/v1/list_core_versions?api_key=<key>
  • https://manifesto-project.wzb.eu/api/v1/metadata?api_key=<key>&keys[]=41320_200909&keys[]=41320_200509&version=2015-3
  • https://manifesto-project.wzb.eu/api/v1/texts_and_annotations?api_key=<key>&keys[]=41320_2009&version=2015-3