Quantas pessoas têm o seu nome? API do IBGE no n8n

Você já se perguntou quantas pessoas no Brasil têm o mesmo nome que você? O IBGE responde isso numa API pública e gratuita, com base no Censo. Neste tutorial você vai criar no n8n um formulário onde qualquer pessoa digita um primeiro nome e, em seguida, vê o total de registros e a década em que aquele nome foi mais usado.

São só três nós, e o exemplo ensina algo que você vai usar muito: pegar uma lista que veio de uma API e resumir essa lista numa frase, com uma expressão. Não é preciso cadastro nem chave.

O que você vai construir

Este é o workflow final no editor do n8n:

Editor do n8n com o workflow Quantas pessoas têm o seu nome (IBGE): nós On form submission, HTTP Request e Form (Form Ending) ligados em sequência
O workflow final “Quantas pessoas têm o seu nome (IBGE)” no editor do n8n (versão 2.40.7).
  • n8n Form Trigger (no canvas, “On form submission”): cria o formulário com o campo Nome.
  • HTTP Request: consulta a API de nomes do IBGE com o nome digitado.
  • n8n Form com a página Form Ending: mostra o total e a década mais popular.

Versão usada: n8n 2.40.7. Os nomes de botões e campos aparecem em inglês, exatamente como na interface. Como exemplo, usamos Maria, o nome mais comum do país. A API devolve apenas contagens por nome, sem nenhum dado de pessoas.

Pré-requisitos

Montando o workflow, nó por nó

Crie um workflow novo e dê a ele o nome Quantas pessoas têm o seu nome (IBGE). Depois, adicione os três nós abaixo, nesta ordem, sempre pelo botão + que aparece à direita do nó anterior.

Nó 1: n8n Form Trigger (o formulário)

Clique em Add first step, digite “form” na busca, clique em n8n Form e escolha o gatilho On new n8n Form event. O nó entra no canvas com o nome On form submission.

Tela do nó On form submission com Form Title Quantas pessoas têm o seu nome?, Form Description, um campo Text Input com Label Nome e placeholder ex.: Maria; à direita, a saída JSON com Nome Maria, submittedAt e formMode test
Configuração do Form Trigger. À direita (OUTPUT), o resultado de um envio de teste.
CampoValorPor que assim
AuthenticationNoneQualquer pessoa com o link pode usar. Os dados são públicos.
Form TitleQuantas pessoas têm o seu nome?Título no topo da página.
Form DescriptionDigite só o primeiro nome, sem sobrenome, para ver quantas pessoas o Censo 2010 do IBGE encontrou com ele.Já avisa que a API trabalha com um nome só (veja os erros comuns).
Form Elements → LabelNomeNome do campo na tela e também o nome do dado na saída do nó.
Form Elements → Element TypeText InputUm campo de texto simples.
Form Elements → Placeholderex.: MariaExemplo em cinza que some quando a pessoa começa a digitar.
Form Elements → Required FieldligadoImpede o envio com o campo vazio.
Options(nenhuma)As opções padrão bastam.

Clique em Execute step. O n8n abre o formulário de teste numa nova aba. Digite Maria e clique em Submit:

Formulário de teste Quantas pessoas têm o seu nome? com o aviso This is a test version of your form, o campo Nome preenchido com Maria e o botão Submit
O formulário de teste com o nome de exemplo.

De volta ao n8n, a saída do nó traz o campo Nome com o valor Maria, além de submittedAt e formMode.

Nó 2: HTTP Request (consultar o IBGE)

A API de nomes do IBGE recebe o nome no fim da URL. Vamos montar o endereço com uma expressão que pega o campo do formulário e remove espaços extras no começo e no fim, com .trim(). Esta é a URL completa:

https://servicodados.ibge.gov.br/api/v2/censos/nomes/{{ $json.Nome.trim() }}

Clique no + à direita do Form Trigger, adicione um nó HTTP Request e preencha como na tabela:

Tela do nó HTTP Request com Method GET e a URL com a expressão $json.Nome.trim(); à direita, a resposta JSON com nome MARIA, sexo null, localidade BR e a lista res com periodo e frequencia por década
HTTP Request consultando o nome digitado. À direita (OUTPUT), a resposta do IBGE com uma contagem por década.
CampoValorPor que assim
MethodGETVamos apenas consultar dados.
URLa URL do bloco acimaEndereço de nomes da API do IBGE, com o nome digitado no final.
AuthenticationNoneA API do IBGE é pública.
Send Query ParametersdesligadoO nome já vai dentro da própria URL.
Send HeadersdesligadoNão são necessários cabeçalhos especiais.
Send BodydesligadoUma consulta GET não envia corpo.
Options(nenhuma)As opções padrão bastam.

Clique em Execute step. A resposta tem os campos nome (MARIA, em maiúsculas e sem acento), sexo (null, porque não filtramos por sexo), localidade (BR, o Brasil inteiro) e res, uma lista com uma linha por década. Cada linha tem periodo e frequencia, que é quantas pessoas nascidas naquele período foram registradas com o nome.

O período usa uma notação de intervalo: [1960,1970[ quer dizer “de 1960 até antes de 1970”, ou seja, a década de 1960. A primeira linha, 1930[, reúne quem nasceu antes de 1930, e a última, [2000,2010[, vai até 2009. As décadas terminam em 2010 porque os dados vêm do Censo 2010. Um detalhe: a API devolve uma lista com um único objeto, e o n8n transforma isso em 1 item.

Nó 3: n8n Form com Form Ending (a página final)

Agora vamos transformar a lista de décadas em duas informações fáceis de ler: o total de pessoas e a década mais popular. Clique no + à direita do HTTP Request, adicione o nó n8n Form e, em Page Type, escolha Form Ending. Esta é a mensagem completa, com as duas expressões; o <br> quebra a linha na página:

Pessoas com esse nome no Censo 2010: {{ $json.res.reduce((soma, item) => soma + item.frequencia, 0).toLocaleString('pt-BR') }}<br>Nascidas na década mais popular: {{ $json.res.reduce((maior, item) => item.frequencia > maior.frequencia ? item : maior).periodo }}
Tela do nó Form com Page Type Form Ending, Completion Title $json.nome resolvido como MARIA e Completion Message com duas expressões reduce; a prévia mostra Pessoas com esse nome no Censo 2010: 11.734.129
O nó Form configurado como Form Ending. Abaixo da mensagem, a prévia já mostra o total calculado.
CampoValorPor que assim
Page TypeForm EndingÚltima tela do formulário.
On n8n Form SubmissionShow Completion ScreenMostra uma tela com título e mensagem.
Completion Title{{ $json.nome }}O próprio nome, do jeito que o IBGE devolveu.
Completion Messageo texto do bloco acimaUma linha com o total e outra com a década mais popular.
Limit Wait TimedesligadoNão precisamos limitar o tempo de espera.
Options(nenhuma)As opções padrão bastam.

As duas expressões usam reduce, uma função do JavaScript que percorre a lista e vai acumulando um resultado. Vale ler com calma:

  • Total: $json.res.reduce((soma, item) => soma + item.frequencia, 0) começa em 0 e, para cada década (item), soma a frequencia. No fim, .toLocaleString('pt-BR') escreve o número com pontos separando os milhares, como estamos acostumados.
  • Década mais popular: $json.res.reduce((maior, item) => item.frequencia > maior.frequencia ? item : maior) compara as décadas duas a duas e fica sempre com a de maior frequência. O .periodo no final pega só o texto do período.

Na prévia abaixo do campo, o n8n já mostra o começo do resultado: “Pessoas com esse nome no Censo 2010: 11.734.129”.

O workflow completo e o teste

Feche o nó e clique em Execute workflow. O n8n abre o formulário de teste; digite Maria e clique em Submit. A página final mostra o resultado:

Página final do formulário com o título MARIA e as linhas Pessoas com esse nome no Censo 2010: 11.734.129 e Nascidas na década mais popular: [1960,1970[
Resultado do teste: 11.734.129 Marias, com mais registros entre quem nasceu na década de 1960.

Segundo a API, o Censo 2010 encontrou 11.734.129 pessoas chamadas Maria, e a década com mais registros foi a de 1960 ([1960,1970[). Também testamos com João, digitado com acento: a API respondeu normalmente, com o nome escrito JOAO. No editor, os três nós ficam verdes, com 1 item em cada ligação:

Workflow executado com os três nós em verde e 1 item em cada ligação
O workflow completo depois do teste.

No painel Logs, na barra inferior, selecione o nó Form para ver os dados que passaram por ele, com a lista res aberta década por década:

Painel Logs com o nó Form selecionado e a tabela com nome MARIA, sexo null, localidade BR e a lista res com periodo e frequencia
O painel Logs depois do teste.

Usar o formulário de verdade (Production URL)

O link de teste só funciona enquanto o editor está esperando um envio. Para ter um link fixo, clique em Publish, no canto superior direito do editor, e confirme. Depois, abra o Form Trigger, clique na aba Production URL e copie o endereço. Com o n8n rodando só no seu computador, o link também só abre nele.

Erros comuns

A página mostra só “Form Submitted” e “Your response has been recorded”. Aconteceu quando digitamos um nome composto com espaço, Maria Clara. A API do IBGE procura um nome só e, sem encontrar, devolve uma lista vazia. Com isso, o HTTP Request termina sem nenhum item (“No output data returned”), o n8n para o workflow ali e o nó Form nunca roda; por isso aparece a tela padrão de envio, sem resultado.

Nó HTTP Request com o nome Maria Clara no INPUT e a mensagem No output data returned, n8n stops executing the workflow when a node has no output data
Erro real com um nome composto: a API devolve uma lista vazia e o workflow para no HTTP Request.
Página do formulário com a mensagem padrão Form Submitted e Your response has been recorded
O que a pessoa vê nesse caso: a tela padrão do formulário, sem resultado.

A solução mais simples é digitar só o primeiro nome, como pede a descrição do formulário. Se quiser mostrar uma mensagem como “nome não encontrado”, o próprio aviso do n8n indica o caminho: ligar a opção Always Output Data na aba Settings do HTTP Request e, depois, tratar o caso vazio com um nó If.

“The resource you are requesting could not be found” com “404 – “””. Aconteceu quando escrevemos {{ $json.nome }}, em minúsculas, na URL. Como o formulário envia o campo Nome, com N maiúsculo, a expressão ficou vazia e a URL terminou em /nomes/, um endereço que não existe. A prévia abaixo do campo URL mostra isso na hora.

Nó HTTP Request com a expressão $json.nome em vermelho, a URL resolvida terminando em /nomes/ e o erro The resource you are requesting could not be found
Erro real com o nome do campo em minúsculas: a URL fica sem o nome.

JSON do workflow para importar

Se preferir, importe o workflow pronto. Baixe o arquivo abaixo ou copie o JSON. No n8n, crie um workflow novo e escolha uma das opções: abra o menu … (três pontinhos) no topo do editor, vá em Import e depois em From file; ou cole o JSON direto no canvas com Ctrl+V.

nomes-ibge.zipBaixar

O download é um arquivo .zip com o nomes-ibge.json dentro. Descompacte antes de importar (ou copie o JSON do bloco abaixo).

{
  "name": "Quantas pessoas têm o seu nome (IBGE)",
  "nodes": [
    {
      "parameters": {
        "formTitle": "Quantas pessoas têm o seu nome?",
        "formDescription": "Digite só o primeiro nome, sem sobrenome, para ver quantas pessoas o Censo 2010 do IBGE encontrou com ele.",
        "formFields": {
          "values": [
            {
              "fieldLabel": "Nome",
              "placeholder": "ex.: Maria",
              "requiredField": true
            }
          ]
        },
        "options": {}
      },
      "id": "9a4c2e71-1111-4b8d-8e04-100000000001",
      "name": "On form submission",
      "type": "n8n-nodes-base.formTrigger",
      "typeVersion": 2.6,
      "position": [
        0,
        0
      ],
      "webhookId": "9a4c2e71-aaaa-4b8d-8e04-1000000000f1"
    },
    {
      "parameters": {
        "url": "=https://servicodados.ibge.gov.br/api/v2/censos/nomes/{{ $json.Nome.trim() }}",
        "options": {}
      },
      "id": "9a4c2e71-2222-4b8d-8e04-100000000002",
      "name": "HTTP Request",
      "type": "n8n-nodes-base.httpRequest",
      "typeVersion": 4.5,
      "position": [
        260,
        0
      ]
    },
    {
      "parameters": {
        "operation": "completion",
        "completionTitle": "={{ $json.nome }}",
        "completionMessage": "=Pessoas com esse nome no Censo 2010: {{ $json.res.reduce((soma, item) => soma + item.frequencia, 0).toLocaleString('pt-BR') }}<br>Nascidas na década mais popular: {{ $json.res.reduce((maior, item) => item.frequencia > maior.frequencia ? item : maior).periodo }}",
        "options": {}
      },
      "id": "9a4c2e71-3333-4b8d-8e04-100000000003",
      "name": "Form",
      "type": "n8n-nodes-base.form",
      "typeVersion": 2.5,
      "position": [
        520,
        0
      ],
      "webhookId": "9a4c2e71-bbbb-4b8d-8e04-1000000000f2"
    }
  ],
  "connections": {
    "On form submission": {
      "main": [
        [
          {
            "node": "HTTP Request",
            "type": "main",
            "index": 0
          }
        ]
      ]
    },
    "HTTP Request": {
      "main": [
        [
          {
            "node": "Form",
            "type": "main",
            "index": 0
          }
        ]
      ]
    }
  },
  "pinData": {},
  "settings": {
    "executionOrder": "v1"
  },
  "meta": {
    "templateCredsSetupCompleted": false
  }
}

O workflow não usa credenciais, então funciona logo depois de importado. Os campos webhookId identificam os endereços do formulário dentro do seu n8n; você não precisa mexer neles.

Recapitulando

  • O n8n Form Trigger recebe o nome; o HTTP Request consulta a API de nomes do IBGE.
  • A resposta traz uma lista res com a frequência do nome por década de nascimento, segundo o Censo 2010.
  • Com reduce, uma expressão soma a lista ou encontra o maior valor dela.
  • Uma lista vazia faz o workflow parar sem erro: digite um nome só, ou trate esse caso com Always Output Data e um If.

A mesma ideia de resumir uma lista com uma expressão serve para muitas outras APIs: somar valores, achar o maior, contar itens. Nos próximos tutoriais, vamos continuar explorando dados públicos brasileiros com o n8n.