R/api_url.R

In tidygeocoder: Geocoding Made Easy

# API URL Functions
# reverse = TRUE for reverse geocoding

## wrapper function for functions below
### IMPORTANT: if arguments are changed in this definition then make sure to
### update reverse_geo.R and geo.R where this function is called.
get_api_url <- function(method,
                        reverse = FALSE,
                        return_type = "locations",
                        search = "onelineaddress",
                        geocodio_v = pkg.globals$default_api_options$geocodio_v,
                        iq_region = pkg.globals$default_api_options$iq_region,
                        mapbox_permanent = pkg.globals$default_api_options$mapbox_permanent,
                        mapquest_open = pkg.globals$default_api_options$mapquest_open,
                        geocodio_hipaa = pkg.globals$default_api_options$geocodio_hipaa) {
  api_url <- switch(method,
    "osm" = get_osm_url(reverse = reverse),
    "census" = get_census_url(return_type, search),
    "geocodio" = get_geocodio_url(geocodio_v, reverse = reverse, geocodio_hipaa = geocodio_hipaa),
    "iq" = get_iq_url(iq_region, reverse = reverse),
    "opencage" = get_opencage_url(),
    "google" = get_google_url(),
    "mapbox" = get_mapbox_url(mapbox_permanent),
    "here" = get_here_url(reverse = reverse),
    "tomtom" = get_tomtom_url(reverse = reverse),
    "mapquest" = get_mapquest_url(mapquest_open, reverse = reverse),
    "bing" = get_bing_url(),
    "arcgis" = get_arcgis_url(reverse = reverse),
    "geoapify" = get_geoapify_url(reverse = reverse)
  )

  if (length(api_url) == 0) stop("API URL not found", call. = FALSE)
  return(api_url)
}

##############################################################################################


# return : returntype => 'locations' or 'geographies'
# search:  searchtype => 'onelineaddress', 'addressbatch', 'address', or 'coordinates'
get_census_url <- function(return_type, search) {
  return(paste0("https://geocoding.geo.census.gov/geocoder/", return_type, "/", search))
}

get_geocodio_url <- function(api_v, reverse = FALSE, geocodio_hipaa = FALSE) {
  # return API URL based on api version (ex. 1.6)
  url_base <- if (geocodio_hipaa == TRUE) "https://api-hipaa.geocod.io/v" else "https://api.geocod.io/v"
  url_keyword <- if (reverse == TRUE) "reverse" else "geocode"
  return(paste0(url_base, as.character(api_v), "/", url_keyword))
}

get_osm_url <- function(reverse = FALSE) {
  url_keyword <- if (reverse == TRUE) "reverse" else "search"
  return(paste0("https://nominatim.openstreetmap.org/", url_keyword))
}

get_iq_url <- function(region = "us", reverse = FALSE) {
  # region can be 'us' or 'eu'
  url_keyword <- if (reverse == TRUE) "reverse" else "search"
  return(paste0("https://", region, "1.locationiq.com/v1/", url_keyword, ".php"))
}

get_google_url <- function() {
  return("https://maps.googleapis.com/maps/api/geocode/json")
}

get_opencage_url <- function() {
  return("https://api.opencagedata.com/geocode/v1/json")
}

get_mapbox_url <- function(mapbox_permanent = FALSE) {
  endpoint <- if (mapbox_permanent == TRUE) "mapbox.places-permanent" else "mapbox.places"
  return(paste0("https://api.mapbox.com/geocoding/v5/", endpoint, "/"))
}

get_here_url <- function(reverse = FALSE) {
  if (reverse == TRUE) {
    return("https://revgeocode.search.hereapi.com/v1/revgeocode")
  }
  return("https://geocode.search.hereapi.com/v1/geocode")
}

get_tomtom_url <- function(reverse = FALSE) {
  url_keyword <- if (reverse == TRUE) "reverseGeocode/" else "geocode/"
  return(paste0("https://api.tomtom.com/search/2/", url_keyword))
}

get_mapquest_url <- function(mapquest_open = FALSE, reverse = FALSE) {
  endpoint <- if (mapquest_open == TRUE) "http://open." else "http://www."
  url_keyword <- if (reverse == TRUE) "reverse" else "address"
  return(paste0(endpoint, "mapquestapi.com/geocoding/v1/", url_keyword))
}

get_bing_url <- function() {
  return("http://dev.virtualearth.net/REST/v1/Locations")
}

get_arcgis_url <- function(reverse = FALSE) {
  if (reverse == TRUE) {
    return("https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/reverseGeocode")
  } else {
    return("https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates")
  }
}

get_geoapify_url <- function(reverse = FALSE) {
  endpoint <- if (reverse) "reverse" else "search"
  return(paste0("https://api.geoapify.com/v1/geocode/", endpoint))
}