Client for the 'IPGeolocation.io IP Location API'

Provides functions to query the 'IPGeolocation.io IP Location API' (< https://ipgeolocation.io/documentation/ip-location-api.html>). Supports retrieval of IP location, ASN, network, currency, timezone, abuse, and security data. Response filtering is supported using 'fields' and 'excludes' parameters (dot notation supported), and optional objects can be requested via the 'include' parameter. Returns parsed API responses as R objects.

ipgeolocation

R client for the IPGeolocation.io IP Location API. This package provides a minimal interface to query the IPGeolocation.io IP Location API from R.

Installation

Until published on CRAN:

# install.packages("remotes")
remotes::install_github("ipgeolocation/ipgeolocation-r")

Once available on CRAN:

install.packages("ipgeolocation")

API Key

An API key is required. You can obtain one from https://ipgeolocation.io/.

It is recommended to store the API key in an environment variable:

Sys.setenv(IPGEOLOCATION_API_KEY = "YOUR_API_KEY")
api_key <- Sys.getenv("IPGEOLOCATION_API_KEY")

Basic Usage

library(ipgeolocation)

result <- ipgeo(
  ip      = "8.8.8.8",
  api_key = api_key
)

str(result)

Selecting Specific Fields (fields)

The fields parameter allows you to return only selected objects or nested fields. It supports:

• Entire objects (e.g., "location")
• Nested fields using dot notation (e.g., "location.city")

You may provide either a character vector or a comma-separated string.

# Entire object
ipgeo(ip = "8.8.8.8", api_key = api_key,
      fields = "location")

# Nested field
ipgeo(ip = "8.8.8.8", api_key = api_key,
      fields = "location.city")

# Multiple fields
ipgeo(ip = "8.8.8.8", api_key = api_key,
      fields = c("location", "location.city"))

# Comma-separated string
ipgeo(ip = "8.8.8.8", api_key = api_key,
      fields = "location,security")

Excluding Fields (excludes)

The excludes parameter removes specific objects or nested fields from the default response. It supports entire objects and dot notation for nested fields.

# Exclude entire object
ipgeo(ip = "8.8.8.8", api_key = api_key,
      excludes = "security")

# Exclude nested field
ipgeo(ip = "8.8.8.8", api_key = api_key,
      excludes = "location.zipcode")

# Multiple exclusions
ipgeo(ip = "8.8.8.8", api_key = api_key,
      excludes = c("location.zipcode", "continent_code"))

Including Additional Modules (include)

The include parameter requests additional modules not part of the default response. Supported module names are "hostname", "security", "dma_code", "abuse", "geo_accuracy", and "user_agent".

Note: Dot notation is not supported for include. Comma-separated values and character vectors are accepted. Availability depends on your API plan.

ipgeo(
  ip      = "8.8.8.8",
  api_key = api_key,
  include = "security"
)

ipgeo(
  ip      = "8.8.8.8",
  api_key = api_key,
  include = c("security", "hostname")
)

Combining Parameters

fields, excludes, and include can be used together:

ipgeo(
  ip      = "8.8.8.8",
  api_key = api_key,
  fields  = c("location", "location.city"),
  excludes = "location.zipcode",
  include  = "security"
)

Error Handling

The function validates parameter types, normalizes vectors to comma-separated strings, fails gracefully if the API is unreachable, and returns parsed JSON as an R list.

Function Reference

ipgeo()

Returns: A list parsed from the JSON API response.

License

MIT