| Title: | Offline Geocoding with One File per Country |
|---|---|
| Description: | Geocodes addresses and reverse-geocodes coordinates on the local machine, without a server, an API key or a network request per address. Each country is one memory-mapped file built from Overture Maps and open address registers, downloaded once and verified against the release checksums. Answers carry their precision (house, street, city) and a confidence score, so uncertain matches can be checked before use. |
| Authors: | GridPin [aut, cre, cph], Authors of the dependency Rust crates [aut, cph] (see inst/AUTHORS) |
| Maintainer: | GridPin <[email protected]> |
| License: | Apache License (== 2.0) |
| Version: | 0.6.0 |
| Built: | 2026-10-31 21:12:23 UTC |
| Source: | https://github.com/gridpin/gridpin |
Close a geocoder and unmap its sheet
gp_close(geocoder)gp_close(geocoder)
geocoder |
A geocoder from [gp_open()]. |
Fetches the sheet of the GridPin release this package was built for, checks its size and SHA-256 against the values pinned in the package, and only then moves it into [gp_home()]. A sheet that is already there is not fetched again. This is the only function that uses the network; set 'GRIDPIN_OFFLINE=1' to forbid it.
gp_download(country)gp_download(country)
country |
A country code or name from [gp_sheets()]. |
The path of the sheet, invisibly.
Every address is matched on your machine against the sheet; nothing is sent anywhere.
gp_geocode(x, sheet, k = 1, sf = FALSE)gp_geocode(x, sheet, k = 1, sf = FALSE)
x |
A character vector of addresses. 'NA' gives a row without coordinates. |
sheet |
A geocoder from [gp_open()], a country code, or a path to a sheet. |
k |
How many candidates to return per address. With 'k = 1' the result has one row per address, in input order; with more, one row per candidate and 'rank' numbers them. |
sf |
Return an 'sf' object with WGS84 points (needs the sf package). |
A data frame with 'query', 'rank', 'lat', 'lon', 'precision' ('house', 'interp', 'near', 'street', 'city'), 'confidence', 'weak' ('TRUE' when the answer is too uncertain to use without a check), the matched 'housenumber', 'street', 'postcode', 'commune', and 'flags'. Addresses that are not found keep their row with 'NA' coordinates.
g <- gp_open(system.file("extdata", "tiny.bin", package = "gridpin")) gp_geocode(c("3 Main Street, Springfield", "Nowhere 99"), g)g <- gp_open(system.file("extdata", "tiny.bin", package = "gridpin")) gp_geocode(c("3 Main Street, Springfield", "Nowhere 99"), g)
Add coordinates to a data frame column of addresses
gp_geocode_df(df, column, sheet, sf = FALSE)gp_geocode_df(df, column, sheet, sf = FALSE)
df |
A data frame. |
column |
Name of the column with the address text. |
sheet |
A geocoder from [gp_open()], a country code, or a path to a sheet. |
sf |
Return an 'sf' object with WGS84 points (needs the sf package). |
'df' with the columns of [gp_geocode()] prefixed 'gp_' (except 'query' and 'rank').
'GRIDPIN_HOME' if set, otherwise the user cache directory for R packages ([tools::R_user_dir()]). Sheets already downloaded by the Python package 'gridpin-mcp' ('~/.cache/gridpin') are found and used without a second download.
gp_home()gp_home()
Loads a country sheet into memory (the file is memory-mapped, so opening is fast and several R sessions share the pages). Opening the same file again returns the same geocoder.
gp_open(sheet)gp_open(sheet)
sheet |
A country code or name from [gp_sheets()] (the sheet must be downloaded, see [gp_download()]) or the path to a '.bin' sheet file. |
An object of class 'gridpin_geocoder'.
g <- gp_open(system.file("extdata", "tiny.bin", package = "gridpin")) gp_geocode("3 Main Street, Springfield", g)g <- gp_open(system.file("extdata", "tiny.bin", package = "gridpin")) gp_geocode("3 Main Street, Springfield", g)
Reverse geocode: the nearest indexed address to each point
gp_reverse(lat, lon, sheet, k = 1)gp_reverse(lat, lon, sheet, k = 1)
lat, lon
|
Numeric vectors of WGS84 coordinates of the same length. |
sheet |
A geocoder from [gp_open()], a country code, or a path to a sheet. |
k |
How many candidates to return per address. With 'k = 1' the result has one row per address, in input order; with more, one row per candidate and 'rank' numbers them. |
A data frame like [gp_geocode()] with 'distance_m', the distance from the point to the answer. Streets are indexed by their centre, so check 'distance_m' before treating the answer as the building at the point.
Uses [tools::sha256sum()] (R 4.5 and newer) or, on older R, the digest package.
gp_sha256(path)gp_sha256(path)
path |
Path to a file. |
Lower-case hexadecimal digest.
Path of a downloaded sheet
gp_sheet_path(country)gp_sheet_path(country)
country |
A country code or name from [gp_sheets()]. |
Available sheets and whether they are downloaded
gp_sheets()gp_sheets()
A data frame: 'code', 'country', 'size_mb', 'downloaded', 'path'.
gp_sheets()gp_sheets()
Versions, for the methods section of your study
gp_version(sheet = NULL)gp_version(sheet = NULL)
sheet |
Optional: a geocoder or sheet, to report its file and size. |
A named list: package version, C interface version, sheet release, and the sheet file.