# Fontes de dados e levantamento na GenderAPI.io V2

> Conheça as fontes das respostas da V2, o levantamento datado do banco de dados, as verificações de consistência em amostras e os limites da documentação de fontes publicada.

Canonical HTML: https://www.genderapi.io/pt/data-provenance

Last reviewed: 2026-09-29

## O que source significa na V2?

O campo source indica qual caminho gerou o resultado final: a consulta ao conjunto de dados armazenado, uma previsão da IA ou nenhuma fonte selecionada. Ele não é uma referência ao editor original de um registro, não é uma prova de licença e não garante que a previsão esteja correta.

Este guia descreve o contrato de resposta atual da V2 e um perfil do banco de dados elaborado pela própria GenderAPI.io. As observações abaixo são levantamentos e verificações de consistência; um catálogo verificado das fontes originais e uma avaliação independente de precisão ainda não foram publicados.

| source | Significado | O que não mostra |
| --- | --- | --- |
| `dataset` | Um registro armazenado foi selecionado; com frequências exatamente empatadas, o gênero ainda pode ser desconhecido | O editor original, o método de coleta, a licença, a idade do registro ou a independência das observações |
| `ai` | A resposta final vem do caminho de previsão com IA configurado; gender ainda pode ser null | Uma amostra contada, uma referência ao conjunto de dados ou uma precisão calibrada da previsão |
| `none` | No modo que usa apenas o conjunto de dados, nenhum registro armazenado foi selecionado para o resultado final | Que a entrada não tenha uma possível associação a um nome em alguma população ou idioma |

## Perfil do banco de dados: 26 de setembro de 2026

Os metadados das coleções foram lidos em 2026-09-26T15:28:18.227Z, e as amostras aleatórias foram extraídas em 2026-09-26T15:31:54.045Z. As duas contagens de documentos vêm, cada uma, dos metadados collStats do MongoDB para a coleção correspondente, e não de uma contagem completa separada. A coleção geral contém registros de nomes, e a coleção específica por país contém combinações de nome e país. Não some os dois números para obter um total de nomes únicos ou de pessoas únicas.

Para cada coleção, o MongoDB selecionou aleatoriamente 5.000 documentos e calculou no servidor do banco de dados as verificações agregadas abaixo. O relatório público não contém nomes nem dados brutos. São observações feitas pela GenderAPI.io no banco de dados de produção, não uma auditoria independente nem um conjunto de dados de avaliação congelado. As verificações tratam da consistência dos contadores, e não da precisão das previsões, do número de pessoas ou nomes únicos ou da cobertura da API.

| Observação | Registros gerais | Registros específicos por país |
| --- | --- | --- |
| Coleção | general | country-specific |
| Número de documentos segundo os metadados | 2.483.220 | 4.080.692 |
| Chave única armazenada | name | name + country |
| Documentos selecionados aleatoriamente | 5.000 | 5.000 |
| Verificações numéricas com falha na amostra | 0 | 0 |
| male + female diferente de total na amostra | 0 | 0 |
| Frequências iguais para male e female na amostra | 124 | 94 |
| Campo updated_at presente na amostra | 667 / 5.000 | 741 / 5.000 |

- [Baixar o perfil agregado datado (JSON)](https://www.genderapi.io/data-evidence/v2-dataset-profile.json)

## O que as verificações do banco de dados mostram

A verificação numérica exige que total seja um inteiro seguro positivo e que as frequências male e female sejam finitas e fiquem entre zero e total. Uma verificação separada compara male + female com total. Todos os contadores das amostras passaram nas verificações; isso não significa que todos os registros das coleções sejam consistentes nem que uma previsão esteja correta.

Frequências iguais para male e female foram encontradas em 124 registros da amostra da coleção geral e em 94 registros da amostra da coleção específica por país. Trata-se de frequências armazenadas iguais, e não de identidades ambíguas verificadas de forma independente nem de uma taxa de resultados desconhecidos da API. Os resultados reais da API dependem da entrada, da disponibilidade do Redis, da seleção de candidatos e das opções de IA.

Um levantamento separado do campo country na coleção geral, feito em 2026-09-26T15:33:13.811Z, encontrou 244 valores armazenados distintos: 239 no formato de duas letras maiúsculas e 5 em outro formato. A conformidade com a ISO, a distribuição de registros por país e a cobertura dos países compatíveis não foram medidas. Esses números não são o número de países compatíveis.

Em nenhuma das amostras foram encontrados campos de fonte ou de licença. Isso não prova que as informações sobre a origem estejam ausentes em cada registro ou em sistemas externos: a presença ou ausência de um campo não prova nada sobre a licença de uma fonte. O campo updated_at estava presente em alguns registros como um valor numérico, mas os valores e o significado deles não foram verificados; isso não indica o quanto os dados estão atualizados nem um plano de atualização.

A V2 faz as consultas ao conjunto de dados pelo Redis. Em 26 de setembro de 2026, a GenderAPI.io, como administradora do sistema, confirmou que o MongoDB e o Redis contêm o mesmo conjunto de dados. A equivalência se baseia nessa confirmação: não foi feita uma comparação independente dos dois bancos de dados, e essa verificação ainda está pendente. O levantamento acima descreve os registros armazenados; a cobertura das respostas da API depende também da entrada enviada, da correspondência dos candidatos e das opções de IA. As amostras foram extraídas sem seed fixa, lidas sem snapshot congelado e processadas sem rótulos de referência independentes; elas não podem medir a precisão das previsões, a calibração nem a cobertura das respostas.

- [Como medir precisão e cobertura](https://www.genderapi.io/pt/accuracy-methodology)

## Acompanhar as evidências na resposta

| Campo | Significado | Limitação |
| --- | --- | --- |
| `input` | Repete o tipo, o valor e o contexto de país enviados | Um valor de entrada não é uma informação de identidade verificada de forma independente |
| `match.name / match.method` | Mostra o candidato selecionado e se ele foi normalizado, extraído como parte ou substring ou previsto pelo modelo | Uma correspondência com uma parte não garante que um primeiro nome real tenha sido extraído do nome completo ou do nome de usuário |
| `match.scope / match.country` | Mostra se o registro selecionado vem da consulta específica do país ou da consulta global | Um país informado não garante que havia um registro específico desse país disponível |
| `sample_count` | A contagem total armazenada no registro selecionado; null em uma previsão da IA | Não representa necessariamente pessoas únicas, observações coletadas de forma independente ou o tamanho da amostra de uma avaliação de precisão |
| `confidence / confidence_kind` | Diferencia uma razão calculada a partir de frequências armazenadas de um valor informado pelo modelo | Nenhum dos valores é uma probabilidade verificada da identidade de gênero de uma pessoa |
| `country / country_source` | Metadados de país do registro retornado ou uma associação entre o nome e um país informada pela IA, se houver | Não indica nacionalidade, residência nem uma origem verificada e não prova que o país enviado teve correspondência |

- [Documentação completa da resposta da V2](https://www.genderapi.io/pt/docs/v2/responses)

## Como a correspondência da entrada afeta o resultado

A consulta ao conjunto de dados normaliza o texto e extrai candidatos dele. Para endereços de e-mail, os candidatos vêm da parte antes do @; para nomes de usuário, um @ inicial opcional é removido. As consultas comuns de endereços de e-mail e nomes de usuário também podem verificar substrings limitadas. Se houver vários registros candidatos, é escolhido o registro com a maior contagem total armazenada. Ele pode ser uma parte diferente do primeiro nome pretendido.

Se um contexto de país for informado, a consulta verifica para cada candidato o registro específico do país e, se ele não existir, o registro global. O resultado final informa a correspondência selecionada. Um registro específico do país ambíguo não é substituído automaticamente pelo registro global desse candidato.

O prompt comum da IA procura um nome próprio reconhecível. forceToGenderize também permite associações por meio de apelidos pessoais ou aliases: nesse modo, um gênero diferente de null junto com name: null é um resultado válido. São tarefas de previsão diferentes, que devem ser avaliadas separadamente.

- [Consulta por nome](https://www.genderapi.io/pt/docs/v2/gender-from-name)
- [Consulta por endereço de e-mail](https://www.genderapi.io/pt/docs/v2/gender-from-email)
- [Consulta por nome de usuário](https://www.genderapi.io/pt/docs/v2/gender-from-username)
- [Opções de IA](https://www.genderapi.io/pt/docs/v2/ai-options)

## Consulta ao conjunto de dados e processamento com IA

Quando a IA é usada, a V2 transmite o type, o value e o contexto de país enviados ao serviço de IA configurado para as previsões. Para endereços de e-mail, o prompt pede ao modelo que ignore o domínio e o sufixo depois do sinal de mais; isso não garante que esses caracteres sejam removidos do valor antes de a IA processá-lo. Use ai_mode: off sem forceToGenderize se o seu fluxo de trabalho exigir uma previsão que use apenas o conjunto de dados.

A validação da resposta da IA verifica os campos JSON, os tipos deles e a consistência entre eles. Ela não prova que o nome retornado, a associação a um gênero ou a associação a um país estejam corretos. O resultado público não contém nenhuma identificação ou versão do modelo nem nenhuma fonte que fundamente a previsão.

| Opção | Caminho de previsão | Evidências retornadas |
| --- | --- | --- |
| ai_mode: off | Apenas consulta ao conjunto de dados | Metadados do registro selecionado ou um resultado desconhecido sem registro selecionado |
| ai_mode: fallback | Consulta primeiro o conjunto de dados; usa a IA se nenhum gênero for retornado | Evidências do caminho final, e não uma amostra combinada do conjunto de dados e da IA |
| ai_mode: always | Usa diretamente o caminho de previsão com IA configurado | Um valor informado pelo modelo ou um resultado desconhecido com confidence null; sample_count é sempre null |
| forceToGenderize: true | Consulta o conjunto de dados e, se não houver resultado, usa a IA considerando apelidos | Evidências do conjunto de dados ou uma associação por meio de um apelido informada pelo modelo; name pode ser null |

- [Opções de IA e compatibilidade entre parâmetros](https://www.genderapi.io/pt/docs/v2/ai-options)
- [Política de privacidade](https://www.genderapi.io/pt/privacy-policy)

## Documentação das fontes ainda não publicada

Nenhum catálogo de fontes verificado foi publicado aqui. O contrato de resposta e o comportamento da implementação não bastam, por si sós, para verificar a origem dos dados, o direito de usar uma fonte, a representatividade dela ou a qualidade dos rótulos. Antes de fazer afirmações sobre fontes específicas, as informações a seguir precisam ser documentadas e verificadas.

Esta revisão da documentação não determina se as fontes originais estão ou não cobertas por uma licença nem se estão completas ou incompletas. Ela descreve os limites das evidências disponíveis publicamente. Fale com a GenderAPI.io se o seu caso de uso exigir a avaliação de uma fonte específica.

| Evidência | Documentação necessária | Status público |
| --- | --- | --- |
| Origem e direito de uso | Fonte ou editor nomeado, período de coleta, licença ou outra base documentada para o uso | Nenhum catálogo verificado foi publicado aqui |
| Histórico de processamento | Transformações, normalização, remoção de duplicatas, agregação e qualquer contribuição sintética ou gerada por modelo | Não aparece no rótulo source: dataset |
| Cobertura da população | Cobertura de países e escritas, procedimento de seleção, definições dos rótulos e vieses documentados | Nenhum número de cobertura avaliado de forma independente foi publicado aqui |
| Atualidade | Identificadores de snapshot, datas de atualização por fonte e um plano de atualização compatível | A resposta da V2 não contém informações de atualidade por registro nem identificação do snapshot |
| Qualidade e correções | Resultados de validação, verificações de sobreposição, tratamento de correções e exclusões e responsabilidade pela revisão | Nenhum resultado de auditoria por fonte foi publicado aqui |

## Proteção de dados, processamento e uso responsável

A origem das fontes, o tratamento de dados pessoais e as condições jurídicas são questões diferentes. As funções no tratamento, os prazos de retenção, os provedores e as condições contratuais constam das políticas publicadas atualmente. Este guia técnico não acrescenta novos compromissos de retenção de dados e não certifica a conformidade com a legislação.

Envie apenas os dados de que o seu fluxo de trabalho precisa. Preserve os tipos de confiança e os resultados desconhecidos e não apresente uma previsão como a identidade que a própria pessoa declarou. Não use um gênero inferido como base para decisões com consequências relevantes para uma pessoa.

- [Política de privacidade](https://www.genderapi.io/pt/privacy-policy)
- [Acordo de processamento de dados](https://www.genderapi.io/pt/data-processing-agreement)
- [Suboperadores](https://www.genderapi.io/pt/subprocessors)
- [Informações sobre o GDPR](https://www.genderapi.io/pt/gdpr-compliance)
- [Termos e condições](https://www.genderapi.io/pt/terms)
- [Fale com a GenderAPI.io](https://www.genderapi.io/pt/contact)

## Evidências de precisão e histórico de alterações

O rótulo da fonte explica o caminho da previsão, e não a qualidade medida dela. O guia de precisão mostra como diferenciar os valores das respostas, a cobertura de respostas, os erros e as informações necessárias para uma avaliação reproduzível.

| Data | Versão do documento | Alteração |
| --- | --- | --- |
| 2026-09-29 | 1.0.0 | Versão em português do levantamento datado do MongoDB, das verificações de consistência nas amostras, dos campos source e match da V2, dos limites do processamento com IA e das lacunas restantes no catálogo de fontes. A equivalência entre MongoDB e Redis se baseia na confirmação da GenderAPI.io de 26 de setembro de 2026; a comparação independente ainda está pendente. Nenhuma porcentagem de precisão nem afirmação sobre a licença das fontes foi acrescentada. |

- [Precisão e confiança](https://www.genderapi.io/pt/accuracy-methodology)