R/bulk-lookup.R

In hrbrmstr/ipstack: Tools to Query 'IP' Address Information from the 'ipstack' 'API'

#' Perform "bulk" IP lookup
#'
#' @md
#' @param ips a character vector of IP addresses to lookup (madx 50)
#' @param fields When `NULL` all fields that the `ipstack_api_key` has access to
#'        will be returned. Otherwise, specify a character vector of field names
#'        according to the [API reference](https://ipstack.com/documentation#fields).
#' @param hostname By default, the `ipstack` API does not return information about
#'        the hostname the given IP address resolves to. In order to include the
#'        hostname object in your API result set this to `TRUE`.
#' @param security Customers subscribed to the "Professional Plus Plan" may access
#'        the `ipstack` API's Security Module, which can be used to assess risks
#'        and threats originating from certain IP addresses before any harm can be
#'        done to a website or web application. In order to use this feature set
#'        this parameter to `TRUE`. NOTE: requests will fail if this parameter is
#'        set to `TRUE` and your plan does not have authority to access security
#'        information.
#' @param language Defaults to `en` (English). But can be [any, valid 2-letter
#'        language spec supported by the API](https://ipstack.com/documentation#language).
#' @param ssl if your plan supports making calls via `https` vs plaintet `http` set
#'        this to `TRUE`
#' @param ipstack_api_key if not placed in the `IPSTACK_API_KEY` environment
#'        variable, place it here. Otherwise, API requests fail
#' @return `list`
#' @references <https://ipstack.com/documentation>
#' @note Bulk requests are not supported on all plans
#' @export
#' @examples \dontrun{
#' bulk_lookup(c("134.201.250.155", "72.229.28.185", "110.174.165.78"))
#' }
bulk_lookup <- function(ips, fields = NULL,
                         hostname = FALSE,
                         security = FALSE,
                         language = "en",
                         ssl = FALSE,
                         ipstack_api_key = Sys.getenv("IPSTACK_API_KEY")) {

  if (length(ips) > 50) {
    stop("Max 50 'ips' allowed for bulk lookups", call.=FALSE)
  } else {
    ips <- paste0(trimws(ips), collapse=",")
  }

  scheme <- if (ssl) "https" else "http"

  httr::GET(
    url = sprintf("%s://api.ipstack.com/%s", scheme, ips),
    httr::user_agent("ipstack R pkg https://gitlab.com/hrbrmstr/ipstack"),
    query = list(
      fields = paste0(trimws(fields), collapse=","),
      hostname = as.integer(hostname),
      security = as.integer(security),
      language = language,
      access_key = ipstack_api_key
    )
  ) -> res

  httr::stop_for_status(res)

  out <- httr::content(res, as = "text", encode = "UTF-8")

  jsonlite::fromJSON(out)

}