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 (but only available until version 2022a as afterwards south america has been integrated directly into the main dataset. To enhance backward scripts compatibility an dummy version refering to an empty dataset is returned as its latest version.))
  • 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
  • get_parties: get list of parties
    • parameter: key (e.g. "key=MPDS2023a")
    • optional parameter: list_form (can be "short" (default) or "long")
    • optional parameter: raw (can be true, all other values are treated as false); sends the file directly without wrapping in json
    • hint: the list of parties is not available for all of the past datasets. You can check the availability by going to the datasets page and check for specific datasets whether they have party lists in the following formats "List – Short (CSV)" or "List – Long (CSV)" available. There you can also find the codebooks with details for these list of parties.
  • 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
    • hint: the list of metadata attributes can be found in the Manifesto Corpus documentation.
    • hint: the response contains a list "items" with the successfully retrieved metadata and a second list "missing_items" that contains all the requested keys for which no metadata could be found.
  • texts_and_annotations: get texts and annotations of the coded manifestos:
    • parameter: keys (e.g. keys[]=41320_200909); 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
    • optional parameter: translation (e.g. "en"); returns the translated text instead of the text in original language (for original languages that are already the desired translation language the original text is returned); valid values are currently en (for english); not setting the parameter results in receiving the original language text
    • hint: the response contains a list "items" with the successfully retrieved texts and a second list "missing_items" that contains all the requested keys for which no texts could be found. The latter can happen, as we do not have machine readable texts, digital annotations, or english translations for all of our data points, but you can simply use the metadata information for querying the availability of such data for a specific document beforehand.
  • 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.

Workflows

Using the API functions described above the common workflow to query corpus texts would likely be around the following steps:

  1. get the core dataset (get_core)
  2. filter the desired observations from this dataset and construct a list of queryable keys following the scheme <party>_<date> (e.g. 41320_200909)
  3. query the corpus metadata (metadata) for these keys
  4. filter availability of specific data (machine-readable texts, digital annotations, english translations) using the metadata information (e.g. "annotations" is true) and construct a list of queryable keys by using the "manifesto_id" metadata property
  5. query the corpus texts and annotations (texts_and_annotations) for these keys

You can find much more details on the general data structure, workflows, examples etc. in the vignette of our manifestoR R-package (PDF) which – even though it's focussed on the package and the R language – should provide you with valuable (context) information.

Changelog

  • 2024-05-08: added optional translation parameter for texts_and_annotations to enable receiving english translations instead of the original language text
  • 2024-03-22: added get_parties function
  • 2023-08-29: to enhance scripts backward compatibility list_core_versions(kind = "south_america"), get_core, and get_core_citation also contain a technical empty dummy dataset MPDSSA9999a as the latest version for the separate South America dataset (which has been directly integrated in the main dataset from version 2023a onwards)
  • 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/list_metadata_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
  • https://manifesto-project.wzb.eu/api/v1/texts_and_annotations?api_key=<key>&keys[]=41320_2009&translation=en&version=2024-1