du_google_geocode: get geocode with error handling built in,reasons are given...
In yusuzech/dfutils: Utility Functions to Work with Tabular Data

Description Usage Arguments Details Value Examples

getting geocode can be tedious sometimes since sometimes we get errors, sometimes we multiple matched results. And doing the error/exception handling has always been a headache. This functions tries do the error handling for your api call won't be interrupted by any errors and you receive clean results.

Note that since this function won't be interrupted, please always test in smaller scale to make sure everything is working as intended.

du_google_geocode(
  address,
  apikey,
  result_type = c("list", "df", "raw"),
  multi_coord_handling = c("none", "first", "average"),
  progress = TRUE,
  show_summary = TRUE
)

`address`	a character vector that contains address(es)
`apikey`	google's apikey for using geocode service
`result_type`	how should the results be returned, see more in details
`multi_coord_handling`	how to handle results with multiple matching coordinates
`progress`	whether to show a progress bar
`show_summary`	whether to show a summary on job status

result_type:

This function returns a list of two parts, result and error, and result_type determines how result is structured. If a item fails or has been processed by this function internally, a comment will show. Otherwise, comment will be NA.

result

list: returns a list of 3 elements, lat,lng and comment
df: returns a data frame with 3 columns, lat, lng and comment
raw: returns the raw result from google's api as a list. Don't show any comments and this function don't process any data (multi_coord_handling won't be applied),you receive everything provided by geocode api

error

a list that shows the error or special treatment for items in result

multiple_coord_handling

Sometimes an address can be confusing to google's geocode API and multiple matches are returned. For data analysis, It is undesirable in most cases. So this functions tries handle this situation automatically. Regardless how this functions handles this scenario, one entry is generated in error.

none: no hanlding, the coordinates will be NA
first: use the first coordinates provided
average: average all coordinates and use it as result

show_summary

summary will be printed to console, it shows how many addresses are tried in total, how many succeeded or failed

comment

Below are explanations for comments:

API Error: something's wrong during API call
Multiple Matches Error: Multiple paries of coordinates found for the same address.
Multiple Matches Found, Using First Result: use the first result returned by geocode API
Multiple Matches Found, Using Average Coordinates: use the average of coordinates returned by geocode API

a list of two elements result and error, return details are dependent on result_type argument.

## Not run: 
apikey = your_apikey
du_google_geocode(
    c(
        "new york, usa",
        "#####", # contains error
        "canada, usa" # multiple matching results
    )
)

## End(Not run)