GenderAPI.io V2: Official SDKs

Choose a package

Official open-source SDKs call the same v2 API described in these guides. Version 2.x of each package uses API v2. Install the 2.x line for new projects.

Registry notes

• Java: add https://jitpack.io to your repositories. The same release is also published to GitHub Packages as io.genderapi:genderapi, which requires a GitHub token with read:packages.
• R: CRAN still serves the 1.x package while version 2.0.0 is under CRAN review. Install 2.0.0 from the GitHub tag until CRAN publishes it.
• JavaScript: the package is for server-side runtimes. Do not use it in browser code, because that would expose your API key.

Shared behavior

• Each client reads the API key from GENDERAPI_API_KEY or accepts it in the constructor. Keep the key on your server.
• Without an API key, requests use the shared IP trial: 10 credits per IP address per 24 hours.
• Importing a package or creating a client sends no request. Each method call sends exactly one request.
• No SDK retries a request automatically. A retry is a new operation with normal billing, so check the error and billing status first.
• The SDKs do not follow redirects, and the default timeout is 10 seconds.
• An unknown result is a successful response: gender is null and the request is billed normally.
• Errors expose the HTTP status, error code, request ID and, when present, the Retry-After value.

• Authentication and trial access
• Credits and usage
• Errors and retries

Quick start examples

Each example sends one name prediction and costs 1 credit. Set GENDERAPI_API_KEY in the server environment first. Each repository README covers batch requests, usage checks and error handling.

from genderapi import GenderAPI

client = GenderAPI()  # reads GENDERAPI_API_KEY
result = client.name("Alice", country="US")
print(result.data.gender, result.data.result_status)
print(result.meta.usage.charged_credits)

import { GenderAPI } from "genderapi";

const client = new GenderAPI(); // reads GENDERAPI_API_KEY
const { data, meta } = await client.name("Andrea", { country: "IT" });
console.log(data.gender, data.result_status, meta.usage.charged_credits);

<?php
require __DIR__ . '/vendor/autoload.php';

use GenderApi\Client;

$client = new Client(); // reads GENDERAPI_API_KEY
$result = $client->name('James', country: 'US');
echo $result->data->gender ?? 'unknown', ' ', $result->meta->usage->chargedCredits, "\n";

require "genderapi"

client = GenderAPI::Client.new # reads ENV["GENDERAPI_API_KEY"]
result = client.name("Andrea", country: "IT")
puts result.data.gender, result.usage.charged_credits

import io.genderapi.GenderApiClient;
import io.genderapi.model.GenderResponse;

GenderApiClient client = new GenderApiClient(); // reads GENDERAPI_API_KEY
GenderResponse response = client.name("Andrea", "IT");
System.out.println(response.getData().getGender());
System.out.println(response.getMeta().getUsage().getChargedCredits());

library(genderapi)

res <- genderapi_name("Sophia", country = "US")  # reads GENDERAPI_API_KEY
res$data$gender
res$meta$usage$charged_credits

using GenderApi;

using var client = new GenderApiClient(); // reads GENDERAPI_API_KEY
GenderResponse res = await client.NameAsync("Alice", country: "US");
Console.WriteLine(res.Data!.Gender ?? "unknown");
Console.WriteLine(res.Meta!.Usage!.ChargedCredits);

Keep a v1 integration on 1.x

Version 1.x packages remain available for existing v1 integrations and are not deprecated. Pin the major version so an update does not install 2.x, then migrate each integration when you are ready.

• Migrate from v1
• Version 1.x client libraries

Source code and issues

Each SDK is open source. Report bugs or request features in the matching GitHub repository.

• Python SDK on GitHub
• JavaScript SDK on GitHub
• PHP SDK on GitHub
• Ruby SDK on GitHub
• Java SDK on GitHub
• R SDK on GitHub
• C# SDK on GitHub