Download Data from the European Social Survey on the Fly

Download data from the European Social Survey directly from their website <>. There are two families of functions that allow you to download and interactively check all countries and rounds available.

CRAN_Status_Badge Travis-CI BuildStatus Coveragestatus rOpensci_Badge


The European Social Survey (ESS) is an academically driven cross-national survey that has been conducted across Europe since its establishment in 2001. Every two years, face-to-face interviews are conducted with newly selected, cross-sectional samples. The survey measures the attitudes, beliefs and behaviour patterns of diverse populations in more than thirty nations. Taken from the ESS website.

Note: The essurvey package was originally called ess. Since essurvey 1.0.0 all ess_* functions have been deprecated in favour of the import_* and download_* functions. Also, versions less than and including essurvey 1.0.1 returned wrong countries. Please install the latest CRAN/Github version.

The essurvey package is designed to download the ESS data as easily as possible. It has a few helper functions to download rounds (a term synonym to waves to denote the same survey in different time points), rounds for a selected country and to show which rounds/countries are available. Check out the vignette and other documentation in the package’s website for more detailed examples of the essurvey package.


You can install and load the development version with these commands:

# install.packages("devtools") in case you don't have it

or the stable version with:



First, you need to register at the ESS website, in case you haven’t. Please visit the register section from the ESS website. If your email is not registered at their website, an error will be raised prompting you to go register.

Set your valid email as en environment variable.

set_email("[email protected]")

To explore which rounds/countries are present in the ESS use the show_*() family of functions.

#>  [1] "Albania"            "Austria"            "Belgium"           
#>  [4] "Bulgaria"           "Croatia"            "Cyprus"            
#>  [7] "Czech Republic"     "Denmark"            "Estonia"           
#> [10] "Finland"            "France"             "Germany"           
#> [13] "Greece"             "Hungary"            "Iceland"           
#> [16] "Ireland"            "Israel"             "Italy"             
#> [19] "Kosovo"             "Latvia"             "Lithuania"         
#> [22] "Luxembourg"         "Netherlands"        "Norway"            
#> [25] "Poland"             "Portugal"           "Romania"           
#> [28] "Russian Federation" "Serbia"             "Slovakia"          
#> [31] "Slovenia"           "Spain"              "Sweden"            
#> [34] "Switzerland"        "Turkey"             "Ukraine"           
#> [37] "United Kingdom"

To download the first round to use in R:

one_round <- import_rounds(1)

This will return a data frame containing the first round. Typically, the European Social Survey data files comes with a script that recodes missing values to NA for different programs (Stata, SPSS, SAS).

Use recode_missings to recode all values automatically.

one_round <-
  import_rounds(1) %>%

See the package vignette for greater detail or see the help page with ?recode_missings. You can also download several rounds by supplying the number of rounds.

five_rounds <- import_rounds(1:5)

This will download all latest versions of rounds 1 through 5 and return a list of length 5 with each round as a data frame inside the list.

You can check the available rounds with show_rounds() because if you supply a non existent round, the function will return an error.

two_rounds <- import_rounds(c(1, 22))
#> Error in ess_round_url(rounds) : 
#> ESS round 22 is not a available. Check show_rounds() 

Alternatively, you can download all available rounds with import_all_rounds().

You can also download rounds by country:

dk_two <- import_country("Denmark", 1:2)

Use show_countries() to see available countries and show_country_rounds("Denmark") to see available rounds for chosen country. Alternatively, use import_all_cntrounds() to download all available rounds of a country.

You should be be aware that data from the ESS survey should by analyzed by taking into consideration the sampling and weights of the survey. A useful example comes from the work of Anthony Damico and Daniel Oberski here.

Stata, SPSS and SAS users

I’m quite aware that most ESS users don’t know R, that is why the package also allows to download the data in Stata, SPSS or SAS format with just one line of code. Instead of the import_* functions, use the download_* functions.

download_rounds(c(1, 2),
                output_dir = "my/new/directory",
                format = 'spss')

This will save the ESS rounds into separate folders and unzip them in the specified directory (if you want to know your current directory, type getwd()). This works the same way for download_country(). Be aware that if you download the files manually you should read them into R with the haven package for all essurvey related functions to work.

Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.




essurvey 1.0.2

Minor changes

show_country_rounds checks if there are missing values and excludes them.

Breaking changes

import_all_cntrounds and import_country returned incorrect countries [#31]

essurvey 1.0.1

Minor changes

  • ess_email is now checked that it is not "" because it wasn't raising an error before.

  • Removes the round argument from import_all_cntrounds because it was a mistake. It already grabs the rounds internally.

essurvey 1.0.1

Minor release

  • Fixes test that checks the number of rounds that each country has. This test was a mistake because the rounds will change as time passes by and precise country rounds shouldn't be tested.

essurvey 1.0.0

The ess package has been renamed to essurvey for a name conflict with Emacs Speaks Statistics (ESS). See R-pkg mailing list, the post related to the release of ess-0-0-1.

Breaking changes

  • ess_rounds and ess_all_rounds are deprecated and will be removed in the next release. Use import_rounds instead [#22]

  • ess_country and ess_all_cntrounds are deprecated and will be removed in the next release. Use import_countries instead [#22]

  • The your_email argument name of ess_* functions has be changed to ess_email [#23]

New features

  • import_rounds, import_all_rounds and download_rounds have been introduced as replacements of ess_rounds and ess_all_rounds. Same changes were repeated for ess_country and ess_all_cntrounds [#22]

  • set_email to set your email as environmental variable rather than write it in each call [#23]

  • All requests to the ESS website are now done through HTTPS rather than HTTP [#24]

  • Add package level documentation [#20]

Minor changes

  • ess_email had no default value but now has NULL as default [#23]

  • The format argument is now checked through match.arg rathern than manual check [#25]

ess 0.1.1 (2018-03-05)

Breaking changes

  • Downloading 1 round both for countries or single rounds now returns a data frame rather than a list. If download is more than two rounds it returns a list. [#8]

New features

  • remove_missings() together with remove_numeric_missings() and remove_character_missings() now allow you to recode the typical categories 'Not applicable', 'Don't know', etc.. into NA's. See the vignette example for more details. [#1]

  • Can download files in 'stata', 'spss' and 'sas' formats for all functions (both for downloading to user's directory and for reading data). [#11]

  • show_themes() and show_theme_rounds() now available to see which themes have been included in which rounds. [#7]

  • show_rounds_country() is now available to see which countries participated in which rounds [#14]

Bug fixes

  • The ouput_dir argument is now set to getwd() rather than NULL as default. [#16]

  • When parsing country rounds from the ESS table from the website, shaded dots were being interpreted as valid rounds when in fact they're not. show_* funs new exclude shaded dots until they've been added as valid rounds

  • If any ess_* function can not connect to the ESS website they will return an explicit R error. [#12]

  • ess_all_cntrounds and ess_all_rounds were returning the directory of each of the files. Now they only return the single directory where the files where saved as a message

ess 0.0.1 (2017-11-07)

First release

Reference manual

It appears you don't have a PDF plugin for this browser. You can click here to download the reference manual.


1.0.8 by Jorge Cimentada, 20 days ago,

Report a bug at

Browse source code at

Authors: Jorge Cimentada [aut, cre] , Thomas Leeper [rev] (Thomas reviewed the package for rOpensci , see , Nujcharee Haswell [rev] (Nujcharee reviewed the package for rOpensci , see , Jorge Lopez [ctb] , François Briatte [ctb]

Documentation:   PDF Manual  

MIT + file LICENSE license

Imports xml2, httr, haven, rvest, tibble, utils

Suggests foreign, testthat, knitr, rmarkdown, covr

See at CRAN