# V-Dem Democracy Indices — Country-Year v16 (`aitorsm/vdem-democracy-indices`) Actor

Query any of the 288 V-Dem Country-Year Core v16 variables with codebook labels, confidence bounds, and dataset version metadata.

- **URL**: https://apify.com/aitorsm/vdem-democracy-indices.md
- **Developed by:** [Aitor Sanchez-Mansilla](https://apify.com/aitorsm) (community)
- **Stats:** 1 total users, 0 monthly users, 0.0% runs succeeded, 1 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.50 / 1,000 data points

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## 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

```json
{
  "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:

```json
{
  "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):

```json
{
  "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.

# Actor input Schema

## `countries` (type: `array`):

V-Dem country names or country\_text\_id codes, one per line. Use all by itself for every country. Unknown countries return an empty result.

## `indices` (type: `array`):

Pick one or more V-Dem variables. The five high-level democracy indices come first; the rest of the Core v16 catalogue (288 variables) follows, alphabetically by code.

## `startYear` (type: `integer`):

First country-year to include, from 1789 through 2025.

## `endYear` (type: `integer`):

Last country-year to include, from the first year through 2025. Defaults to the first year.

## `maxRows` (type: `integer`):

Stop after this many rows. Batch runs allow 1 to 10,000 rows.

## `listVariables` (type: `boolean`):

Return the variable catalogue (name, codebook label, section, bounds, and year/country coverage) in the VARIABLES key-value record instead of data rows. No dataset items are pushed, so only the Actor start is charged.

## `search` (type: `string`):

With List variables: keep only variables whose name, label, or section contain every keyword, for example corruption.

## `refreshSource` (type: `boolean`):

Reload the v16 data and replace the cached snapshot before querying. This can be slow; false uses the bundled, dated v16 snapshot.

## Actor input object example

```json
{
  "countries": [
    "USA",
    "GBR",
    "Mexico"
  ],
  "indices": [
    "electoral",
    "v2x_corr",
    "v2x_freexp_altinf"
  ],
  "startYear": 2024,
  "endYear": 2024,
  "maxRows": 10000,
  "listVariables": false,
  "refreshSource": false
}
```

# Actor output Schema

## `overview` (type: `string`):

No description

## `runSummary` (type: `string`):

No description

## `variables` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "countries": [
        "USA"
    ],
    "indices": [
        "electoral",
        "liberal",
        "participatory",
        "deliberative",
        "egalitarian"
    ],
    "startYear": 2024,
    "endYear": 2024
};

// Run the Actor and wait for it to finish
const run = await client.actor("aitorsm/vdem-democracy-indices").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "countries": ["USA"],
    "indices": [
        "electoral",
        "liberal",
        "participatory",
        "deliberative",
        "egalitarian",
    ],
    "startYear": 2024,
    "endYear": 2024,
}

# Run the Actor and wait for it to finish
run = client.actor("aitorsm/vdem-democracy-indices").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "countries": [
    "USA"
  ],
  "indices": [
    "electoral",
    "liberal",
    "participatory",
    "deliberative",
    "egalitarian"
  ],
  "startYear": 2024,
  "endYear": 2024
}' |
apify call aitorsm/vdem-democracy-indices --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,aitorsm/vdem-democracy-indices"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/bgjMV1CGrKUbvhYif/builds/9tL9clHUWc02hx3U3/openapi.json