,
Claudia Vitolo [rev] ,
Robin Lovelace [rev] | Title: | API Wrapper Around 'Postcodes.io' |
|---|---|
| Description: | Free UK geocoding using data from Office for National Statistics. It is using several functions to get information about post codes, outward codes, reverse geocoding, nearest post codes/outward codes, validation, or randomly generate a post code. API wrapper around <https://postcodes.io>. |
| Authors: | Eryk Walczak [aut, cre] ,
Claudia Vitolo [rev] ,
Robin Lovelace [rev] |
| Maintainer: | Eryk Walczak <[email protected]> |
| License: | GPL-3 |
| Version: | 0.3.1 |
| Built: | 2024-11-27 03:39:21 UTC |
| Source: | https://github.com/ropensci/PostcodesioR |
Returns a list of matching postcodes and respective available data.
bulk_postcode_lookup(postcodes)bulk_postcode_lookup(postcodes)
postcodes |
Accepts a list of postcodes. Accepts up to 100 postcodes.
For only one postcode use |
A list of length one.
postcode_lookup for documentation.
pc_list <- list( postcodes = c("PR3 0SG", "M45 6GN", "EX165BL")) # spaces are ignored bulk_postcode_lookup(pc_list) # The function needs a list of length one. This won't work: bulk_postcode_lookup(list("PR3 0SG", "M45 6GN", "EX165BL"))pc_list <- list( postcodes = c("PR3 0SG", "M45 6GN", "EX165BL")) # spaces are ignored bulk_postcode_lookup(pc_list) # The function needs a list of length one. This won't work: bulk_postcode_lookup(list("PR3 0SG", "M45 6GN", "EX165BL"))
Returns nearest postcodes for a given longitude and latitude. Accepts up to 100 geolocations.
bulk_reverse_geocoding(geolocations)bulk_reverse_geocoding(geolocations)
geolocations |
A list containing an array of objects to geolocate. At least two elements needed. |
This method requires a JSON object containing an array of geolocation objects to be POSTed. Each geolocation object accepts an optional radius (meters) and limit argument. Both default to 100m and 10 respectively. It also accepts a wideSearch argument.
A list with the geocoded data.
postcode_lookup for documentation.
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_reverse_geocoding(geolocations_list)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_reverse_geocoding(geolocations_list)
Returns nearest outcodes for a given outcode. The search is based on the relative distance of the outcode centroid.
nearest_outcode(outcode, limit = 10, radius = 5000)nearest_outcode(outcode, limit = 10, radius = 5000)
outcode |
A string with a UK postcode. |
limit |
An integer. Optional parameter. Limits number of postcodes matches to return. Defaults to 10. Needs to be less than 100. |
radius |
An integer. Optional parameter. Limits number of postcodes matches to return. Defaults to 5,000m. Needs to be less than 25,000m. |
A list of geographical properties.
postcode_lookup for documentation.
nearest_outcode("EC1Y") nearest_outcode("EC1Y", limit = 11) nearest_outcode("EC1Y", limit = 11, radius = 6000)nearest_outcode("EC1Y") nearest_outcode("EC1Y", limit = 11) nearest_outcode("EC1Y", limit = 11, radius = 6000)
Returns nearest outward codes for a given longitude and latitude. The search is based on the relative distance of the outcode centroid.
nearest_outcode_lonlat(longitude, latitude)nearest_outcode_lonlat(longitude, latitude)
longitude |
A string or numeric. Needs to have at least three decimal points. |
latitude |
A string or numeric. Needs to have at least three decimal points. |
A list with available data.
postcode_lookup for documentation.
nearest_outcode_lonlat(0.127, 51.507)nearest_outcode_lonlat(0.127, 51.507)
Returns nearest postcodes for a given postcode. The search is based on the relative distance of the postcode centroid.
nearest_postcode(postcode, limit = 10, radius = 100)nearest_postcode(postcode, limit = 10, radius = 100)
postcode |
A string. Valid UK postcode. |
limit |
A string or integer. Limits number of postcodes matches to return. Defaults to 10. Needs to be lower than 100. |
radius |
Limits number of postcodes matches to return. Defaults to 100m. Needs to be less than 2,000m. |
A list of geographic properties of the nearest postcode.
nearest_postcode("EC1Y 8LX") nearest_postcode("EC1Y 8LX", limit = 11) nearest_postcode("EC1Y 8LX", limit = 12, radius = 200)nearest_postcode("EC1Y 8LX") nearest_postcode("EC1Y 8LX", limit = 11) nearest_postcode("EC1Y 8LX", limit = 12, radius = 200)
Returns nearest outcodes for a given longitude and latitude.
outcode_reverse_geocoding(longitude, latitude, limit = 10, radius = 5000)outcode_reverse_geocoding(longitude, latitude, limit = 10, radius = 5000)
longitude |
A string, integer or float. Needs to have at least two decimal points. |
latitude |
A string, integer or float. Needs to have at least two decimal points. |
limit |
A string, integer or float. Limits number of postcodes matches to return. Defaults to 10. Needs to be less than 100. |
radius |
A string, integer or float. Limits number of postcodes matches to return. Defaults to 5,000m. Needs to be less than 25,000m. |
A list of geographical properties.
postcode_lookup for documentation.
outcode_reverse_geocoding("-3.15", "51.47") outcode_reverse_geocoding(-3.15, 51.47) outcode_reverse_geocoding("-3.15807731271522", "51.4799900627036") outcode_reverse_geocoding(-3.15, 51.47, limit = 11, radius = 20000)outcode_reverse_geocoding("-3.15", "51.47") outcode_reverse_geocoding(-3.15, 51.47) outcode_reverse_geocoding("-3.15807731271522", "51.4799900627036") outcode_reverse_geocoding(-3.15, 51.47, limit = 11, radius = 20000)
Geolocation data for the centroid of the outward code specified.
outward_code_lookup(outcode)outward_code_lookup(outcode)
outcode |
A string. The outward code representing the first half of any postcode (separated by a space). |
The list of geographical properties.
postcode_lookup for documentation.
outward_code_lookup("E1")outward_code_lookup("E1")
Lookup a place by code. Returns all available data if found. Returns 404 if a place does not exist.
place_lookup(code)place_lookup(code)
code |
A string. The unique identifier for places - Ordnance Survey (OSGB) code. |
A list with available places.
code A unique identifier that enables records to be identified easily.
The identifier will be persistent for all LocalTypes
except Section of Named Road and Section of Numbered Road.
name_1 Name. The proper noun that applies to the real world entity.
Names that are prefixed by the definite article are not formatted
for alphabetical sorting, that is, 'The Pennines' not 'Pennines, The'.
name_1_lang Language of Name. The language type is only set
where more than one name exists
E.g. cym (Welsh), eng (English), gla (Scottish Gaelic).
name_2 Name (in case of multiple languages).
The proper noun that applies to the real world entity.
Names that are prefixed by the definite article are not formatted for
alphabetical sorting, that is, 'The Pennines' not 'Pennines, The'.
name_2_lang Language of Name. The language type is only set where more than one name exists
E.g. cym (Welsh), eng (English), gla (Scottish Gaelic).
local_type The Ordnance Survey classification for the named place being represented
by the specific feature. E.g. City, Town, Village, Hamlet, Other Settlement, Suburban Area
outcode The postcode district, for example, SO15.
county_unitary Administrative Area. The name of the County (non-metropolitan or Metropolitan),
Unitary Authority or Greater London Authority administrative area that the point geometry
for feature is within or nearest to.
county_unitary_type Administrative Area Type. Classifies the type of administrative unit.
district_borough District or Borough. The name of the District, Metropolitan District or
London Borough administrative unit that the point geometry for the feature is within.
district_borough_type Borough Type. Classifies the type of administrative unit.
region The name of the European Region (was Government O ice Region)
that the point geometry for the feature is within or nearest to.
country The country (i.e. one of the four constituent countries of the United Kingdom
or the Channel Islands or the Isle of Man) to which each place is assigned.
longitude The WGS84 longitude given the Place's national grid reference.
latitude The WGS84 latitude given the Place's national grid reference.
eastings The Ordnance Survey postcode grid reference Easting to 1 metre resolution;
blank for postcodes in the Channel Islands and the Isle of Man.
northings The Ordnance Survey postcode grid reference Northing to 1 metre resolution;
blank for postcodes in the Channel Islands and the Isle of Man.
min/max northings/eastings Minimum and Maximum, Northings and Eastings.
Bounding box or Minimum Bounding Rectangle (MBR) for roads and settlements.
For Settlements and Sections of Named and Numbered Roads,
the MBR gives a representation of the extent of these features and
is not snapped to the real world extent.
See https://postcodes.io/docs for more details.
place_lookup("osgb4000000074544700")place_lookup("osgb4000000074544700")
Submit a place query and receive a complete list of places matches and associated data.
This function is similar to place_lookup but it returns a list
and allows limiting the results.
place_query(place, limit = 10)place_query(place, limit = 10)
place |
A string. Name of a place to search for. |
limit |
An integer. Limits the number of matches to return. Defaults to 10. Needs to be less than 100. |
A list with available places.
place_lookup for documentation.
place_query("Hills") place_query("Hills", limit = 12)place_query("Hills") place_query("Hills", limit = 12)
Returns a data frame of matching postcodes.
postcode_autocomplete(postcode, limit = 10)postcode_autocomplete(postcode, limit = 10)
postcode |
A string. Valid UK postcode. |
limit |
An integer. Limits number of postcodes matches to return. Defaults to 10. Needs to be less than 100. |
A data frame with suggested postcodes.
postcode_autocomplete("E1") postcode_autocomplete("E1", limit = 11)postcode_autocomplete("E1") postcode_autocomplete("E1", limit = 11)
Lookup a postcode.
postcode_lookup(postcode)postcode_lookup(postcode)
postcode |
A string. One valid UK postcode.
This function is case- and space-insensitive.
For more than one postcode use |
A data frame. Returns all available data if found. Returns NAs if postcode does not exist (404).
postcode Postcode. All current ('live') postcodes within the United Kingdom,
the Channel Islands and the Isle of Man, received monthly from Royal Mail.
2, 3 or 4-character outward code, single space and 3-character inward code.
quality Positional Quality. Shows the status of the assigned grid reference.
1 - within the building of the matched address closest to the postcode mean
2 - as for status value 1, except by visual inspection of Landline maps (Scotland only)
3 - approximate to within 50m
4 - postcode unit mean (mean of matched addresses with the same postcode, but not snapped to a building)
5 - imputed by ONS, by reference to surrounding postcode grid references
6 - postcode sector mean, (mainly PO Boxes)
8 - postcode terminated prior to Gridlink(R) initiative, last known ONS postcode grid reference1
9 - no grid reference available
eastings Eastings. The Ordnance Survey postcode grid reference
Easting to 1 metre resolution; blank for postcodes in the
Channel Islands and the Isle of Man.
Grid references for postcodes in Northern Ireland relate to the Irish Grid system.
northings Northings. The Ordnance Survey postcode grid reference
Easting to 1 metre resolution; blank for postcodes in the
Channel Islands and the Isle of Man.
Grid references for postcodes in Northern Ireland relate to the Irish Grid system.
country Country. The country (i.e. one of the four constituent
countries of the United Kingdom or the Channel Islands or the Isle of Man)
to which each postcode is assigned.
nhs_ha Strategic Health Authority. The health area code for the postcode.
longitude Longitude.
The WGS84 longitude given the Postcode's national grid reference.
latitude Latitude.
The WGS84 latitude given the Postcode's national grid reference.
european_electoral_region European Electoral Region (EER).
The European Electoral Region code for each postcode.
primary_care_trust Primary Care Trust (PCT).
The code for the Primary Care areas in England, LHBs in Wales, CHPs in Scotland,
LCG in Northern Ireland and PHD in the Isle of Man;
there are no equivalent areas in the Channel Islands.
Care Trust/ Care Trust Plus (CT) / local health board (LHB) /
community health partnership (CHP) / local commissioning group (LCG) /
primary healthcare directorate (PHD).
region Region (formerly GOR). The Region code for each postcode.
The nine GORs were abolished on 1 April 2011 and are now known as 'Regions'.
They were the primary statistical subdivisions of England and
also the areas in which the Government Offices for the Regions fulfilled their role.
Each GOR covered a number of local authorities.
lsoa 2011 Census lower layer super output area (LSOA).
The 2011 Census lower layer SOA code for England and Wales,
SOA code for Northern Ireland and data zone code for Scotland.
msoa 2011 Census middle layer super output area (MSOA).
The 2011 Census middle layer SOA (MSOA) code for England and
Wales and intermediate zone for Scotland.
incode Incode. 3-character inward code that
is following the space in the full postcode.
outcode Outcode. 2, 3 or 4-character outward code.
The part of postcode before the space.
parliamentary_constituency Westminster Parliamentary Constituency.
The Westminster Parliamentary Constituency code for each postcode.
admin_district District.
The current district/unitary authority to which the postcode has been assigned.
parish Parish (England)/ community (Wales).
The smallest type of administrative area in England is the parish
(also known as 'civil parish'); the equivalent units in Wales are communities.
admin_county County. The current county to which the postcode has been assigned.
admin_ward Ward.
The current administrative/electoral area to which the postcode has been assigned.
ccg Clinical Commissioning Group. Clinical commissioning groups (CCGs)
are NHS organisations set up by the Health and Social Care Act 2012
to organise the delivery of NHS services in England.
nuts Nomenclature of Units for Territorial Statistics (NUTS) /
Local Administrative Units (LAU) areas.
The LAU2 code for each postcode. NUTS is a hierarchical classification of
spatial units that provides a breakdown of the European Union's
territory for producing regional statistics which are comparable across
the Union. The NUTS area classification in the United Kingdom
comprises current national administrative and electoral areas,
except in Scotland where some NUTS areas comprise whole and/or part
Local Enterprise Regions. NUTS levels 1-3 are frozen for a minimum of
three years and NUTS levels 4 and 5 are now
Local Administrative Units (LAU) levels 1 and 2 respectively.
_code Returns an ID or Code associated with the postcode.
Typically these are a 9 character code known as an ONS Code or GSS Code.
This is currently only available for districts, parishes, counties, CCGs, NUTS and wards.
See https://postcodes.io/docs for more details.
postcode_lookup("EC1Y8LX") postcode_lookup("EC1Y 8LX") # spaces are ignored postcode_lookup("DE3 5LF") # terminated postcode returns NAspostcode_lookup("EC1Y8LX") postcode_lookup("EC1Y 8LX") # spaces are ignored postcode_lookup("DE3 5LF") # terminated postcode returns NAs
Submit a postcode query and receive a complete list of postcode matches and all associated postcode data.
postcode_query(postcode, limit = 10)postcode_query(postcode, limit = 10)
postcode |
A string. Valid UK postcode. |
limit |
An integer. Limits the number of matches to return. Defaults to 10. Needs to be less than 100. |
A list of geographic properties. To return a data frame use postcode_lookup.
postcode_query("EC1Y8LX") postcode_query("EC1", limit = 11)postcode_query("EC1Y8LX") postcode_query("EC1", limit = 11)
Convenience method to validate a postcode.
postcode_validation(postcode)postcode_validation(postcode)
postcode |
A string. Valid UK postcode. |
A logical vector: True or False (meaning respectively valid or invalid postcode).
postcode_validation("EC1Y 8LX") # returns TRUE postcode_validation("XYZ") # returns FALSEpostcode_validation("EC1Y 8LX") # returns TRUE postcode_validation("XYZ") # returns FALSE
Returns a random place and all associated data
random_place()random_place()
A data frame describing a random place and all associated data.
place_lookup for documentation.
random_place()random_place()
Returns a random postcode and all available data for that postcode.
random_postcode(outcode = NULL)random_postcode(outcode = NULL)
outcode |
A string. Filters random postcodes by outcode. Returns null if invalid outcode. Optional. |
A list with a random postcode with corresponding characteristics.
postcode_lookup for documentation.
random_postcode() random_postcode("N1")random_postcode() random_postcode("N1")
Returns nearest postcodes for a given longitude and latitude.
reverse_geocoding( longitude, latitude, limit = 10, radius = 100, wideSearch = NULL )reverse_geocoding( longitude, latitude, limit = 10, radius = 100, wideSearch = NULL )
longitude |
A string or numeric. Needs to have at least three decimal points. |
latitude |
A string or numeric. Needs to have at least three decimal points. |
limit |
An integer. Limits number of postcodes matches to return. Defaults to 10. Needs to be less than 100. |
radius |
An integer. Limits number of postcodes matches to return. Defaults to 100m. Needs to be less than 2,000m. |
wideSearch |
TRUE or FALSE. Search up to 20km radius, but subject to a maximum of 10 results. Since lookups over a wide area can be very expensive, we've created this method to allow you choose to make the trade off between search radius and number of results. Defaults to false. When enabled, radius and limits over 10 are ignored. |
A list with available data.
postcode_lookup for documentation.
reverse_geocoding(0.127, 51.507) reverse_geocoding("0.1275", "51.5073", limit = 3) reverse_geocoding("0.1275", "51.5073", limit = 11, radius = 200)reverse_geocoding(0.127, 51.507) reverse_geocoding("0.1275", "51.5073", limit = 3) reverse_geocoding("0.1275", "51.5073", limit = 11, radius = 200)
Lookup a Scottish postcode.
scottish_postcode_lookup(postcode)scottish_postcode_lookup(postcode)
postcode |
A string. One valid Scottish postcode.
This function is case- and space-insensitive.
For non-Scottish postcodes use |
A data frame. Returns all available data if found. Returns NAs if postcode does not exist (404).
postcode Postcode. Royal Mail postcode.
scottish_parliamentary_constituency Scottish Parliamentary
Constituency 2014 Scottish Parliamentary Constituency.
scottish_parliamentary_constituency Scottish Parliamentary
Constituency GSS Code. A code that identifies a 2014 Scottish
Parliamentary Constituency.
See https://postcodes.io/docs for more details.
scottish_postcode_lookup("EH12NG")scottish_postcode_lookup("EH12NG")
Returns month and year if a postcode was terminated or is no longer active.
terminated_postcode(postcode)terminated_postcode(postcode)
postcode |
A string. Terminated UK postcode. |
A data frame with data about terminated postcode. NULL if postcode is active.
postcode Postcode. All currently terminated postcodes within
the United Kingdom, the Channel Islands and the Isle of Man,
received every 3 months from Royal Mail. 2, 3 or 4-character outward code,
single space and 3-character inward code.
year_terminated Termination year.
Year of termination of a postcode.
month_terminated Termination month.
Month of termination of a postcode. 1-January, 2-February, ..., 12-December.
longitude Longitude.
The WGS84 longitude given the Postcode's national grid reference.
latitude Latitude.
The WGS84 latitude given the Postcode's national grid reference.
See https://postcodes.io/docs for more details.
terminated_postcode("EC1Y 8LX") # existing postcode terminated_postcode("E1W 1UU") # terminated postcodeterminated_postcode("EC1Y 8LX") # existing postcode terminated_postcode("E1W 1UU") # terminated postcode