V-Dem Democracy Indices — Country-Year v16

Query any variable in the V-Dem Country-Year Core dataset without handling its 212 MB CSV yourself. Results are from the V-Dem Country-Year Core v16 release, published in March 2026. This Actor does not make live assessments; the newest year available in this version is 2025.

Coverage: 288 variables (every base variable in Core v16), 1789–2025, 202 countries, 28,092 country-years. 178 variables include V-Dem's confidence bounds.

What it does

The Actor ships a compact, columnar extract of every base variable in Country-Year Core v16. It also ships a variable catalogue with each variable's codebook label and section, whether it has bounds, and how many years and countries it covers. It returns one row per observed country, year, and variable. country_code is V-Dem's country_text_id, and index is the V-Dem variable name. Missing observations produce no row. Confidence bounds are null for variables that V-Dem publishes without _codelow/_codehigh columns, such as factual (A-type) indicators and v2x_suffr.

On a cold run, the Actor seeds a small row index into a versioned key-value-store cache. It then loads each requested variable from the bundle the first time that variable is requested. The extract was taken on 2026-09-25 and does not update automatically. Every row includes the dataset release, version, snapshot time, and current snapshot age. Set refreshSource: true to reload the v16 data and rebuild the cache for all 288 variables. If an explicit refresh fails, the run fails. The run's RUN_SUMMARY record includes the data checksum (SHA-256), data status, row counts, snapshot time, the variables served, and the stop reason.

Input

{
  "countries": ["ESP"],
  "indices": ["v2x_corr", "v2x_freexp_altinf", "electoral"],
  "startYear": 2020,
  "endYear": 2025,
  "maxRows": 10000,
  "refreshSource": false
}

countries accepts V-Dem names or country_text_id codes, or ["all"]. It defaults to USA; an unknown country returns an empty successful result. startYear defaults to 2024 and endYear defaults to startYear; valid years are 1789–2025. maxRows is 1–10,000 in batch mode. refreshSource defaults to false.

indices accepts:

• Any variable name in the catalogue, e.g. v2x_corr, v2mecenefm, or v2eltype_0. Letter case is ignored.
• The five headline aliases electoral, liberal, participatory, deliberative, and egalitarian, which map to v2x_polyarchy, v2x_libdem, v2x_partipdem, v2x_delibdem, and v2x_egaldem. They are the default.
• all, which returns the five headline indices plus every variable whose name starts with v2x_ (54 variables). The component families with other prefixes, such as v2xel_frefair, v2xcl_rol, and v2xeg_eqdr, are not in all; add them by name.

An unknown name fails the run with a clear message that lists the closest catalogue names. For example, v2x_corruption suggests v2x_corr first.

How to find a variable

Run the Actor with {"listVariables": true, "search": "corruption"}. This mode reads only the bundled catalogue. It writes the matches to the VARIABLES key-value record (also linked in the run's output tab) and pushes no dataset items, so only the Actor start is charged. Every whitespace-separated keyword must appear in the variable's name, codebook label, part, section, or subsection. Omit search to get all 288 entries. Each entry looks like this:

{
  "name": "v2x_corr",
  "label": "Political corruption index",
  "labelSource": "codebook_heading",
  "codebookEntry": "5.7.1 (v2x_corr)",
  "codebookType": "D",
  "part": "Other Indices Created Using V-Dem Data",
  "section": "Corruption",
  "subsection": null,
  "hasBounds": true,
  "companions": ["v2x_corr_sd"],
  "firstYear": 1789,
  "lastYear": 2025,
  "years": 237,
  "countries": 200,
  "observations": 27199
}

Labels are the headings of the V-Dem v16 codebook, which defines each variable's question, scale, and aggregation. Twelve multiple-selection columns (e.g. v2eltype_0) are labelled with their codebook response option. Two *_nr columns are labelled with their parent question plus the codebook's "number of coders" definition. companions lists the other Core columns for a variable (_sd, _osp, _ord, _mean, _nr, and so on). These are documented for reference but are not returned as rows. The same catalogue is available free at GET /variables.

Output

Example row (Spain, 2025; snapshot metadata varies):

{
  "country": "Spain",
  "country_code": "ESP",
  "year": 2025,
  "index": "v2x_corr",
  "label": "Political corruption index",
  "value": 0.113,
  "ci_low": 0.083,
  "ci_high": 0.138,
  "source": "V-Dem Country-Year Core v16",
  "source_version": "v16",
  "source_fetched_at": "2026-09-25T15:04:40.919Z",
  "cache_age_hours": 0
}

Rows are ordered by year, then country code, then the order of the requested variables. ci_low and ci_high are V-Dem's published *_codelow and *_codehigh values, not bounds computed by this Actor. Values are the V-Dem values as published; scales differ by variable, so check the codebook entry before comparing variables.

Standby HTTP API

GET /query?country=ESP&index=v2x_corr&year=2025 returns JSON with rows, dataset metadata, sourceStatus, and truncated. Repeat or comma-separate country and index; index accepts any catalogue name, the aliases, or all. Use startYear, endYear, and maxRows for ranges. Add refreshSource=true only when you want to reload the data. Standby allows at most 500 rows per request. Valid empty queries return 200 and rows: []. Invalid inputs, including unknown variables (with suggestions), return 400. Data loading failures return 503, and a spending cap that cuts off results returns 402 with only the delivered rows.

GET /variables?search=corruption&limit=20 searches the catalogue and is not charged.

Pricing

The historical task proposed $0.001 per dataset row. That is a proposal, not a configured or verified Store price. In pay-per-event mode, the SDK's default-dataset-item event is charged by Actor.pushData(), and the Actor does not call Actor.charge() again. Catalogue lookups (listVariables, GET /variables) push no dataset items and charge nothing beyond the Actor start. Delivery stops at the platform spending cap, and RUN_SUMMARY.stopReason reports charge_limit_reached if rows were withheld. Local non-PPE runs still return data.

Use cases

• Compare democracy, corruption, media freedom, or any other V-Dem measure across country-years.
• Join V-Dem values to a country-year research table.
• Find a variable with free GET /variables, then request country-year rows with GET /query. AI agents can use Apify MCP to run a batch and retrieve its dataset.

Related Actors

No companion Actor is linked here until one has a verified listing.

FAQ

Is country_code ISO 3166? No. It is V-Dem's country_text_id. Many values resemble ISO codes, but this Actor does not promise ISO coverage.

Why are some country-years missing? V-Dem does not publish an observation for every variable and year. A missing value is omitted, and a missing confidence-bound column becomes null. The catalogue's firstYear, lastYear, years, and countries show each variable's coverage.

Can I get _sd, _osp, or _ord versions? Not as rows. The catalogue lists them under companions, but only base variables, with their _codelow/_codehigh bounds, are served.

Does an empty result indicate an outage? No. Empty matches succeed. Data loading, refresh, or cache failures fail the batch run or return 503 in Standby.

Can I request a different V-Dem release? No. This version supports Country-Year Core v16 only. The dataset version is fixed to prevent mixing measurements across releases.