ViaCEP - Brazilian zip code checker / address completion

Just published my first plugin. A bit self-serving because I need to use it on 2 different apps so it has to come out of testing.

Pass it a 8-digit CEP (Brazilian zip code) and it returns all relevant address information: street, number, neighborhood, city, and state. Available both as a data call or action. Great when paired with Input Formatter.

I didn’t implement the unicode return. Let me know if someone needs.

First time caller, long time listener.


I have done a small update to implement a new call from Viacep. Now you can pass it a state + city + street and it will return the CEP (the whole CEP object, actually).

  • state (or “uf” in Portuguese): needs to be the 2-digit format.
  • city and street need to have at least 3 characters.
  • it only returns the first 50 entries

Because I am (still) a rookie I do not do any data validation. If you pass it the wrong parameters, you will get an error 400 which Bubble will display as a popup and it will likely break your flow.

More info on

1 Like

O que você está desenvolvendo? Podemos cooperar?

Ôpa, tudo bem!?

(I will continue in English for the benefit of the forum).
I am working on an open access fiber network in São Paulo.

and also

(A new provider has just joined:

Do you live in São Paulo (when you are in Brazil)? I see on your LinkedIn that you’re living in China, too?

Im working on as a starting webapp… I live in China, Im from Joao Pessoa

Hi Rico, how are you?

I’m using the ViaCEP plugin and i’m didn’t understand how to make it works.
Could help me with more detail explanation about how to config your plugin?
This the way i’ve been doing:

  1. Create an Input element for CEP
  2. Create others Input element for the other infos (logradouro, bairro, cidade, uf, etc.)
  3. Configure extra Inputs inicial conent to “Get data from an external API”, selected “ViaCEP - get CEP info-data” as API provider and input dynamic data at (path)cep as “Input CEP’value”.

I think this step by step is tremendous wrong. Hope you could help me with this.

Thanks for the plugin and your attention.

Hi, thanks for the questions!

There are 2 ways to use the plugin:

  1. feed it a CEP and get the details (state, street, ‘bairro’, etc.)
  2. feed it a state + city + street name and get the CEP

For the first one, there are 2 types of Bubble calls: action and data. Data you can use directly on an element; Action you can use in a workflow.

I didn’t quite get what you are trying to accomplish with your steps. Are you trying to have the user enter his CEP and let your application fill in the rest?

My guess is that you only need steps 1 + 3 or steps 2 + 3.

For example, in my apps registration form, I ask the person to input their CEP + number and from there I save the complete address to their user data.

If you share you editor’s link, I would be happy to take a look at it.

Hi Rico, thank you for fast response.

I’m trying to have the user enter his CEP and let my application fill the rest. But not just on the user data, also on the address input field.

I will love to share my editors link with, but i don’t know how. I will copy and paste my link and i wish it works:

Thanks again!

I have exactly this functionality. Here is a video.

(Hmmm… I just realized I recorded the video in Portuguese. I know consoleb11 speaks it, but future users might not. Just nudge me and I will record it in English.)

Hi Rico,

Sorry for the late reply.
Thank you so much for your help. I will watch the video.

Hey Rico! Just to say thank you very much again.
It worked.

1 Like

Does this app work for the whole of Brazil or just for the biggest cities? I am based in the US. And when I need to look for a zip code, I have several options. Usually, I am using You can check here practically all locations in the country irrespective of the size. If your app works the same for Brazil, then it is wonderful. Are there similar apps for other countries?


Yes, you can use this for all ZIP codes of Brazil. The source that ViaCEP uses is from the Brazilian government (

I’m not sure about other countries, but I guess you could use Google Maps or Open Street Maps.

Initially I used Google Maps’s data, but it was not accurate enough for some of the addresses that I was working with.

1 Like

Fala @rico.trevisan,

Estamos usando demais o plugin, muito obrigado!

Uma dúvida: você conseguiria, por gentileza, retirar o valor inicial do parâmetro da chamada get CEP info - data, conforme abaixo?

Digo pois quando a gente abre o CEP, já vem com os dados desse plugin, é meio confuso pro usuário.



Boa idéia, obrigado!

:white_check_mark: done

Fala @rico.trevisan , tudo bem?

Antes de qualquer coisa, obrigado pelo plugin! :slight_smile:

Vamos lá… Estou usando o plugin para pegar os dados durante um workflow. O problema é que quando o usuário não completa o CEP (coloca somente, 123, por exemplo) o plugin retorna um erro. Como o erro é do plugin, não consigo tratar esse erro em específico.


Sabe como posso impedir este comportamento?

Fiz alguns updates:

@rpetribu nessa página de exemplos eu aplico filtros para impedir esses erros.

1 Like

Boa @rico.trevisan . :+1:

O que acabei fazendo foi só disparar o workflow se o CEP estiver completo, assim previno o erro de acontecer. Foi basicamente o que você também fez ai, pelo que vi!

Muito obrigado pelo retorno!

1 Like

excelente plugin. já estou usando e vou avaliar 5 estrelas!

1 Like

Olá amigo, eu não consigo fazer com que os dados se autocompletem de forma alguma… eu criei um input que recebe os dados do cep, depois coloquei um outro input para mostrar a rua recebida… mas nada que eu faça funciona… você poderia me dar um passo a passo de como fazer?