PostcodesioR is an API wrapper for postcodes.io. It allows acquiring geographic information about the UK postcodes and geographic coordinates.
if (!require("devtools")) install.packages("devtools") devtools::install_github("ropensci/PostcodesioR")
Provide a postcode to obtain all available information
library(PostcodesioR) lookup_result <- postcode_lookup("EC1Y8LX") #overview str(lookup_result)
There is another function that returns the same data points but returns a list and allows optional parameters
query_result <- postcode_query("EC1Y8LX") #overview str(query_result)
This function creates a nested list with the codes for administrative district, county, ward, parish, parliamentary constituency, CCG, and NUTS.
To query two or more postcodes, use bulk_
functions.
pc_list <- list(postcodes = c("PR3 0SG", "M45 6GN", "EX165BL")) bulk_lookup_result <- bulk_postcode_lookup(pc_list) #overview str(bulk_lookup_result[1])
If you want to work with data frame then the nested list created above can be turned into a data frame
library(purrr) bulk_list <- lapply(bulk_lookup_result, "[[", 2) bulk_df <- map_dfr(bulk_list, `[`, c("postcode", "longitude", "latitude"))
Querying Scottish postcodes requires a separate function:
scottish_lookup <- scottish_postcode_lookup("EH12NG") str(scottish_lookup)
Provide an outcode to obtain geolocation data for the centroid of the specified outcode:
ocl <- outward_code_lookup("E1") #overview str(ocl)
Provide latitude and longitude to obtain geographic information. Different levels of aggregation are available, i.e. postcode or outcode.
rev_geo <- reverse_geocoding(0.127, 51.507) # overview str(rev_geo[1])
To reverse geocode multiple values use the function underneath. The result is a nested list, which might be a bit intimidating, but it allows storing unequal number of elements.
# create a list with the coordinates geolocations_list <- structure( list( geolocations = structure( list( longitude = c(-3.15807731271522, -1.12935802905177), latitude = c(51.4799900627036, 50.7186356978817), limit = c(NA, 100L), radius = c(NA, 500L)), .Names = c("longitude", "latitude", "limit", "radius"), class = "data.frame", row.names = 1:2)), .Names = "geolocations") bulk_rev_geo <- bulk_reverse_geocoding(geolocations_list) bulk_rev_geo[[1]]$result[[1]]
The list above is not the most common way of storing files. It's more likely that a data frame will be used to store the geodata. In that case, it has to be turned into a list of a specific format required by the API:
geolocations_df <- structure( list( longitude = c(-3.15807731271522, -1.12935802905177), latitude = c(51.4799900627036, 50.7186356978817), limit = c(NA, 100L), radius = c(NA, 500L)), .Names = c("longitude", "latitude", "limit", "radius"), row.names = 1:2, class = "data.frame") geolocations_df # turn a data frame into a list geolocations_df2list <- list(geolocations_df) # add a list name names(geolocations_df2list) <- "geolocations" # display correct input for the function geolocations_df2list
Common usage of this function might be extracting particular variables. You can extract one variable like this:
# extract one postcode bulk_rev_geo[[1]]$result[[8]]$postcode
But more likely you will want more than one result. After all, that's the point of using a bulk function:
# function to extract variables of interest extract_bulk_geo_variable <- function(x) { bulk_results <- lapply(bulk_rev_geo, `[[`, "result") sapply(unlist(bulk_results, recursive = FALSE), `[[`, x) } # define the variables you need variables_of_interest <- c("postcode", "latitude", "longitude") # return a data frame with the variables data.frame( sapply(variables_of_interest, extract_bulk_geo_variable))
out_rev_geocode <- outcode_reverse_geocoding("-3.15", "51.47") # overview str(out_rev_geocode[1])
Generates a list with a random UK postcode and corresponding geographic information:
# without restrictions random_postcode()
A randomly generated postcode can also belong to a particular outcode:
# restrict to an outcode random_postcode("N1")
You can also generate a random place, specified by an OSGB code, with corresponding geographic information:
random_place()
This function can validate a UK postcode:
postcode_validation("EC1Y8LX") # actual UK postcode
postcode_validation("XYZ") # incorrect UK postcode
Find the potential candidates for a postcode if you only know the beginning characters
postcode_autocomplete("EC1")
It defaults to 10 candidates, but can be changed by specifying the limit
argument.
Provide a postcode to get a list of the nearest postcodes:
near_pc <- nearest_postcode("EC1Y8LX") #overview str(near_pc[1])
You can also use outcodes:
near_outcode <- nearest_outcode("EC1Y") # overview str(near_outcode[2])
Or longitude and latitude
near_ll <- nearest_outcode_lonlat(0.127, 51.507) #overview str(near_ll[1])
Provide a name of a place of interest. You can specify the number of results (default is 10):
place_query_result <- place_query("Hills", limit = 11) # overview str(place_query_result[1])
You can also find a place using an OSGB code:
place_lookup_result <- place_lookup("osgb4000000074544700") # overview str(place_lookup_result)
You might end up having terminated postcodes in your data set. These are postcodes that are no longer active. UK postcodes can change so it's worth checking whether used postcodes are still active. If you need more information about when a particular postcode was terminated use:
terminated_postcode("E1W 1UU")
Any scripts or data that you put into this service are public.
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.