Retrieves specific datasets from Nomis, based on their ID. To find dataset IDs, use nomis_data_info. Datasets are retrived in csv format and parsed with the read_csv function from the readr package into a tibble, with all columns parsed as character columns.

To find the code options for a given dataset, use nomis_get_metadata for specific codes, and nomis_codelist for code values.

This can be a slow process if querying significant amounts of data. Guest users are limited to 25,000 rows per query, although nomisr identifies queries that will return more than 25,000 rows, sending individual queries and combining the results of those queries into a single tibble. In interactive sessions, nomisr will warn you if guest users are requesting more than 350,000 rows of data, and if registered users are requesting more than 1,500,000 rows.

Note the difference between the time and date parameters. The time and date parameters should not be used at the same time. If they are, the function will retrieve data based on the the date parameter. If given more than one query, time will return all data available between those queries, inclusively, while date will only return data for the exact queries specified. So time = c("first", "latest") will return all data, while date = c("first", "latest") will return only the first and latest data published.

nomis_get_data(id, time = NULL, date = NULL, geography = NULL,
  sex = NULL, measures = NULL, additional_queries = NULL,
  exclude_missing = FALSE, select = NULL, tidy = FALSE,
  tidy_style = "snake_case", ...)

Arguments

id

The ID of the dataset to retrieve.

time

Parameter for selecting dates and date ranges. Accepts either a single date value, or two date values and returns all data between the two date values, There are two styles of values that can be used to query time.

The first is one or two of "latest" (returns the latest available data), "previous" (the date prior to "latest"), "prevyear" (the date one year prior to "latest") or "first" (the oldest available data for the dataset).

The second style is to use or a specific date or multiple dates, in the style of the time variable codelist, which can be found using the nomis_get_metadata function.

Values for the time and date parameters should not be used at the same time. If they are, the function will retrieve data based on the the date parameter.

Defaults to NULL.

date

Parameter for selecting specific dates. Accepts one or more date values. If given multiple values, only data for the given dates will be returned, but there is no limit to the number of data values. For example, date=c("latest, latestMINUS3, latestMINUS6") will return the latest data, data from three months prior to the latest data and six months prior to the latest data. There are two styles of values that can be used to query time.

The first is one or more of "latest" (returns the latest available data), "previous" (the date prior to "latest"), "prevyear" (the date one year prior to "latest") or "first" (the oldest available data for the dataset).

The second style is to use or a specific date or multiple dates, in the style of the time variable codelist, which can be found using the nomis_get_metadata function.

Values for the time and date parameters should not be used at the same time. If they are, the function will retrieve data based on the the date parameter.

Defaults to NULL.

geography

The code of the geographic area to return data for. If NULL, returns data for all available geographic areas, subject to other parameters. Defaults to NULL. In the rare instance that a geographic variable does not exist, if not NULL, the function will return an error.

sex

The code for sexes/genders to include in the dataset. Accepts a string or number, or a vector of strings or numbers. nomisr automatically voids any queries for sex if it is not an available code in the requested dataset.

There are two different codings used for sex, depending on the dataset. For datasets using "SEX", 7 will return results for males and females, 6 only females and 5 only males. Defaults to NULL, equivalent to c(5,6,7) for datasets where sex is an option. For datasets using "C_SEX", 0 will return results for males and females, 1 only males and 2 only females. Some datasets use "GENDER" with the same values as "SEX", which works with both sex = <code> and gender = <code> as a dot parameter.

measures

The code for the statistical measure(s) to include in the data. Accepts a single string or number, or a list of strings or numbers. If NULL, returns data for all available statistical measures subject to other parameters. Defaults to NULL.

additional_queries

Any other additional queries to pass to the API. See https://www.nomisweb.co.uk/api/v01/help for instructions on query structure. Defaults to NULL. Deprecated in package versions greater than 0.2.0 and will eventually be removed in a future version.

exclude_missing

If TRUE, excludes all missing values. Defaults to FALSE.

select

A character vector of one or more variables to select, excluding all others. select is not case sensitive.

tidy

Logical parameter. If TRUE, converts variable names to snake_case, or another style as specified by the tidy_style parameter. Defaults to FALSE.

tidy_style

The style to convert variable names to, if tidy = TRUE. Accepts one of "snake_case", "camelCase" and "period.case". Defaults to "snake_case".

...

Use to pass any other parameters to the API. Useful for passing concepts that are not available through the default parameters. Only accepts concepts identified in nomis_get_metadata and concept values identified in nomis_codelist. Parameters can be quoted or unquoted. Each parameter should have a name and a value. For example, CAUSE_OF_DEATH = 10300 when querying dataset "NM_161_1". Parameters are not case sensitive. Note that R using partial matching for function variables, and so passing a parameter with the same opening characters as one of the above-named parameters can cause an error unless the value of the named parameter is specified. See example below:

Value

A tibble containing the selected dataset. By default, all tibble columns are parsed as characters.

See also

Examples

# Return data for each country jobseekers_country <- nomis_get_data(id="NM_1_1", time="latest", geography = "TYPE499", measures=c(20100, 20201), sex=5) tibble::glimpse(jobseekers_country)
#> Observations: 70 #> Variables: 34 #> $ DATE <chr> "2018-09", "2018-09", "2018-09", "2018-09", "20... #> $ DATE_NAME <chr> "September 2018", "September 2018", "September ... #> $ DATE_CODE <chr> "2018-09", "2018-09", "2018-09", "2018-09", "20... #> $ DATE_TYPE <chr> "date", "date", "date", "date", "date", "date",... #> $ DATE_TYPECODE <chr> "0", "0", "0", "0", "0", "0", "0", "0", "0", "0... #> $ DATE_SORTORDER <chr> "0", "0", "0", "0", "0", "0", "0", "0", "0", "0... #> $ GEOGRAPHY <chr> "2092957697", "2092957697", "2092957697", "2092... #> $ GEOGRAPHY_NAME <chr> "United Kingdom", "United Kingdom", "United Kin... #> $ GEOGRAPHY_CODE <chr> "K02000001", "K02000001", "K02000001", "K020000... #> $ GEOGRAPHY_TYPE <chr> "countries", "countries", "countries", "countri... #> $ GEOGRAPHY_TYPECODE <chr> "499", "499", "499", "499", "499", "499", "499"... #> $ GEOGRAPHY_SORTORDER <chr> "0", "0", "0", "0", "0", "0", "0", "0", "0", "0... #> $ SEX <chr> "5", "5", "5", "5", "5", "5", "5", "5", "5", "5... #> $ SEX_NAME <chr> "Male", "Male", "Male", "Male", "Male", "Male",... #> $ SEX_CODE <chr> "5", "5", "5", "5", "5", "5", "5", "5", "5", "5... #> $ SEX_TYPE <chr> "sex", "sex", "sex", "sex", "sex", "sex", "sex"... #> $ SEX_TYPECODE <chr> "0", "0", "0", "0", "0", "0", "0", "0", "0", "0... #> $ SEX_SORTORDER <chr> "0", "0", "0", "0", "0", "0", "0", "0", "0", "0... #> $ ITEM <chr> "1", "1", "2", "2", "3", "3", "4", "4", "9", "9... #> $ ITEM_NAME <chr> "Total claimants", "Total claimants", "Students... #> $ ITEM_CODE <chr> "1", "1", "2", "2", "3", "3", "4", "4", "9", "9... #> $ ITEM_TYPE <chr> "item", "item", "item", "item", "item", "item",... #> $ ITEM_TYPECODE <chr> "0", "0", "0", "0", "0", "0", "0", "0", "0", "0... #> $ ITEM_SORTORDER <chr> "0", "0", "1", "1", "2", "2", "3", "3", "4", "4... #> $ MEASURES <chr> "20100", "20201", "20100", "20201", "20100", "2... #> $ MEASURES_NAME <chr> "Persons claiming JSA", "Workplace-based estima... #> $ OBS_VALUE <dbl> 227468.0, 1.2, NA, NA, NA, NA, NA, NA, NA, NA, ... #> $ OBS_STATUS <chr> "A", "A", "Q", "Q", "Q", "Q", "Q", "Q", "Q", "Q... #> $ OBS_STATUS_NAME <chr> "Normal Value", "Normal Value", "These figures ... #> $ OBS_CONF <chr> "F", "F", "F", "F", "F", "F", "F", "F", "F", "F... #> $ OBS_CONF_NAME <chr> "Free (free for publication)", "Free (free for ... #> $ URN <chr> "Nm-1d1d32297e0d2092957697d5d1d20100", "Nm-1d1d... #> $ RECORD_OFFSET <chr> "0", "1", "2", "3", "4", "5", "6", "7", "8", "9... #> $ RECORD_COUNT <chr> "70", "70", "70", "70", "70", "70", "70", "70",...
# Return data for Wigan jobseekers_wigan <- nomis_get_data(id="NM_1_1", time="latest", geography = "1879048226", measures=c(20100, 20201), sex="5") tibble::glimpse(jobseekers_wigan)
#> Observations: 10 #> Variables: 34 #> $ DATE <chr> "2018-09", "2018-09", "2018-09", "2018-09", "20... #> $ DATE_NAME <chr> "September 2018", "September 2018", "September ... #> $ DATE_CODE <chr> "2018-09", "2018-09", "2018-09", "2018-09", "20... #> $ DATE_TYPE <chr> "date", "date", "date", "date", "date", "date",... #> $ DATE_TYPECODE <chr> "0", "0", "0", "0", "0", "0", "0", "0", "0", "0" #> $ DATE_SORTORDER <chr> "0", "0", "0", "0", "0", "0", "0", "0", "0", "0" #> $ GEOGRAPHY <chr> "1879048226", "1879048226", "1879048226", "1879... #> $ GEOGRAPHY_NAME <chr> "Wigan", "Wigan", "Wigan", "Wigan", "Wigan", "W... #> $ GEOGRAPHY_CODE <chr> "E08000010", "E08000010", "E08000010", "E080000... #> $ GEOGRAPHY_TYPE <chr> "local authorities: district / unitary (as of A... #> $ GEOGRAPHY_TYPECODE <chr> "448", "448", "448", "448", "448", "448", "448"... #> $ GEOGRAPHY_SORTORDER <chr> "0", "0", "0", "0", "0", "0", "0", "0", "0", "0" #> $ SEX <chr> "5", "5", "5", "5", "5", "5", "5", "5", "5", "5" #> $ SEX_NAME <chr> "Male", "Male", "Male", "Male", "Male", "Male",... #> $ SEX_CODE <chr> "5", "5", "5", "5", "5", "5", "5", "5", "5", "5" #> $ SEX_TYPE <chr> "sex", "sex", "sex", "sex", "sex", "sex", "sex"... #> $ SEX_TYPECODE <chr> "0", "0", "0", "0", "0", "0", "0", "0", "0", "0" #> $ SEX_SORTORDER <chr> "0", "0", "0", "0", "0", "0", "0", "0", "0", "0" #> $ ITEM <chr> "1", "1", "2", "2", "3", "3", "4", "4", "9", "9" #> $ ITEM_NAME <chr> "Total claimants", "Total claimants", "Students... #> $ ITEM_CODE <chr> "1", "1", "2", "2", "3", "3", "4", "4", "9", "9" #> $ ITEM_TYPE <chr> "item", "item", "item", "item", "item", "item",... #> $ ITEM_TYPECODE <chr> "0", "0", "0", "0", "0", "0", "0", "0", "0", "0" #> $ ITEM_SORTORDER <chr> "0", "0", "1", "1", "2", "2", "3", "3", "4", "4" #> $ MEASURES <chr> "20100", "20201", "20100", "20201", "20100", "2... #> $ MEASURES_NAME <chr> "Persons claiming JSA", "Workplace-based estima... #> $ OBS_VALUE <dbl> 1186, NA, NA, NA, NA, NA, NA, NA, NA, NA #> $ OBS_STATUS <chr> "A", "Q", "Q", "Q", "Q", "Q", "Q", "Q", "Q", "Q" #> $ OBS_STATUS_NAME <chr> "Normal Value", "These figures are missing.", "... #> $ OBS_CONF <chr> "F", "F", "F", "F", "F", "F", "F", "F", "F", "F" #> $ OBS_CONF_NAME <chr> "Free (free for publication)", "Free (free for ... #> $ URN <chr> "Nm-1d1d32297e0d1879048226d5d1d20100", "Nm-1d1d... #> $ RECORD_OFFSET <chr> "0", "1", "2", "3", "4", "5", "6", "7", "8", "9" #> $ RECORD_COUNT <chr> "10", "10", "10", "10", "10", "10", "10", "10",...
# annual population survey - regional - employment by occupation emp_by_occupation <- nomis_get_data(id="NM_168_1", time="latest", geography = "2013265925", sex="0", select = c("geography_code", "C_OCCPUK11H_0_NAME", "obs_vAlUE")) tibble::glimpse(emp_by_occupation)
#> Observations: 1,976 #> Variables: 3 #> $ GEOGRAPHY_CODE <chr> "E12000005", "E12000005", "E12000005", "E1200000... #> $ C_OCCPUK11H_0_NAME <chr> "Total", "Total", "Total", "Total", "1 Managers,... #> $ OBS_VALUE <dbl> 2705400.0, 52400.0, 100.0, NA, 286900.0, 17100.0...
# Deaths in 2016 and 2015 by three specified causes, g death <- nomis_get_data("NM_161_1", date = c("2016","2015"), geography = "TYPE480", cause_of_death=c(10300, 102088, 270)) tibble::glimpse(death)
#> Observations: 22,680 #> Variables: 46 #> $ DATE <chr> "2016", "2016", "2016", "2016", "2016", "2... #> $ DATE_NAME <chr> "2016", "2016", "2016", "2016", "2016", "2... #> $ DATE_CODE <chr> "2016", "2016", "2016", "2016", "2016", "2... #> $ DATE_TYPE <chr> "date", "date", "date", "date", "date", "d... #> $ DATE_TYPECODE <chr> "0", "0", "0", "0", "0", "0", "0", "0", "0... #> $ DATE_SORTORDER <chr> "0", "0", "0", "0", "0", "0", "0", "0", "0... #> $ GEOGRAPHY <chr> "2013265921", "2013265921", "2013265921", ... #> $ GEOGRAPHY_NAME <chr> "North East", "North East", "North East", ... #> $ GEOGRAPHY_CODE <chr> "E12000001", "E12000001", "E12000001", "E1... #> $ GEOGRAPHY_TYPE <chr> "regions", "regions", "regions", "regions"... #> $ GEOGRAPHY_TYPECODE <chr> "480", "480", "480", "480", "480", "480", ... #> $ GEOGRAPHY_SORTORDER <chr> "0", "0", "0", "0", "0", "0", "0", "0", "0... #> $ CAUSE_OF_DEATH <chr> "10300", "10300", "10300", "10300", "10300... #> $ CAUSE_OF_DEATH_NAME <chr> "C00 Malignant neoplasm of lip", "C00 Mali... #> $ CAUSE_OF_DEATH_CODE <chr> "C00", "C00", "C00", "C00", "C00", "C00", ... #> $ CAUSE_OF_DEATH_TYPE <chr> "ICD-10 three digit", "ICD-10 three digit"... #> $ CAUSE_OF_DEATH_TYPECODE <chr> "1005", "1005", "1005", "1005", "1005", "1... #> $ CAUSE_OF_DEATH_SORTORDER <chr> "0", "0", "0", "0", "0", "0", "0", "0", "0... #> $ GENDER <chr> "0", "0", "0", "0", "0", "0", "0", "0", "0... #> $ GENDER_NAME <chr> "Total", "Total", "Total", "Total", "Total... #> $ GENDER_CODE <chr> "0", "0", "0", "0", "0", "0", "0", "0", "0... #> $ GENDER_TYPE <chr> "Sex", "Sex", "Sex", "Sex", "Sex", "Sex", ... #> $ GENDER_TYPECODE <chr> "1000", "1000", "1000", "1000", "1000", "1... #> $ GENDER_SORTORDER <chr> "0", "0", "0", "0", "0", "0", "0", "0", "0... #> $ AGE <chr> "0", "0", "0", "0", "0", "0", "1", "1", "1... #> $ AGE_NAME <chr> "total (all ages)", "total (all ages)", "t... #> $ AGE_CODE <chr> "0", "0", "0", "0", "0", "0", "1", "1", "1... #> $ AGE_TYPE <chr> "ageband", "ageband", "ageband", "ageband"... #> $ AGE_TYPECODE <chr> "1000", "1000", "1000", "1000", "1000", "1... #> $ AGE_SORTORDER <chr> "0", "0", "0", "0", "0", "0", "1", "1", "1... #> $ MEASURE <chr> "1", "2", "5", "6", "7", "8", "1", "2", "5... #> $ MEASURE_NAME <chr> "Deaths", "Age-standardised mortality rate... #> $ MEASURE_CODE <chr> "1", "2", "5", "6", "7", "8", "1", "2", "5... #> $ MEASURE_TYPE <chr> "measures", "measures", "measures", "measu... #> $ MEASURE_TYPECODE <chr> "1000", "1000", "1000", "1000", "1000", "1... #> $ MEASURE_SORTORDER <chr> "0", "1", "2", "3", "4", "5", "0", "1", "2... #> $ MEASURES <chr> "20100", "20100", "20100", "20100", "20100... #> $ MEASURES_NAME <chr> "Value", "Value", "Value", "Value", "Value... #> $ OBS_VALUE <dbl> 0, NA, NA, NA, NA, NA, 0, NA, NA, NA, NA, ... #> $ OBS_STATUS <chr> "A", "Q", "Q", "Q", "Q", "Q", "A", "Q", "Q... #> $ OBS_STATUS_NAME <chr> "Normal Value", "These figures are missing... #> $ OBS_CONF <chr> "F", "F", "F", "F", "F", "F", "F", "F", "F... #> $ OBS_CONF_NAME <chr> "Free (free for publication)", "Free (free... #> $ URN <chr> "Nm-161d1d32256e0d2013265921d10300d0d0d1d2... #> $ RECORD_OFFSET <chr> "0", "1", "2", "3", "4", "5", "6", "7", "8... #> $ RECORD_COUNT <chr> "22680", "22680", "22680", "22680", "22680...
# All causes of death in London in 2016 london_death <- nomis_get_data("NM_1_1", date = c("2016"), geography = "2013265927", sex = 1, age = 0)
#> Error: The API request did not return any results. #> Please check your parameters.
tibble::glimpse(london_death)
#> Error in tibble::glimpse(london_death): object 'london_death' not found
# NOT RUN { ## Results in an error because `measure` is mistaken for `measures` mort_data1 <- nomis_get_data(id = "NM_161_1", date = "2016", geography = "TYPE464", sex = 0, cause_of_death = "10381", age = 0, measure = 6) ## Does not error because `measures` is specified mort_data2 <- nomis_get_data(id = "NM_161_1", date = "2016", geography = "TYPE464", sex = 0, measures = NULL, cause_of_death = "10381", age = 0, measure = 6) # }