Package {genderapi}

genderapi: Official 'GenderAPI.io' V2 Client

Description

Server-side R client for the 'GenderAPI.io' V2 API (⁠https://api.genderapi.io/api/v2⁠). It infers gender from names, email addresses and usernames, runs batches of up to 50 items, reads the free usage endpoint and validates phone numbers.

Details

Results are inferences, not verified identity, and can be unknown (gender is NULL). confidence is returned exactly as the API sends it and is not a calibrated probability; read it together with confidence_kind.

Safety rules

• Every prediction or phone request is sent exactly once. The package never retries automatically, not even after HTTP 429, a timeout or a lost response: a request whose response was lost may still have been billed.

• Redirects are never followed, so the API key is never forwarded to another host. A 3xx response raises a genderapi_redirect_error.

• The default timeout is 10 seconds (see genderapi_client()).

• The base URL must use HTTPS; plain HTTP is accepted only for localhost, ⁠127.0.0.1⁠ and ⁠[::1]⁠ (local tests).

• Loading the package or creating a client never sends a request.

• The API key is sent only in the Authorization: Bearer header, never in a URL, and is never printed. Keep keys on the server; never embed them in browser code or in documents shared with end users.

API key and IP trial

The key is taken from the api_key argument of genderapi_client() or from the GENDERAPI_API_KEY environment variable. Without a key the server applies its shared IP trial (10 credits per 24 hours for all clients behind the same public IP); the package does not implement any trial logic itself. Check meta$access$mode in every response.

Author(s)

Maintainer: Onur Ozturk onurozturk1980@gmail.com

See Also

https://www.genderapi.io/api-documentation, https://www.genderapi.io/docs/v2/responses, https://www.genderapi.io/docs/v2/errors-and-retries

Convert GenderAPI results to a data frame

Description

Flattens a prediction (one row) or a batch (one row per item, in submission order) into a data frame. JSON null becomes NA. confidence is copied unchanged; it is not converted into a percentage or probability. The original list keeps every field, including fields not shown here.

Usage

## S3 method for class 'genderapi_prediction'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

## S3 method for class 'genderapi_batch'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

Arguments

Details

Columns: index, id, charged_credits (batch only), input_type, input_value, gender, result_status, reason, confidence, confidence_kind, sample_count, source, name, country, country_source, match_name, match_method, match_scope, match_country, and for batches error_status, error_code, error_detail.

Value

A data frame.

Examples

res <- structure(
  list(data = list(gender = NULL, result_status = "unknown",
                   reason = "not_found", confidence = NULL,
                   confidence_kind = NULL, source = "none"),
       meta = list()),
  class = c("genderapi_prediction", "genderapi_response")
)
as.data.frame(res)

Defunct V1 functions

Description

The V1 functions of genderapi 1.x were removed in 2.0.0 because the V2 API uses different routes, request fields and responses. Calling one of them raises an error that names the replacement:

Usage

get_gender_by_name(...)

get_gender_by_email(...)

get_gender_by_username(...)

get_gender_by_name_bulk(...)

get_gender_by_email_bulk(...)

get_gender_by_username_bulk(...)

Arguments

Details

genderapi 1.x (V1 API) stays available and installable indefinitely; no deprecation or shutdown is planned. To keep using it, install 1.x with remotes::install_version("genderapi", "1.0.3"). The source stays on the v1 branch of the repository.

Infer gender for a batch of 1 to 50 items

Description

Sends one POST /gender/batch request with ⁠{"items": [...]}⁠. Batch items default to ai_mode = "off" on the server. The server decides the limit (50 items; 10 on the IP trial). Larger jobs must be split by the caller; the package never retries or splits automatically.

Usage

genderapi_batch(items, client = genderapi_client())

Arguments

Details

A partially successful batch is returned normally (HTTP 200): inspect every item. Each item has index, the optional id, charged_credits and exactly one of data (a prediction) or error (a problem with code). meta$summary has total, succeeded, identified, unknown and failed. When every executed item fails the API answers with an error status; the resulting genderapi_http_error keeps the item array in data.

Retry only failed items, and only once billing is confirmed: resubmitting successful items charges them again.

Value

A genderapi_batch: the parsed V2 JSON with data (the item list) and meta (including summary and usage). Use as.data.frame() for one row per item and genderapi_failed() for the failed items.

Examples

items <- list(
  genderapi_item("name", "Onur", country = "TR", id = "a"),
  genderapi_item("email", "alex@example.com", id = "b")
)
## Not run: 
# Sends a request and may consume credits.
res <- genderapi_batch(items)
res$meta$summary
as.data.frame(res)
genderapi_failed(res)

## End(Not run)

Read API capabilities and the error catalog

Description

genderapi_capabilities() sends ⁠GET /⁠ (deployment version, limits and AI availability). genderapi_error_catalog() sends GET /errors, the public catalog of stable error codes, HTTP statuses and recommended actions. Both are unauthenticated: no API key is sent.

Usage

genderapi_capabilities(client = genderapi_client())

genderapi_error_catalog(client = genderapi_client())

Arguments

Value

The parsed JSON object as a list of class genderapi_response.

Examples

## Not run: 
genderapi_capabilities()
catalog <- genderapi_error_catalog()

## End(Not run)

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

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 error conditions

Description

All errors raised by this package inherit from genderapi_error, so they can be caught with tryCatch(..., genderapi_error = function(e) ...). More specific classes:

Details

• genderapi_validation_error: the input failed a client-side check. No request was sent and nothing was billed.

• genderapi_http_error: the API answered with HTTP 400 or higher. Fields: status, code, title, detail, action, errors (validation pointers), documentation, request_id (from the body, meta$request_id or the X-Request-ID header), retry_after (the Retry-After header as a string), billing_status, usage (meta$usage), meta, data (the item array of an all-failed batch), body (parsed JSON or NULL), raw (the response text) and headers.

• genderapi_redirect_error: the API answered with a 3xx redirect. It was not followed, so the key was not forwarded. Fields: status, location, headers.

• genderapi_transport_error: no usable response (network error or timeout). code is "timeout" or "transport_error". The request may still have been processed and billed.

• genderapi_response_error: a 2xx response that is not a JSON object. code is "invalid_response".

• genderapi_access_mode_error: an API key is set but a successful response reports an access mode other than "api_key" in meta$access$mode (usually "ip_trial", because the key was not recognized). code is "unexpected_access_mode". The request has already been processed and may have consumed IP-trial credits; it is not retried. Fields: access_mode, access_reason, result (the complete parsed result the function would have returned, including meta$usage), status and request_id. Disable the check with genderapi_client(require_api_key_access = FALSE).

The package never retries. After a 429 wait for retry_after seconds; the next request is a new, billable operation. When billing_status is "unconfirmed" or action is "contact_support", contact support with request_id before sending the request again. Match on code, never on the human-readable detail. See genderapi_error_catalog().

Error bodies can contain the submitted input. Do not log them wholesale.

Examples

client <- genderapi_client(api_key = NULL)
e <- tryCatch(genderapi_name("", client = client), genderapi_error = function(e) e)
class(e)
conditionMessage(e)

Failed items of a batch

Description

Returns the items that carry an error instead of data. Works on a genderapi_batch (partial success) and on the genderapi_http_error raised when every executed item failed. Retry failed items only after billing is confirmed, and never resubmit successful items: they would be charged again.

Usage

genderapi_failed(x)

Arguments

Value

A list of items, each with index, optional id, charged_credits and error (a problem with code, status, detail and action). An empty list when nothing failed.

Examples

res <- structure(
  list(data = list(
    list(index = 0L, id = "a", charged_credits = 1L,
         data = list(gender = "male", result_status = "identified")),
    list(index = 1L, id = "b", charged_credits = 0L,
         error = list(code = "ai_upstream_error", status = 502L))
  ), meta = list()),
  class = c("genderapi_batch", "genderapi_response")
)
genderapi_failed(res)

Infer gender for one name, email address or username

Description

Sends one POST /gender request (one billable operation). The request is never retried. A successful unknown result is billable and is returned, not raised as an error.

Usage

genderapi_gender(
  type,
  value,
  country = NULL,
  ai_mode = NULL,
  force_to_genderize = FALSE,
  id = NULL,
  client = genderapi_client()
)

genderapi_name(
  value,
  country = NULL,
  ai_mode = NULL,
  force_to_genderize = FALSE,
  id = NULL,
  client = genderapi_client()
)

genderapi_email(
  value,
  country = NULL,
  ai_mode = NULL,
  force_to_genderize = FALSE,
  id = NULL,
  client = genderapi_client()
)

genderapi_username(
  value,
  country = NULL,
  ai_mode = NULL,
  force_to_genderize = FALSE,
  id = NULL,
  client = genderapi_client()
)

Arguments

Details

genderapi_name(), genderapi_email() and genderapi_username() are shortcuts for genderapi_gender() with the matching type.

Value

A genderapi_prediction: the parsed V2 JSON as a list with data (the prediction) and meta (request_id, duration_ms, access, usage). All fields are kept as sent, including fields added by future API versions. JSON null becomes NULL. Key fields of data: gender ("male", "female" or NULL), result_status ("identified" or "unknown"), reason, confidence with confidence_kind ("observed_frequency" or "model_reported"; not a calibrated probability), sample_count, source, name, country, country_source and match. Use as.data.frame() for a one-row data frame.

See Also

genderapi_batch(), genderapi_error

Examples

## Not run: 
# Sends a request and may consume credits.
res <- genderapi_name("Onur", country = "TR")
res$data$gender
res$data$result_status
res$meta$usage$charged_credits
as.data.frame(res)

## End(Not run)

Build one prediction item

Description

Validates the input with the cheap, certain rules of the V2 schema and returns the exact wire object (type, value, country, id, forceToGenderize, options$ai_mode). Invalid input raises a genderapi_validation_error; no request is sent. The API performs the authoritative checks (email syntax, country membership, trial limits).

Usage

genderapi_item(
  type,
  value,
  country = NULL,
  ai_mode = NULL,
  force_to_genderize = FALSE,
  id = NULL
)

Arguments

Value

A list of class genderapi_item.

Examples

genderapi_item("name", "Onur", country = "TR", ai_mode = "off", id = "row-1")

Read credit usage (free)

Description

Sends GET /usage. This read is not billed. data holds remaining_credits (can be negative or NULL), expires_at, and for the IP trial resets_at, limit and period_seconds; meta$access$mode shows whether the key or the IP trial was used.

Usage

genderapi_usage(client = genderapi_client())

Arguments

Value

A genderapi_usage list with data and meta.

Examples

## Not run: 
u <- genderapi_usage()
u$data$remaining_credits
u$meta$access$mode

## End(Not run)

Validate a phone number

Description

Sends one POST /phone/validate request. It costs 1 credit, including for invalid numbers, and is never retried.

Usage

genderapi_validate_phone(number, country = NULL, client = genderapi_client())

Arguments

Value

A genderapi_phone list. data has valid, possible, e164, country and country_calling_code.

Examples

## Not run: 
genderapi_validate_phone("+90 212 555 01 01")$data$valid

## End(Not run)