Several candidates, and reverse geocoding

When the address is ambiguous

An address without a town can match the same street in several places. With k greater than one, gp_geocode() returns a long table: one row per candidate, numbered by rank.

gp_geocode("1 Main Street", sheet, k = 3)[, c("query", "rank", "commune", "precision", "weak")]
#>           query rank     commune precision  weak
#> 1 1 Main Street    1 Springfield     house FALSE
#> 2 1 Main Street    2 Shelbyville     house FALSE

With k = 1 (the default) you get the best candidate only, one row per address. The best candidate of a k = 3 call is not always the same as the single answer of a k = 1 call: keep k = 1 when you want one answer per address, and use k > 1 to show alternatives to a person who chooses.

From coordinates to the nearest address

gp_reverse(c(40.7504, 40.7601), c(-73.9904, -73.9801), sheet)[,
  c("point", "housenumber", "street", "distance_m")]
#>                     point housenumber      street distance_m
#> 1 40.7504000, -73.9904000           5 Main Street          0
#> 2 40.7601000, -73.9801000          10  Oak Avenue         14

Streets without house points are indexed by their centre, so the nearest answer can be some distance away: distance_m says how far. Missing coordinates (NA) give a row without an answer.

Opening and closing

gp_open() maps the file into memory once; later calls with the same file reuse it, and several R sessions share the pages. gp_close() releases it.

g <- gp_open(sheet)
g
#> <gridpin_geocoder> /tmp/Rtmp1qXd6a/Rinst9c53eeec348/gridpin/extdata/tiny.bin
gp_close(g)