Title: | Access 'Nomis' UK Labour Market Data |
---|---|
Description: | Access UK official statistics from the 'Nomis' database. 'Nomis' includes data from the Census, the Labour Force Survey, DWP benefit statistics and other economic and demographic data from the Office for National Statistics, based around statistical geographies. See <https://www.nomisweb.co.uk/api/v01/help> for full API documentation. |
Authors: | Evan Odell [aut, cre] |
Maintainer: | Evan Odell <[email protected]> |
License: | MIT + file LICENSE |
Version: | 0.4.7 |
Built: | 2024-09-02 10:17:03 UTC |
Source: | https://github.com/ropensci/nomisr |
Assign or reassign API key for Nomis.
nomis_api_key(check_env = FALSE)
nomis_api_key(check_env = FALSE)
check_env |
If TRUE, will check the environment variable
|
The Nomis API has an optional key. Using the key means that 100,000 rows can be returned per call, which can speed up larger data requests and reduce the chances of being rate limited or having requests timing out.
By default, nomisr
will look for the environment variable
NOMIS_API_KEY
when the package is loaded. If found, the API key will
be stored in the session option nomisr.API.key
. If you would like to
reload the API key or would like to manually enter one in, this function
may be used.
You can sign up for an API key here.
Nomis uses its own internal coding for query concepts. nomis_codelist
returns the codes for a given concept in a tibble
, given a dataset
ID and a concept name.
Note that some codelists, particularly geography, can be very large.
nomis_codelist(id, concept, search = NULL)
nomis_codelist(id, concept, search = NULL)
id |
A string with the ID of the particular dataset. Must be specified. |
concept |
A string with the variable concept to return options for. If
left empty, returns all the variables for the dataset specified by |
search |
Search for codes that contain a given string. The wildcard
character |
A tibble with the codes used to query specific concepts.
x <- nomis_codelist("NM_1_1", "item") # Searching for codes ending with "london" y <- nomis_codelist("NM_1_1", "geography", search = "*london") z <- nomis_codelist("NM_161_1", "cause_of_death")
x <- nomis_codelist("NM_1_1", "item") # Searching for codes ending with "london" y <- nomis_codelist("NM_1_1", "geography", search = "*london") z <- nomis_codelist("NM_161_1", "cause_of_death")
Nomis content type metadata is included in annotation tags, in the form of
contenttype/<contenttype>
in the annotationtitle
column in
the annotations.annotation
list-column returned from
nomis_data_info()
. For example, the content types returned from
dataset "NM_1658_1", using nomis_data_info("NM_1658_1")
, are
"geoglevel", "2001census" and "sources".
nomis_content_type(content_type, id = NULL)
nomis_content_type(content_type, id = NULL)
content_type |
A string with the content type to return metadata on. |
id |
A string with an optional |
A tibble with metadata on a given content type.
a <- nomis_content_type("sources") tibble::glimpse(a) b <- nomis_content_type("sources", id = "census") tibble::glimpse(b)
a <- nomis_content_type("sources") tibble::glimpse(a) b <- nomis_content_type("sources", id = "census") tibble::glimpse(b)
Retrieve metadata on the structure and available variables for all available data sets or the information available in a specific dataset based on its ID.
nomis_data_info(id, tidy = FALSE)
nomis_data_info(id, tidy = FALSE)
id |
Dataset ID. If empty, returns data on all available datasets. If the ID of a dataset, returns metadata for that particular dataset. |
tidy |
If |
A tibble with all available datasets and their metadata.
# Get info on all datasets x <- nomis_data_info() tibble::glimpse(x) # Get info on a particular dataset y <- nomis_data_info("NM_1658_1") tibble::glimpse(y)
# Get info on all datasets x <- nomis_data_info() tibble::glimpse(x) # Get info on a particular dataset y <- nomis_data_info("NM_1658_1") tibble::glimpse(y)
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 earliest 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", query_id = NULL, ... )
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", query_id = NULL, ... )
id |
A string containing the ID of the dataset to retrieve,
in |
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 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
Values for the Defaults to |
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,
The first is one or more of 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
Values for the Defaults to |
geography |
The code of the geographic area to return data for. If
|
sex |
The code for sexes/genders to include in the dataset.
Accepts a string or number, or a vector of strings or numbers.
There are two different codings used for sex, depending on the dataset. For
datasets using |
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 |
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 |
exclude_missing |
If |
select |
A character vector of one or more variables to include in
the returned data, excluding all others. |
tidy |
Logical parameter. If |
tidy_style |
The style to convert variable names to, if
|
query_id |
Results can be labelled as belonging to a certain query
made to the API. |
... |
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 |
A tibble containing the selected dataset. By default, all tibble
columns except for the "OBS_VALUE"
column are parsed as characters.
# Return data on Jobseekers Allowance for each country in the UK jobseekers_country <- nomis_get_data( id = "NM_1_1", time = "latest", geography = "TYPE499", measures = c(20100, 20201), sex = 5 ) # Return data on Jobseekers Allowance for Wigan jobseekers_wigan <- nomis_get_data( id = "NM_1_1", time = "latest", geography = "1879048226", measures = c(20100, 20201), sex = "5" ) # 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" ) ) # Deaths in 2016 and 2015 by three specified causes, # identified with nomis_get_metadata() death <- nomis_get_data("NM_161_1", date = c("2016", "2015"), geography = "TYPE480", cause_of_death = c(10300, 102088, 270) ) # All causes of death in London in 2016 london_death <- nomis_get_data("NM_161_1", date = c("2016"), geography = "2013265927", sex = 1, age = 0 ) ## 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 ) ## End(Not run)
# Return data on Jobseekers Allowance for each country in the UK jobseekers_country <- nomis_get_data( id = "NM_1_1", time = "latest", geography = "TYPE499", measures = c(20100, 20201), sex = 5 ) # Return data on Jobseekers Allowance for Wigan jobseekers_wigan <- nomis_get_data( id = "NM_1_1", time = "latest", geography = "1879048226", measures = c(20100, 20201), sex = "5" ) # 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" ) ) # Deaths in 2016 and 2015 by three specified causes, # identified with nomis_get_metadata() death <- nomis_get_data("NM_161_1", date = c("2016", "2015"), geography = "TYPE480", cause_of_death = c(10300, 102088, 270) ) # All causes of death in London in 2016 london_death <- nomis_get_data("NM_161_1", date = c("2016"), geography = "2013265927", sex = 1, age = 0 ) ## 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 ) ## End(Not run)
Retrieve all concept code options of all Nomis datasets,
concept code options for a given dataset, or the all the options for a given
concept variable from a particular dataset. Specifying concept
will
return all the options for a given variable in a particular dataset.
If looking for a more detailed overview of all available
metadata for a given dataset, see nomis_overview()
.
nomis_get_metadata( id, concept = NULL, type = NULL, search = NULL, additional_queries = NULL, ..., tidy = FALSE )
nomis_get_metadata( id, concept = NULL, type = NULL, search = NULL, additional_queries = NULL, ..., tidy = FALSE )
id |
The ID of the particular dataset. Returns no data if not specified. |
concept |
A string with the variable concept to return options for. If
left empty, returns all the variables for the dataset specified by |
type |
A string with options for a particular code value, to return
types of variables available for a given code. Defaults to |
search |
A string or character vector of strings to search for in the
metadata. Defaults to |
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 |
... |
Use to pass any other parameters to the API. |
tidy |
If |
A tibble with metadata options for queries using nomis_get_data()
.
a <- nomis_get_metadata("NM_1_1") print(a) b <- nomis_get_metadata("NM_1_1", "geography") tibble::glimpse(b) # returns all types of geography c <- nomis_get_metadata("NM_1_1", "geography", "TYPE") tibble::glimpse(c) # returns geography types available within Wigan d <- nomis_get_metadata("NM_1_1", "geography", "1879048226") tibble::glimpse(d) e <- nomis_get_metadata("NM_1_1", "item", geography = 1879048226, sex = 5) print(e) f <- nomis_get_metadata("NM_1_1", "item", search = "*married*") tibble::glimpse(f)
a <- nomis_get_metadata("NM_1_1") print(a) b <- nomis_get_metadata("NM_1_1", "geography") tibble::glimpse(b) # returns all types of geography c <- nomis_get_metadata("NM_1_1", "geography", "TYPE") tibble::glimpse(c) # returns geography types available within Wigan d <- nomis_get_metadata("NM_1_1", "geography", "1879048226") tibble::glimpse(d) e <- nomis_get_metadata("NM_1_1", "item", geography = 1879048226, sex = 5) print(e) f <- nomis_get_metadata("NM_1_1", "item", search = "*married*") tibble::glimpse(f)
Returns an overview of available metadata for a given dataset.
nomis_overview(id, select = NULL)
nomis_overview(id, select = NULL)
id |
The ID of the particular dataset. Returns no data if not specified. |
select |
A string or character vector of one or more overview parts to
select, excluding all others. |
A tibble with two columns, one a character vector with the name of the metadata category, and the other a list column of values for each category.
General dataset information such as name, description, sub-description, mnemonic, restricted access and status
Shows the geographic coverage of the main geography dimension in this dataset (e.g. United Kingdom, England and Wales etc.)
The keywords allocated to the dataset
The units of measure supported by the dataset
The classifications allocated to this dataset
Information about the first release, last update and next update
Details for the point of contact for this dataset
Show the available analysis breakdowns of this dataset
Individual dimension information (e.g. sex, geography, date, etc.)
Allows a specific dimension to be selected (e.g. dimension-geography would allow information about geography dimension). This is not used if "Dimensions" is specified too.
Full list of selectable codes, excluding Geography, which as a list of Types instead. (Requires "Dimensions" to be selected too)
Full list of selectable codes for a specific dimension, excluding Geography, which as a list of Types instead. This is not used if "Codes" is specified too (Requires "Dimensions" or equivalent to be selected too)
Any available metadata attached at the dimensional level (Requires "Dimensions" or equivalent to be selected too)
Information about whether user defined codes can be created with the MAKE parameter when querying data (Requires "Dimensions" or equivalent to be selected too)
Metadata attached at the dataset level
library(dplyr) q <- nomis_overview("NM_1650_1") q %>% tidyr::unnest(name) %>% glimpse() s <- nomis_overview("NM_1650_1", select = c("Units", "Keywords")) s %>% tidyr::unnest(name) %>% glimpse()
library(dplyr) q <- nomis_overview("NM_1650_1") q %>% tidyr::unnest(name) %>% glimpse() s <- nomis_overview("NM_1650_1", select = c("Units", "Keywords")) s %>% tidyr::unnest(name) %>% glimpse()
A function to search for datasets on given topics. In the case of multiple
search parameters, returns metadata on all datasets matching one or more
of the parameters. The wildcard character *
can be added to the
beginning and/or end of each search string.
nomis_search( name = NULL, description = NULL, keywords = NULL, content_type = NULL, units = NULL, tidy = FALSE )
nomis_search( name = NULL, description = NULL, keywords = NULL, content_type = NULL, units = NULL, tidy = FALSE )
name |
A string or character vector of strings to search for in
available dataset names. Defaults to |
description |
A string or character vector of strings to search for in
available dataset descriptions. Note that |
keywords |
A string or character vector of strings to search for in
available dataset keywords. Defaults to |
content_type |
A string or character vector of strings to search for
in available dataset content types. |
units |
A string or character vector of strings to search for in
available dataset units. Defaults to |
tidy |
If |
A tibble with details on all datasets matching the search query.
x <- nomis_search(name = "*seekers*") y <- nomis_search(keywords = "Claimants") # Return metadata of all datasets with content_type "sources". a <- nomis_search(content_type = "sources") # Return metadata of all datasets with content_type "sources" and # source ID "acses" b <- nomis_search(content_type = "sources-acses")
x <- nomis_search(name = "*seekers*") y <- nomis_search(keywords = "Claimants") # Return metadata of all datasets with content_type "sources". a <- nomis_search(content_type = "sources") # Return metadata of all datasets with content_type "sources" and # source ID "acses" b <- nomis_search(content_type = "sources-acses")
Access UK official statistics from the Nomis database. Nomis includes data from the Census, the Labour Force Survey, DWP benefit statistics and other economic and demographic data from the Office for National Statistics.
The package provides functions to find what data is available, metadata, including the variables and query options for different datasets and a function for downloading data.
The full API documentation and optional registration for an API key is available at https://www.nomisweb.co.uk/api/v01/help.