-
Notifications
You must be signed in to change notification settings - Fork 7
/
Introduction.Rmd
299 lines (202 loc) · 6.47 KB
/
Introduction.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
---
title: "Introduction"
author: "Eryk Walczak"
date: "`r Sys.Date()`"
output:
rmarkdown::html_vignette:
smart: no
toc: true
vignette: >
%\VignetteIndexEntry{Introduction}
%\VignetteEngine{knitr::rmarkdown}
%\VignetteEncoding{UTF-8}
---
PostcodesioR is an API wrapper for postcodes.io. It allows acquiring geographic information about the UK postcodes and geographic coordinates.
## Installation
```{r, message = FALSE, warning = FALSE, eval = FALSE}
if (!require("devtools")) install.packages("devtools")
devtools::install_github("ropensci/PostcodesioR")
```
## Lookup postcodes and outcodes
### Single postcode
Provide a postcode to obtain all available information
```{r, message = FALSE, warning = FALSE}
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
```{r}
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.
### Multiple postcodes
To query two or more postcodes, use `bulk_` functions.
```{r}
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
```{r}
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:
```{r}
scottish_lookup <- scottish_postcode_lookup("EH12NG")
str(scottish_lookup)
```
### Outward code lookup
Provide an outcode to obtain geolocation data for the centroid of the specified outcode:
```{r}
ocl <- outward_code_lookup("E1")
#overview
str(ocl)
```
## Reverse geocoding
Provide latitude and longitude to obtain geographic information. Different levels of aggregation are available, i.e. postcode or outcode.
### Single postcode
```{r}
rev_geo <- reverse_geocoding(0.127, 51.507)
# overview
str(rev_geo[1])
```
### Multiple postcodes
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.
```{r}
# 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:
```{r}
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:
```{r}
# 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:
```{r}
# 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))
```
### Single outcode
```{r}
out_rev_geocode <- outcode_reverse_geocoding("-3.15", "51.47")
# overview
str(out_rev_geocode[1])
```
## Generate random entries
### Postcodes
Generates a list with a random UK postcode and corresponding geographic information:
```{r}
# without restrictions
random_postcode()
```
A randomly generated postcode can also belong to a particular outcode:
```{r}
# restrict to an outcode
random_postcode("N1")
```
## Places
You can also generate a random place, specified by an OSGB code, with corresponding geographic information:
```{r}
random_place()
```
## Postcode validation
This function can validate a UK postcode:
```{r}
postcode_validation("EC1Y8LX") # actual UK postcode
```
```{r}
postcode_validation("XYZ") # incorrect UK postcode
```
## Autocomplete postcodes
Find the potential candidates for a postcode if you only know the beginning characters
```{r}
postcode_autocomplete("EC1")
```
It defaults to 10 candidates, but can be changed by specifying the `limit` argument.
## Find nearest postcodes or outcodes
Provide a postcode to get a list of the nearest postcodes:
```{r}
near_pc <- nearest_postcode("EC1Y8LX")
#overview
str(near_pc[1])
```
You can also use outcodes:
```{r}
near_outcode <- nearest_outcode("EC1Y")
# overview
str(near_outcode[2])
```
Or longitude and latitude
```{r}
near_ll <- nearest_outcode_lonlat(0.127, 51.507)
#overview
str(near_ll[1])
```
## Find places
Provide a name of a place of interest. You can specify the number of results (default is 10):
```{r}
place_query_result <- place_query("Hills", limit = 11)
# overview
str(place_query_result[1])
```
You can also find a place using an OSGB code:
```{r}
place_lookup_result <- place_lookup("osgb4000000074544700")
# overview
str(place_lookup_result)
```
## Terminated postcodes
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:
```{r}
terminated_postcode("E1W 1UU")
```