vignettes/adding_geocoder_services.Rmd
adding_geocoder_services.Rmd
This page documents how to add support for a new geocoder service to the package. Required changes are organized by file. If anything isn’t clear, feel free to file an issue.
Base all changes on the main branch.
The two core functions to focus on in the package are geo() and reverse_geo(). These functions have a very similar layout, but geo()
is for forward geocoding while reverse_geo()
is for reverse geocoding. The geocode()
and reverse_geocode()
functions extract input data and pass it to the geo()
and reverse_geo()
functions respectively.
Both the geo()
and reverse_geo()
functions take inputs (either addresses or coordinates) and call other functions as needed to deduplicate the inputs, pause to comply with API usage rate policies, and execute geocoding queries. Key parameters and settings for geocoding are stored for easy access and display in built-in datasets which are documented below.
get_api_url()
function accordingly. If arguments need to be added to the get_api_url()
function, make sure to adjust the calls to this function in the geo()
and reverse_geo()
functions accordingly.method
column (which is how the service is specified in the geo()
and geocode()
functions). The generic_name
column has the universal parameter name that is used across geocoder services (ie. “address”, “limit”, etc.) while the api_name
column stores the parameter names that are specific to the geocoder service.generic_name
) unless the parameters are required. Parameters can always be passed to services directly with the custom_query
argument in geo()
or reverse_geo()
.min_time_reference
with the minimum time each query should take (in seconds) according to the geocoder service’s free tier usage restrictions.api_key_reference
if the service requires an API key.batch_limit_reference
.api_info_reference
with links to the service’s website, documentation, and usage policy.extract_results()
function which is used for parsing single addresses (ie. not batch geocoding). You can see examples of how I’ve tested out parsing the results of geocoder services here.extract_reverse_results()
function for reverse geocoding.extract_errors_from_results()
function to extract error messages for invalid queries.geo()
.get_coord_parameters()
function based on how the service passed latitude and longitude coordinates for reverse geocoding.reverse_batch_func_map
named list.geo_<method>()
convenience function to R/geo_methods.R.no_query = TRUE
in the geo()
and geocode()
functions.These files don’t necessarily need to be updated. However, you might need to make changes to these files if the service you are implementing requires some non-standard workarounds.
verbose = TRUE
to make sure it behaves as expected. You can reference tests available the ‘sandbox’ folder for reference.devtools::check()
to make sure the package still passes all tests and the vignette runs properly. To only run the package tests use devtools::test()
, but note these tests do not query the geocoder services to avoid external dependencies.devtools::test()
) because they require API keys which would not exist on all systems and are dependent on the geocoder services being online at that the time of the test.