download_wid: Download data from WID.world

In wid: Download Data from the World Inequality Database

Download data from WID.world

Description

Downloads data from the World Wealth and Income Database (https://wid.world) into a data.frame. Type vignette("wid-demo") for a detailed presentation.

Usage

download_wid(
  indicators = "all",
  areas = "all",
  years = "all",
  perc = "all",
  ages = "all",
  pop = "all",
  metadata = FALSE,
  score_filter = NULL,
  verbose = FALSE
)

Arguments

indicators	List of six-letter strings, or "all": code names of the indicators in the database. Default is "all" for all indicators. See 'Details' for more.
areas	List of strings, or "all": area code names of the database. "XX" for countries/regions, "XX-YY" for infra-national regions. "XX-YYY" for supra-national regions. Default is "all" for all areas. See 'Details' for more.
years	Numerical vector, or "all": years to retrieve. Default is "all" for all years.
perc	List of strings, or "all": percentiles take the form "pXX" or "pXXpYY". Default is "all" for all percentiles. See 'Details' for more.
ages	Numerical vector, or "all": age category codes in the database. 999 for all ages, 992 for adults. Default is "all" for all age categories. See 'Details' for more.
pop	List of characters, or "all": type of population. "t" for tax units, "i" for individuals. Default is "all" for all population types. See 'Details' for more.
metadata	Should the function fetch metadata too (ie. variable descriptions, sources, methodological notes, etc.)? Default is FALSE.
score_filter	Optional data quality score filter. A single number is interpreted as a minimum row_score. You can also use a named list with row_score and/or series_score; each value can be a minimum, a two-number inclusive range, or a list with min and/or max.
verbose	Should the function indicate the progress of the request? Default is FALSE.

Details

Although all arguments default to "all", you cannot download the entire database by typing download_wid(). The command requires you to specify either some indicators or some areas. To download the entire database, please visit https://wid.world/data/ and choose "download full dataset".

If there is no data matching you selection on WID.world (maybe because you specified an indicator or an area that doesn't exist), the command will return NULL with a warning.

All monetary amounts for countries and country subregions are in constant local currency of the reference year (i.e. the previous year, the database being updated every year around July). Monetary amounts for world regions are in EUR PPP of the reference year. You can access the price index using the indicator inyixx, the PPP exchange rates using xlcusp (USD), xlceup (EUR), xlcyup (CNY), and the market exchange rates using xlcusx (USD), xlceux (EUR), xlcyux (CNY). To check the current reference year, you can look at when the price index is equal to 1.

Shares and wealth/income ratios are given as a fraction of 1. That is, a top 1% share of 20% is given as 0.2. A wealth/income ratio of 300% is given as 3.

The arguments of the command follow a nomenclature specific to WID.world. We provide more details with a few examples below. For the complete up-to-date documentation of the structure of the database, please visit https://wid.world/codes-dictionary/.

Indicators

The argument indicators is a vector of 6-letter codes that corresponds to a given series type for a given income or wealth concept. The first letter correspond to the type of series. Some of the most common possibilities include:

one-letter code		description
a		average (local currency unit, last year’s prices)
b		inverted Pareto-Lorenz coefficient
f		female population (fraction between 0 and 1)
g		Gini coefficient (between 0 and 1)
i		index
n		population
s		share (fraction between 0 and 1)
t		threshold (local currency unit, last year’s prices)
m		total (local currency unit, last year’s prices)
p		proportion of women (fraction between 0 and 1)
w		wealth-to-income ratio or labor/capital share (fraction of national income)
r		Top 10/Bottom 50 ratio
x		exchange rate (market or PPP)
e		Total emissions (tons of CO2 equivalent emissions)
k		Per capita emissions (tons of CO2 equivalent emissions)
l		Average per capita group emissions (tons of CO2 equivalent per capita emissions)

The next five letters correspond a concept (usually of income and wealth). Some of the most common possibilities include:

five-letter code		description
ptinc		pre-tax national income
pllin		pre-tax labor income
pkkin		pre-tax capital income
fiinc		fiscal income
hweal		net personal wealth

For example, sfiinc corresponds to the share of fiscal income, ahweal corresponds to average personal wealth. If you don't specify any indicator, it defaults to "all" and downloads all available indicators. Check https://wid.world/codes-dictionary/ for a full list of codes.

Area codes

All data in WID.world is associated to a given area, which can be a country, a region within a country, an aggregation of countries (eg. a continent), or even the whole world. The argument areas is a vector of codes that specify the areas for which to retrieve data. Countries and world regions are coded using 2-letter ISO codes. Country subregions are coded as XX-YY where XX is the country 2-letter code. If you don't specify any area, it defaults to "all" and downloads data for all available areas.

Years

All data in WID.world correspond to a year. Some series go as far back as the 1800s. The argument years is a vector of integer that specify those years. If you don't specify any year, it defaults to "all" and downloads data for all available years.

Percentiles

The key feature of WID.world is that it provides data on the whole distribution, not just totals and averages. The argument perc is a vector of strings that indicate for which part of the distribution the data should be retrieved. For share and average variables, percentiles correspond to percentile ranges and take the form pXXpYY. For example the top 1% share correspond to p99p100. The top 10% share excluding the top 1% is p90p99. Thresholds associated to the percentile group pXXpYY correspond to the minimal income or wealth level that gets you into the group. For example, the threshold of the percentile group p90p100 or p90p91 correspond to the 90% quantile. Variables with no distributional meaning use the percentile p0p100. If you don't specify any percentile, it defaults to "all" and downloads data for all available parts of the distribution.

Age groups

Data may only concern the population in a certain age group. The argument ages is a vector of age codes that specify which age categories to retrieve. Ages are coded using 3-digit codes. Some of the most common possibilities include:

three-digit code		description
999		all ages
014		ages 0 to 14
156		ages 15 to 64
997		ages 65 and older
991		ages below 20
992		ages 20 and older

If you don't specify any age, it defaults to "all" and downloads data for all available age groups. Visit https://wid.world/codes-dictionary/ for a comprehensive list of options.

Population types

The data in WID.world can refer to different types of population (i.e. different statistical units). The argument pop is a vector of population codes. They are coded using one-letter codes. Some of the most common possibilities include:

one-letter code		description
i		individuals
j		equal-split adults (i.e., income or wealth divided equally among spouses)
m		male
f		female
t		tax unit
e		employed

If you don't specify any code, it defaults to "all" and downloads data for all available populations.

Data quality score filters

Use score_filter to keep observations or country-series above a data quality threshold. For example, score_filter = 3 keeps observations with row_score >= 3, while score_filter = list(series_score = 4) keeps country-series with series_score >= 4. A two-number vector gives an inclusive range, e.g. list(row_score = c(3, 5)).

Value

A data.frame with the following columns:

country

The country or area code.

variable

The variable name, which combine the indicator, the age code and the population code.

percentile

The part of the distribution the value relates to.

year

The year the value relates to.

value

The value of the indicator.

If you specify metadata = TRUE, the data.frame also has the following columns:

countryname

The full name of the country/region.

shortname

A short version of the variable full name in plain english.

shortdes

A description of the type of series.

pop

The population type, in plain english.

age

The age group, in plain english.

source

The source for the data.

row_score

Observation-level data quality score. Since 2026, this score varies by country, series, and year.

series_score

Country-series data quality score. It is a weighted average of row_score over years, with greater weight on more recent observations.

method

Methodological notes, if any.

Author(s)

Thomas Blanchet, with updates by Ignacio Flores

wid documentation built on July 9, 2026, 1:07 a.m.