GenderAPI.io V2 · Guia

Identificar o gênero por nomes indianos

Teste nomes usados na Índia com a GenderAPI.io V2. Preserve a grafia original, escolha o contexto de país IN de forma consciente e interprete corretamente as correspondências de nomes completos, os resultados da IA e os resultados desconhecidos.

Última atualização:

Teste a API V2

Analise um nome

Conjunto de dados + IA

Envie um valor e confira a resposta completa, incluindo resultados desconhecidos e créditos usados.

A ferramenta usa um contexto de país de exemplo: Índia (IN). Não é um padrão para todos os nomes deste idioma nem uma prova de nacionalidade.

Requisição padrão: 1 crédito, incluindo o fallback de IA e os resultados desconhecidos. Com a interpretação de apelidos: 1 crédito se o resultado vier do conjunto de dados, ou 2 no total se a IA for usada, mesmo quando o resultado for desconhecido.

O valor enviado (o nome) é transmitido à GenderAPI.io e pode ser repassado ao serviço de IA configurado se o fallback de IA for necessário. Saiba mais sobre o tratamento dos dados.

Nenhuma chave de API salva. Você pode usar o teste por IP compartilhado enquanto ele tiver créditos restantes.

A resposta abaixo é um exemplo ilustrativo. Clique em Analisar para enviar uma requisição.

Exemplo de resposta V2 · nenhum resultado em tempo real
Nome—
GêneroDesconhecido
Confiança—
FonteModelo de IA
Créditos usados1

As frequências, os valores e o saldo do exemplo mostram o formato da resposta. Os valores reais podem ser diferentes. Uma previsão não é uma identidade confirmada.

Usar o nome original sem presumir uma única escrita ou uma ordem fixa

A demonstração usa um exemplo em devanágari e o contexto de país IN. É um exemplo de entrada, e não uma definição de todos os nomes usados na Índia. A API aceita strings Unicode, então você pode enviar a grafia do cadastro da sua aplicação sem transliterá-la antes para o alfabeto latino.

A consulta usa partes normalizadas. Não há conversão geral entre escritas nem garantia de que uma grafia latina e uma grafia na escrita original levem à mesma entrada. Salve a entrada original junto com o nome retornado. O fato de uma escrita ser aceita não significa que exista uma precisão medida de forma independente para cada idioma ou comunidade.

Não presuma que a primeira ou a última parte sempre tem o mesmo papel. A V2 escolhe o candidato disponível com a maior contagem total armazenada e não garante uma posição fixa para o nome. Iniciais, partes curtas e entradas armazenadas ausentes podem deixar o resultado do conjunto de dados sem resposta; o fallback de IA pode interpretar o valor enviado inteiro.

Exemplo de entradaO que mostraO que verificar
प्रिया शर्माNome completo em devanágariVárias partes podem se tornar candidatas. Verifique o nome selecionado e a correspondência em vez de presumir que a primeira parte tem prioridade.
Priya SharmaExemplo no alfabeto latinoÉ uma grafia separada; não há garantia de correspondência idêntica entre escritas.
A. KumarInicial e outra parteUma inicial com uma única letra não se torna candidata no conjunto de dados. Uma correspondência com a outra parte não confirma o nome pretendido.
country: INContexto de exemplo: ÍndiaUse-o se o seu cadastro tiver um contexto de país relevante, e não apenas porque o nome aparece neste guia.

Escolher o contexto de país IN de forma consciente

A demonstração em tempo real envia country: IN (Índia). A API não escolhe esse país com base na escrita em que o nome está. Use um contexto de país conhecido e relevante na sua integração ou omita country. Não transforme este valor de exemplo em um padrão para todos os cadastros.

Para cada candidato, a consulta escolhe a entrada específica do país, se ela existir, e caso contrário a entrada global. Em seguida, é escolhido o candidato disponível com a maior contagem total armazenada. O escopo real da correspondência aparece em data.match.scope e data.match.country. Uma entrada específica do país com frequências empatadas não é substituída automaticamente pelo resultado global; se o fallback estiver ativado, a IA pode ser usada no lugar.

data.input.country descreve o contexto de país enviado na requisição. data.country e data.country_source descrevem a associação a um país retornada e a origem dela. São campos diferentes e não indicam nacionalidade, origem étnica nem residência.

Enviar uma requisição V2 com um nome da sua aplicação

Defina sua chave existente em GENDERAPI_API_KEY e execute o exemplo no seu servidor. A requisição ativa explicitamente o fallback de IA automático comum. Ela mostra como a requisição é montada, e não uma precisão medida ou uma cobertura confirmada. Defina options.ai_mode: off se quiser uma previsão que use apenas o conjunto de dados.

Escolha uma linguagem de programação. Configure sua chave de API, depois execute o exemplo no seu servidor.

Cada requisição de previsão é uma nova operação cobrada, inclusive as novas tentativas. Estes exemplos não fazem novas tentativas automaticamente. Verifique o status da cobrança antes de enviar outra requisição.

Antes de executar: acesso e tratamento de erros

Execute estes exemplos no seu servidor. Defina GENDERAPI_API_KEY no ambiente do processo com a sua chave de API existente. Confirme que meta.access.mode é api_key: uma chave não reconhecida pode levar ao teste por IP.

Respostas JSON com HTTP 4xx e 5xx preservam o corpo do erro e retornam um código de saída diferente de zero. Verifique code, action e meta.usage.billing_status antes de fazer uma nova tentativa.

Guia de erros e novas tentativas →
cURL
curl --silent --show-error --fail-with-body --max-time 30 \
  --request POST 'https://api.genderapi.io/api/v2/gender' \
  --header "Authorization: Bearer ${GENDERAPI_API_KEY:?Set GENDERAPI_API_KEY}" \
  --header 'Content-Type: application/json' \
  --data '{
  "type": "name",
  "value": "प्रिया शर्मा",
  "country": "IN",
  "options": {
    "ai_mode": "fallback"
  }
}'

cURL 7.76+ em um shell POSIX. Execute no seu terminal. Documentação do ambiente de execução

JavaScript / Node.js
// Server-side Node.js. Save as example.mjs.
const apiKey = process.env.GENDERAPI_API_KEY;
if (!apiKey) throw new Error("Set GENDERAPI_API_KEY");
const body = {
  "type": "name",
  "value": "प्रिया शर्मा",
  "country": "IN",
  "options": {
    "ai_mode": "fallback"
  }
};

const response = await fetch("https://api.genderapi.io/api/v2/gender", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(body),
  signal: AbortSignal.timeout(30_000),
  redirect: "error",
});
const raw = await response.text();
if (!(response.headers.get("content-type") ?? "").includes("json")) {
  throw new Error(`HTTP ${response.status}: expected JSON; request ID ${response.headers.get("x-request-id")}`);
}
const result = JSON.parse(raw); // Also accepts application/problem+json.
if (!response.ok) {
  console.error(`HTTP ${response.status}`, result);
  process.exitCode = 1; // A retry is a new operation; inspect billing first.
} else {
  console.log(JSON.stringify(result, null, 2));
  // For batches, inspect every item: HTTP 200 may contain item errors.
}

Node.js 22+; fetch nativo. Salve como example.mjs e execute node example.mjs. Documentação do ambiente de execução

Python
import json
import os
import sys
import urllib.error
import urllib.request

api_key = os.environ.get("GENDERAPI_API_KEY")
if not api_key:
    raise RuntimeError("Set GENDERAPI_API_KEY")
body = json.loads("{\"type\":\"name\",\"value\":\"प्रिया शर्मा\",\"country\":\"IN\",\"options\":{\"ai_mode\":\"fallback\"}}")

class NoRedirect(urllib.request.HTTPRedirectHandler):
    def redirect_request(self, req, fp, code, msg, headers, newurl):
        return None

request = urllib.request.Request(
    "https://api.genderapi.io/api/v2/gender",
    method="POST",
    data=json.dumps(body).encode("utf-8"),
    headers={
        "Authorization": "Bearer " + api_key,
        "Content-Type": "application/json",
    },
)
opener = urllib.request.build_opener(NoRedirect())
try:
    response = opener.open(request, timeout=30)
except urllib.error.HTTPError as error:
    response = error  # Keep the Problem Details body on non-2xx responses.
with response:
    status = response.status
    raw = response.read().decode("utf-8")
    if "json" not in response.headers.get("Content-Type", ""):
        raise RuntimeError(f"HTTP {status}: expected a JSON response")
    result = json.loads(raw)
print(json.dumps(result, indent=2), file=sys.stderr if status >= 300 else sys.stdout)
if not 200 <= status < 300:
    sys.exit(1)  # Inspect code, action and billing before retrying.
# For batches, inspect every item even when HTTP status is 200.

Python 3.10+; biblioteca padrão. Salve como example.py e execute python3 example.py. Documentação do ambiente de execução

PHP
<?php
$apiKey = getenv('GENDERAPI_API_KEY');
if (!$apiKey) {
    throw new RuntimeException('Set GENDERAPI_API_KEY');
}
$body = json_decode('{"type":"name","value":"प्रिया शर्मा","country":"IN","options":{"ai_mode":"fallback"}}', true, 512, JSON_THROW_ON_ERROR);

$ch = curl_init('https://api.genderapi.io/api/v2/gender');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_FOLLOWLOCATION => false,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode($body, JSON_THROW_ON_ERROR),
]);
$raw = curl_exec($ch);
if ($raw === false) {
    throw new RuntimeException(curl_error($ch));
}
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
$contentType = curl_getinfo($ch, CURLINFO_CONTENT_TYPE) ?: '';
curl_close($ch);
if (strpos($contentType, 'json') === false) {
    throw new RuntimeException("HTTP $status: expected a JSON response");
}
$result = json_decode($raw, true, 512, JSON_THROW_ON_ERROR);
$output = json_encode($result, JSON_PRETTY_PRINT | JSON_THROW_ON_ERROR) . PHP_EOL;
if ($status < 200 || $status >= 300) {
    fwrite(STDERR, $output); // Preserve the Problem Details body.
    exit(1);
}
echo $output;
// For batches, inspect every item; HTTP 200 can contain item errors.

PHP 8+ com a extensão cURL. Salve como example.php e execute php example.php. Documentação do ambiente de execução

Java
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;
import java.time.Duration;

public class GenderApiExample {
    private static String requiredEnv(String name) {
        String value = System.getenv(name);
        if (value == null || value.isBlank()) throw new IllegalStateException("Set " + name);
        return value;
    }

    public static void main(String[] args) throws Exception {
        String apiKey = requiredEnv("GENDERAPI_API_KEY");
        String body = "{\"type\":\"name\",\"value\":\"प्रिया शर्मा\",\"country\":\"IN\",\"options\":{\"ai_mode\":\"fallback\"}}";
        HttpClient client = HttpClient.newBuilder()
            .connectTimeout(Duration.ofSeconds(10))
            .followRedirects(HttpClient.Redirect.NEVER)
            .build();
        HttpRequest request = HttpRequest.newBuilder(URI.create("https://api.genderapi.io/api/v2/gender"))
            .timeout(Duration.ofSeconds(30))
            .header("Authorization", "Bearer " + apiKey)
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(body, StandardCharsets.UTF_8))
            .build();
        HttpResponse<String> response = client.send(request,
            HttpResponse.BodyHandlers.ofString(StandardCharsets.UTF_8));
        if (!response.headers().firstValue("content-type").orElse("").contains("json")) {
            throw new IllegalStateException("HTTP " + response.statusCode() + ": expected JSON");
        }
        // JSON text; parse with your application's JSON library when integrating.
        if (response.statusCode() < 200 || response.statusCode() >= 300) {
            System.err.println(response.body()); // Includes Problem Details.
            System.exit(1);
        }
        System.out.println(response.body());
        // For batches, inspect each item's data or error, including on HTTP 200.
    }
}

Java 17+; cliente HTTP padrão. Salve como GenderApiExample.java e execute java GenderApiExample.java. Documentação do ambiente de execução

C# / .NET
using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Text.Json;

string RequiredEnv(string name) =>
    !string.IsNullOrWhiteSpace(Environment.GetEnvironmentVariable(name))
        ? Environment.GetEnvironmentVariable(name)!
        : throw new InvalidOperationException($"Set {name}");

var apiKey = RequiredEnv("GENDERAPI_API_KEY");
using var handler = new HttpClientHandler { AllowAutoRedirect = false };
using var client = new HttpClient(handler) { Timeout = TimeSpan.FromSeconds(30) };
using var request = new HttpRequestMessage(HttpMethod.Post, "https://api.genderapi.io/api/v2/gender");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", apiKey);
request.Content = new StringContent("{\"type\":\"name\",\"value\":\"प्रिया शर्मा\",\"country\":\"IN\",\"options\":{\"ai_mode\":\"fallback\"}}", Encoding.UTF8, "application/json");

using var response = await client.SendAsync(request);
var raw = await response.Content.ReadAsStringAsync();
if (!(response.Content.Headers.ContentType?.MediaType?.Contains("json") ?? false))
    throw new InvalidOperationException($"HTTP {(int)response.StatusCode}: expected JSON");
using var result = JsonDocument.Parse(raw);
if (!response.IsSuccessStatusCode)
{
    Console.Error.WriteLine(result.RootElement); // Preserve Problem Details.
    Environment.ExitCode = 1;
}
else
{
    Console.WriteLine(result.RootElement);
    // For batches, inspect every item even on HTTP 200.
}

Aplicação de console .NET 8+. Use como Program.cs em um projeto de console e depois execute dotnet run. Documentação do ambiente de execução

Go
package main

import (
    "encoding/json"
    "fmt"
    "io"
    "net/http"
    "os"
    "strings"
    "time"
)

func requiredEnv(name string) string {
    value := os.Getenv(name)
    if value == "" { panic("Set " + name) }
    return value
}

func run() error {
    apiKey := requiredEnv("GENDERAPI_API_KEY")
    body := "{\"type\":\"name\",\"value\":\"प्रिया शर्मा\",\"country\":\"IN\",\"options\":{\"ai_mode\":\"fallback\"}}"
    request, err := http.NewRequest("POST", "https://api.genderapi.io/api/v2/gender", strings.NewReader(body))
    if err != nil { return err }
    request.Header.Set("Authorization", "Bearer " + apiKey)
    request.Header.Set("Content-Type", "application/json")
    client := &http.Client{
        Timeout: 30 * time.Second,
        CheckRedirect: func(req *http.Request, via []*http.Request) error {
            return http.ErrUseLastResponse
        },
    }
    response, err := client.Do(request)
    if err != nil { return err }
    defer response.Body.Close()
    raw, err := io.ReadAll(response.Body)
    if err != nil { return err }
    if !strings.Contains(response.Header.Get("Content-Type"), "json") || !json.Valid(raw) {
        return fmt.Errorf("HTTP %d: expected a JSON response", response.StatusCode)
    }
    if response.StatusCode < 200 || response.StatusCode >= 300 {
        return fmt.Errorf("HTTP %d: %s", response.StatusCode, raw)
    }
    fmt.Println(string(raw))
    // For batches, inspect every item even on HTTP 200.
    return nil
}

func main() {
    if err := run(); err != nil {
        fmt.Fprintln(os.Stderr, err) // Keep Problem Details for error handling.
        os.Exit(1)
    }
}

Go 1.22+; biblioteca padrão. Salve como main.go e execute go run main.go. Documentação do ambiente de execução

Salvar o resultado junto com as evidências

Uma associação inferida não é o gênero declarado por uma pessoa. Salve separadamente a entrada original, as evidências retornadas e o que a pessoa declarou. Um resultado desconhecido é um resultado válido e não deve se transformar em uma categoria adivinhada na sua aplicação.

CampoUso
data.gender / data.result_statusUse male ou female somente com identified. Em um resultado desconhecido, preserve o valor null nativo do JSON.
data.name / data.matchVerifique o nome retornado e o candidato selecionado. Uma correspondência com uma substring não comprova que a entrada pertence a uma pessoa com esse nome.
data.confidence / data.confidence_kindA confiança está em uma escala de 0 a 1 ou é null. observed_frequency se baseia em frequências armazenadas; model_reported é um valor fornecido pela IA. Avalie os limites separadamente para cada tipo.
data.source / data.sample_countDiferencie dataset, ai e none. Resultados da IA não têm um tamanho de amostra armazenado. Um tamanho de amostra não é um valor de precisão medido.
meta.access.modeEm uma integração com conta, verifique se o valor informado é api_key. Chaves ausentes ou não reconhecidas podem usar o teste por IP compartilhado.
meta.usageLeia charged_credits e billing_status. Um resultado desconhecido bem-sucedido é cobrado. Uma resposta perdida não comprova que a requisição foi gratuita.

Decidir quando usar a IA

forceToGenderize é opcional para nomes, endereços de e-mail e nomes de usuário. Quando ativado, omita ai_mode ou use fallback; off e always não podem ser combinados com essa opção e retornam 422. Um saldo inicial positivo basta para iniciar uma requisição, mesmo que a cobrança final deixe o saldo negativo.

O modo de apelidos pode retornar um gênero junto com name: null. Ele também pode dar um resultado desconhecido. Nem o fallback de IA comum nem a interpretação de apelidos garantem uma resposta correta ou um valor diferente de null.

Opção da requisiçãoComportamentoCréditos por consulta bem-sucedida
options.ai_mode: offUsa apenas o conjunto de dados.1, inclusive para um resultado desconhecido
options.ai_mode: fallbackConsulta primeiro o conjunto de dados e depois usa a IA comum se nenhum gênero for retornado. É o padrão das requisições individuais.1 no total, incluindo o fallback de IA
options.ai_mode: alwaysUsa a IA diretamente.2
forceToGenderize: trueConsulta primeiro o conjunto de dados e depois deixa a IA interpretar um apelido pessoal ou um alias, mesmo sem um nome próprio real.1 para um resultado encontrado no conjunto de dados; 2 no total se a IA for usada

Processar uma lista de nomes sem perder o contexto

Envie até 50 itens com uma chave de API ou 10 com o teste por IP via POST /api/v2/gender/batch. Dê a cada item um id único e preserve o valor original de cada linha. Cada item pode ter as próprias opções de país e de IA; omita o país se ele não for conhecido.

Ao contrário das requisições individuais, que usam fallback por padrão, os itens de um lote usam apenas o conjunto de dados por padrão. Defina options.ai_mode: fallback em cada item que precisar da IA. Verifique cada resultado, mesmo depois de HTTP 200, salve os resultados desconhecidos e verifique os erros e a cobrança antes de reenviar. Cada item comum bem-sucedido custa 1 crédito; uma requisição HTTP com um lote não equivale a um crédito por previsão.

Saber o que você envia

A demonstração em tempo real envia o valor digitado à GenderAPI.io somente quando você o envia. Se a IA for usada, type, value e o contexto de país enviados são transmitidos ao serviço configurado para as previsões. Para uma previsão baseada apenas no conjunto de dados, defina options.ai_mode: off sem forceToGenderize na sua integração.

A política de privacidade, o acordo de processamento de dados e a lista de suboperadores descrevem as condições de tratamento publicadas. Um resultado é uma associação inferida, e o que uma pessoa declara tem prioridade. Não o use como base para decisões com consequências relevantes para uma pessoa.

Perguntas frequentes

A demonstração de nomes indianos aceita apenas nomes em hindi?

A demonstração usa um exemplo em devanágari, mas a API aceita nomes como strings Unicode. Isso não significa que o conjunto de dados tenha cobertura completa nem que exista uma precisão medida para cada idioma da Índia.

A grafia latina dá o mesmo resultado que a escrita original?

Não há garantia. A consulta atual não trata transliterações como equivalentes de forma geral. Salve cada grafia enviada junto com os dados de source, match e confidence retornados.

Existe uma avaliação independente de precisão publicada para este grupo de nomes?

Esta página não publica uma avaliação desse tipo. O fato de a entrada ser aceita, de frequências armazenadas serem exibidas ou de um valor de confiança ser retornado não é uma medição independente de precisão. A descrição da metodologia explica quais dados estão disponíveis e quais medições ainda não foram publicadas.

Um resultado sem previsão consome créditos?

Um resultado desconhecido bem-sucedido é cobrado. O modo comum, apenas com o conjunto de dados ou com fallback, custa 1 crédito no total. Com forceToGenderize, a requisição custa 1 crédito se o resultado vier do conjunto de dados ou 2 no total se a IA for usada, inclusive para um resultado desconhecido. Os erros seguem regras de cobrança separadas; verifique meta.usage.

Continue testando

Use sua chave da GenderAPI

Cole a chave de API da sua conta GenderAPI para continuar os testes quando os créditos compartilhados do teste por IP de 24 horas acabarem. Salvar a chave não envia nenhuma consulta; envie a consulta novamente quando quiser.

Armazenada somente nesta aba do navegador e apagada quando a aba é fechada.