The package helps you send a collection of UK postcodes to the postcodes.io API, and handles the data returned by the API.

This gives you easy access to the coordinates of the centroids of the postcode areas, and other information such as the statistical, administrative and health geographies the postcodes sit within. For example: its LSOA (or equivalent), local authority, and parliamentary constituency.

The package also helps you check a list of postcodes for currency/validity, and suggests replacement current postcodes for terminated (out of date) codes.

You can install the development version of {NHSRpostcodetools} from GitHub with:

# install.packages("pak") # run this if you don't yet have {pak} installed
pak::pak("nhs-r-community/NHSRpostcodetools")

# then load the package with `library()`
library(NHSRpostcodetools)

You can get postcode data by submitting a vector of postcodes:

get_postcode_data(c("NP22 3PS", "NP22 4PS", "NP22 5PS"))

or if you have a data frame with a column of postcodes, you might do:

postcode_data_join(my_data, .col = "postcodes")

setting the .col argument to the name of the column containing the codes (this is "postcode" by default, so in that case you don't need to supply .col)

If you have a list of postcodes that may contain errors or out of date codes, you can check them with suggest_fixes():

suggest_fixes(c("NP22 3PQ", "NP22 3PR", "NP22 3MN"))

This will return a summary data frame for any codes that are not found to be current and valid, and will suggest nearby replacement postcodes where possible. This allows you to fix invalid postcodes in your data before running get_postcode_data().

NB suggest_fixes() isn't magic! It can try to deal with terminated (out of date) postcodes and postcodes with an incorrect or missing final letter, but it can't help with incorrect outcodes (the first half of the postcode).

So if your postcode data has "NR22 3PS" when it should have "NP22 3PS", you are on your own 😜! Please sense-check your data before using suggest_fixes(), and use care when implementing its suggestions.

The package website contains more guidance on how to use the functions in this package, and what to expect.

If you experience any problems using this package, find a bug, or have ideas for how to improve it, you are welcome to create a GitHub issue, or you may prefer to start a thread in the [Discussions][discussions] area.

Before submitting your issue, please read the NHS-R Community's guidance on how to contribute to packages.

This project is released with a Contributor Code of Conduct. By contributing to this project, you agree to abide by its terms.