Merge pull request #176 from jessecambon/dev

api_options error handling

Author: jessecambon

NEWS.md

@@ -3,6 +3,7 @@
 - Changed the default `min_time` (minimum seconds elapsed per query) value to 1 (60 queries per minute) for the Location IQ service ([#166](https://github.com/jessecambon/tidygeocoder/issues/166)).
 - Updated default Geocodio API URL from version 1.6 to 1.7.
 - Fixed code and documentation that incorrectly referred to `mapquest_open` as `mapbox_open`.
+- An error is now thrown if an `api_options` parameter is not compatible with the specified `method`.
 - A message is now displayed warning that `flatten=FALSE` is ignored for Geocodio and Mapquest (the output of these services requires flattening to avoid errors).
 
 # tidygeocoder 1.0.5

R/geo.R

@@ -238,9 +238,9 @@ geo <-
         api_options[["here_request_id"]] <- here_request_id
       }
     }
-
+    
     # apply api options defaults for options not specified by the user
-    api_options <- apply_api_options_defaults(api_options)
+    api_options <- apply_api_options_defaults(method, api_options)
 
     # capture all function arguments including default values as a named list.
     # IMPORTANT: make sure to put this statement before any other variables are defined in the function
@@ -267,7 +267,7 @@ geo <-
 
     # Check parameter arguments --------------------------------------------------------
 
-    check_api_options(api_options, "geo")
+    check_api_options(method, api_options, FALSE, return_addresses)
 
     # Check argument inputs
     if (is.null(address) && is.null(street) && is.null(city) && is.null(county) && is.null(state) && is.null(postalcode) && is.null(country)) {
@@ -282,29 +282,24 @@ geo <-
     check_address_argument_datatype(postalcode, "postalcode")
     check_address_argument_datatype(country, "country")
 
-    if (!(api_options[["census_return_type"]] %in% c("geographies", "locations"))) {
-      stop("Invalid return_type argument. See ?geo", call. = FALSE)
+    if (!is.null(api_options[["census_return_type"]])) {
+      if (!(api_options[["census_return_type"]] %in% c("geographies", "locations"))) {
+        stop("Invalid census_return_type argument. See ?geo", call. = FALSE)
+      }
     }
 
     stopifnot(
       is.logical(verbose), is.logical(no_query), is.logical(flatten), is.null(param_error) || is.logical(param_error),
       is.logical(full_results), is.logical(unique_only), is.logical(return_addresses),
       is.null(batch_limit_error) || is.logical(batch_limit_error), is.logical(progress_bar), is.logical(quiet),
       is.numeric(timeout), timeout >= 0,
-      is.list(custom_query),
-      is.logical(api_options[["mapbox_permanent"]]),
-      is.null(api_options[["here_request_id"]]) || is.character(api_options[["here_request_id"]]),
-      is.logical(api_options[["mapquest_open"]]), is.logical(api_options[["geocodio_hipaa"]])
+      is.list(custom_query)
     )
 
     check_verbose_quiet(verbose, quiet, reverse = FALSE)
     check_common_args("geo", mode, limit, batch_limit, min_time)
     check_method(method, reverse = FALSE, mode, batch_func_map, cascade_order = cascade_order)
 
-    if (!(api_options[["census_return_type"]] %in% c("geographies", "locations"))) {
-      stop("Invalid census_return_type value. See ?geo", call. = FALSE)
-    }
-
     # Deprecate parameters that only existed because of method = "cascade"
     if (api_options[["init"]] == TRUE) {
       if (!missing("cascade_order")) lifecycle::deprecate_warn("1.0.4", "geo(cascade_order)", "geocode_combine()")

R/global_variables.R

@@ -26,6 +26,11 @@ pkg.globals$no_reverse_methods <- c("census")
 # these methods do not support flatten=FALSE for batch geocoding
 pkg.globals$batch_flatten_required_methods <- c("geocodio", "mapquest")
 
+# these are special api_options parameters that do not correspond to a method
+#   cascade_flag: indicates (deprecated) cascade method was used
+#   init: indicates if this is the first pass through the geo or reverse_geo function
+pkg.globals$special_api_options <- c("cascade_flag", "init")
+
 # default settings for the `api_options` argument in geo() and reverse_geo()
 pkg.globals$default_api_options <- list(
   census_return_type = "locations",

R/input_handling.R

@@ -6,20 +6,21 @@
 # utility function for packaging either lat longs or address data
 # takes a dataframe input
 # cords = TRUE if processing coordinates
+# note that reverse_geo() converts lat and long into numeric before passing to this function
 package_inputs <- function(input_orig, coords = FALSE) {
   input_colnames <- names(input_orig) # store column names
 
   input_unique <- input_orig
 
   # limit lat/longs in unique dataset to possible values
   if (coords == TRUE) {
-    input_unique$lat[(input_unique$lat > 90 | input_unique$lat < -90)] <- NA
-    input_unique$long[(input_unique$long > 180 | input_unique$long < -180)] <- NA
+    input_unique$lat[(input_unique$lat > 90 | input_unique$lat < -90)] <- as.numeric(NA)
+    input_unique$long[(input_unique$long > 180 | input_unique$long < -180)] <- as.numeric(NA)
 
     # If lat is NA then make long NA and vice versa (ie. don't pass coordinate if
     # only one value exists)
-    input_unique$lat <- ifelse(is.na(input_unique$long), NA, input_unique$lat)
-    input_unique$long <- ifelse(is.na(input_unique$lat), NA, input_unique$long)
+    input_unique$lat <- ifelse(is.na(input_unique$long), as.numeric(NA), input_unique$lat)
+    input_unique$long <- ifelse(is.na(input_unique$lat), as.numeric(NA), input_unique$long)
   }
 
   # remove rows that are entirely blank or NA

R/results_processing.R

@@ -108,7 +108,7 @@ extract_results <- function(method, response, full_results = TRUE, flatten = TRU
 
     # add prefix to variable names that likely could be in our input dataset
     # to avoid variable name overlap
-    for (var in c("address", "street", "city", "county", "state", "postalcode", "postcode", "country")) {
+    for (var in c(pkg.globals$address_arg_names, "postcode")) {
       if (var %in% names(results)) {
         names(results)[names(results) == var] <- paste0(method, "_", var)
       }
@@ -177,7 +177,7 @@ extract_reverse_results <- function(method, response, full_results = TRUE, flatt
     "geoapify" = response$features$properties["formatted"]
   )
 
-  # Return NA if data is not empty or not valid (cannot be turned into a dataframe)
+  # Return NA if data is empty or not valid (cannot be turned into a dataframe)
   if (is.null(names(address)) | all(sapply(address, is.null)) | length(address) == 0) {
     return(NA_result)
   }

R/reverse_geo.R

@@ -171,7 +171,7 @@ reverse_geo <-
     }
 
     # apply api options defaults for options not specified by the user
-    api_options <- apply_api_options_defaults(api_options)
+    api_options <- apply_api_options_defaults(method, api_options)
 
     # capture all function arguments including default values as a named list.
     # IMPORTANT: make sure to put this statement before any other variables are defined in the function
@@ -185,17 +185,13 @@ reverse_geo <-
       is.logical(verbose), is.logical(no_query), is.logical(flatten),
       is.logical(full_results), is.logical(unique_only), is.logical(progress_bar),
       is.logical(quiet),
-      is.list(custom_query),
-      is.logical(api_options[["mapbox_permanent"]]),
-      is.null(api_options[["here_request_id"]]) || is.character(api_options[["here_request_id"]]),
-      is.logical(api_options[["mapquest_open"]]), is.logical(api_options[["geocodio_hipaa"]])
+      is.list(custom_query)
     )
 
     check_verbose_quiet(verbose, quiet, reverse = FALSE)
 
     # Check method argument
-
-    check_api_options(api_options, "reverse_geo")
+    check_api_options(method, api_options, TRUE, return_coords)
     check_method(method, reverse = TRUE, mode, reverse_batch_func_map)
 
     if (length(lat) != length(long)) stop("Lengths of lat and long must be equal.", call. = FALSE)
@@ -288,8 +284,6 @@ reverse_geo <-
         ))
       }
 
-      if (method == "here") check_here_return_input(api_options[["here_request_id"]], return_coords, reverse = TRUE)
-
       # Enforce batch limit if needed
       if (num_unique_coords > batch_limit) {
         stop(paste0(

R/utils.R

@@ -104,20 +104,6 @@ format_address <- function(df, fields) {
 # QA Checks --------------------------------------------------------------------
 # functions called by reverse_geo() and/or geo()
 
-check_api_options <- function(api_options, func_name) {
-  for (param in names(api_options)) {
-    if (!param %in% c("cascade_flag", "init", names(pkg.globals$default_api_options))) {
-      stop(
-        paste0(
-          "Invalid parameter ", '"', param, '"',
-          " used in the api_options argument. See ?", func_name
-        ),
-        call. = FALSE
-      )
-    }
-  }
-}
-
 # check the data type of an address argument - called by geo() function
 # should not be a matrix, class, or dataframe for instance
 # allow factor since it could be coerced to a datatype by address handler function
@@ -229,22 +215,6 @@ check_limit_for_batch <- function(limit, return_input, reverse) {
   }
 }
 
-
-# check for HERE method batch queries --- for use in geo() and reverse_geo()
-check_here_return_input <- function(here_request_id, return_input, reverse) {
-  input_terms <- get_coord_address_terms(reverse)
-
-  # If a previous job is requested return_addresses should be FALSE
-  # This is because the job won't send the addresses, but would recover the
-  # results of a previous request
-  if (is.character(here_request_id) && return_input == TRUE) {
-    stop("HERE: When requesting a previous job via here_request_id, set ", input_terms$return_arg,
-      " to FALSE. See ?", input_terms$base_func_name, " for details.",
-      call. = FALSE
-    )
-  }
-}
-
 # Misc -----------------------------------------------------------------------------------------
 
 ## function for extracting everything except the single line
@@ -349,15 +319,26 @@ api_url_modification <- function(method, api_url, generic_query, custom_query, r
   return(api_url)
 }
 
-# apply api options defaults for options not specified by the user.
-# called by geo() and reverse_geo()
-apply_api_options_defaults <- function(api_options) {
-  for (name in names(pkg.globals$default_api_options)) {
-    if (is.null(api_options[[name]])) api_options[[name]] <- pkg.globals$default_api_options[[name]]
+
+# for specific geocoders in batch setting...
+# give a warning that the query is going to run with flatten=TRUE
+# even though the user specified flatten=FALSE
+flatten_override_warning <- function(flatten, method, reverse, batch) {
+  if (flatten == FALSE && (method %in% pkg.globals$batch_flatten_required_methods)) {
+    input_terms <- get_coord_address_terms(reverse)
+    message(paste0(
+      "Note: flatten=FALSE is ignored. Outputs must be flattened for the ",
+      get_setting_value(tidygeocoder::api_info_reference, method, "method_display_name"), " ",
+      if (batch == TRUE) "batch" else paste0("single ", input_terms$input_singular),
+      " geocoder"
+    ))
   }
-  return(api_options)
 }
 
+
+
+# Api options functions ----------------------------------------------------------------------
+
 # Set the api_options[["init"]] parameter
 # init is for internal package use only, used to designate if the geo() or reverse_geo() function
 # is being called for the first time (init = TRUE) or if it has called itself
@@ -369,17 +350,94 @@ initialize_init <- function(api_options) {
   return(api_options)
 }
 
-# for specific geocoders in batch setting...
-# give a warning that the query is going to run with flatten=TRUE
-# even though the user specified flatten=FALSE
-flatten_override_warning <- function(flatten, method, reverse, batch) {
-  if (flatten == FALSE && (method %in% pkg.globals$batch_flatten_required_methods)) {
-    input_terms <- get_coord_address_terms(reverse)
-    message(paste0(
-      "Note: flatten=FALSE is ignored. Outputs must be flattened for the ",
-      get_setting_value(tidygeocoder::api_info_reference, method, "method_display_name"), " ",
-      if (batch == TRUE) "batch" else paste0("single ", input_terms$input_singular),
-      " geocoder"
-    ))
+# check for HERE method batch queries --- for use in geo() and reverse_geo()
+check_here_return_input <- function(here_request_id, return_input, reverse) {
+  input_terms <- get_coord_address_terms(reverse)
+  
+  # If a previous job is requested return_addresses should be FALSE
+  # This is because the job won't send the addresses, but would recover the
+  # results of a previous request
+  if (is.character(here_request_id) && return_input == TRUE) {
+    stop("HERE: When requesting a previous job via here_request_id, set ", input_terms$return_arg,
+         " to FALSE. See ?", input_terms$base_func_name, " for details.",
+         call. = FALSE
+    )
+  }
+}
+
+# apply api options defaults for options not specified by the user
+# that are relevant for the specified method
+# called by geo() and reverse_geo()
+apply_api_options_defaults <- function(method, api_options) {
+  for (api_opt in names(pkg.globals$default_api_options)) {
+    api_opt_method <- strsplit(api_opt, "_")[[1]][[1]] # extract method name from api option
+    
+    if ((method == api_opt_method) && is.null(api_options[[api_opt]])) {
+      api_options[[api_opt]] <- pkg.globals$default_api_options[[api_opt]]
+    } 
+  }
+  return(api_options)
+}
+
+# throw error if method and a specified api_option is mismatched 
+# ie. method='census' and api_options(list(geocodio_hipaa=TRUE))
+# return_inputs : return_addresses for geo() or return_inputs for reverse_geo()
+check_api_options <- function(method, api_options, reverse, return_inputs) {
+  
+  stopifnot(
+    is.null(api_options[["mapbox_permanent"]]) || is.logical(api_options[["mapbox_permanent"]]),
+    is.null(api_options[["here_request_id"]]) || is.character(api_options[["here_request_id"]]),
+    is.null(api_options[["mapquest_open"]]) || is.logical(api_options[["mapquest_open"]]),
+    is.null(api_options[["geocodio_hipaa"]]) || is.logical(api_options[["geocodio_hipaa"]])
+  )
+  
+  if (method == "here") check_here_return_input(api_options[["here_request_id"]], return_inputs, reverse = reverse)
+  
+  
+  # cycle through the api options specified (except for init)
+  #  if (api_options$init == TRUE) {
+  api_method_mismatch_args <- c() # store mismatch api_options here
+  api_bad_args <- c() # store invalid api_options here
+  error_message <- c() # store error message here (if any)
+  
+  for (api_opt in names(api_options)[!names(api_options) %in% pkg.globals$special_api_options]) {
+    # extract method name from api_option
+    api_opt_method <- strsplit(api_opt, "_")[[1]][[1]]
+    
+    # check if api parameter is valid
+    if (!api_opt %in% names(pkg.globals$default_api_options)) {
+      api_bad_args <- c(api_bad_args, api_opt)
+    }
+    # if api parameter is valid but there is a mismatch with selected method
+    # then add offending arg to vector
+    else if (api_opt_method != method) {
+      api_method_mismatch_args <- c(api_method_mismatch_args, api_opt)
+    }
+  } # end loop
+  
+  # error message for bad api arguments
+  if (length(api_bad_args) != 0) {
+    error_message <- c(error_message,
+       paste0(
+         "Invalid api_options parameter(s) used:\n\n",
+         paste0(api_bad_args, sep = "  "), "\n\n"
+       ))
+  }
+  
+  # error message for api arguments that mismatch with the method argument
+  if (length(api_method_mismatch_args) != 0) {
+    error_message <- c(error_message,
+      'method = "', method, '" is not compatible with the specified api_options parameter(s):\n\n',
+      paste0(api_method_mismatch_args, sep = "  "), "\n\n"
+    )
+  }
+  
+  # show error (if applicable)
+  if (length(error_message) != 0) {
+    stop(error_message,
+      'See ?', if (reverse == TRUE) "reverse_geo" else "geo",
+      call. = FALSE
+    )
   }
+#  }
 }