genderapi_client: Create a GenderAPI.io V2 client

In genderapi: Official 'GenderAPI.io' V2 Client

Create a GenderAPI.io V2 client

Description

A client holds the API key, base URL, timeout and user agent. Creating a client never sends a request. Every request function takes a client argument that defaults to genderapi_client(), so setting the GENDERAPI_API_KEY environment variable is enough for most scripts.

Usage

genderapi_client(
  api_key = Sys.getenv("GENDERAPI_API_KEY", ""),
  base_url = default_base_url,
  timeout = 10,
  user_agent = NULL,
  require_api_key_access = TRUE
)

Arguments

api_key	API key string. Defaults to the GENDERAPI_API_KEY environment variable. NULL or "" means no key (IP trial).
base_url	API base URL. Keep the default in production. HTTPS is required; ⁠http://⁠ is accepted only for localhost, ⁠127.0.0.1⁠ and ⁠[::1]⁠ so that tests can use a local fake server.
timeout	Total request timeout in seconds (default 10). A timed-out request is not retried and may still have been billed.
user_agent	Optional User-Agent header. Defaults to ⁠genderapi-r/<version>⁠.
require_api_key_access	TRUE (default) to raise a genderapi_access_mode_error when a key is set but a successful response reports an access mode other than "api_key". Applies to predictions, batches, usage and phone validation, never to genderapi_capabilities() or genderapi_error_catalog(). Has no effect without a key. See genderapi_error.

Details

Without a key (api_key is NULL or empty and GENDERAPI_API_KEY is unset) requests are sent without an Authorization header and the server applies its shared IP trial (10 credits per 24 hours per public IP). The package has no client-side trial logic; meta$access$mode in each response tells you which access mode the server used.

When a key is set, the package by default checks that each successful authenticated response reports meta$access$mode == "api_key". If the server answered through another mode (usually "ip_trial" because the key was not recognized), a genderapi_access_mode_error is raised. The request has already been processed and may have consumed IP-trial credits; the full result is in the error's result field. It is never retried. Set require_api_key_access = FALSE to return such responses normally.

Keep keys server-side. Never put a key in browser code, a URL, a log or a document shared with end users. Printing a client never shows the key.

Value

An object of class genderapi_client.

Examples

# No request is sent here.
client <- genderapi_client(api_key = NULL, timeout = 5)
client

genderapi documentation built on Oct. 1, 2026, 5:13 p.m.