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 entrada | O que mostra | O que verificar |
|---|---|---|
प्रिया शर्मा | Nome completo em devanágari | Vá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 Sharma | Exemplo no alfabeto latino | É uma grafia separada; não há garantia de correspondência idêntica entre escritas. |
A. Kumar | Inicial e outra parte | Uma 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: IN | Contexto de exemplo: Índia | Use-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 7.76+ em um shell POSIX. Execute no seu terminal. Documentação do ambiente de execução
Node.js 22+; fetch nativo. Salve como example.mjs e execute node example.mjs. Documentação do ambiente de execução
Python 3.10+; biblioteca padrão. Salve como example.py e execute python3 example.py. Documentação do ambiente de execução
PHP 8+ com a extensão cURL. Salve como example.php e execute php example.php. Documentação do ambiente de execução
Java 17+; cliente HTTP padrão. Salve como GenderApiExample.java e execute java GenderApiExample.java. Documentação do ambiente de execução
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 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.
| Campo | Uso |
|---|---|
data.gender / data.result_status | Use male ou female somente com identified. Em um resultado desconhecido, preserve o valor null nativo do JSON. |
data.name / data.match | Verifique 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_kind | A 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_count | Diferencie 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.mode | Em 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.usage | Leia 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ção | Comportamento | Créditos por consulta bem-sucedida |
|---|---|---|
| options.ai_mode: off | Usa apenas o conjunto de dados. | 1, inclusive para um resultado desconhecido |
| options.ai_mode: fallback | Consulta 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: always | Usa a IA diretamente. | 2 |
| forceToGenderize: true | Consulta 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.