VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/Idiomas e localidades

Países, estados, cidades e bairros

Lista os países, os estados, as cidades e os bairros cadastrados na plataforma, com filtros e paginação, para preencher os seletores de endereço.

A plataforma mantém uma base oficial de localidades do Brasil. Estas quatro rotas públicas a entregam em cascata: países, estados de um país, cidades de um estado e bairros de uma cidade. O uso típico é um formulário de endereço em que escolher o estado carrega as cidades e escolher a cidade carrega os bairros. Estas rotas não buscam por CEP: servem quando o comprador escolhe a localidade em listas.

Países e estados não têm paginação. Cidades e bairros são paginados. Todas as respostas têm cache público de 5 minutos.

Listar países

GET/api/v1/storefront/locations/countriesPública

Lista os países

Lista os países cadastrados. Na loja de teste existe só o Brasil.

Parâmetros de consulta

statusstring
Filtra por situação do país (A ativo). Sem o parâmetro, devolve todos. Um valor sem nenhum país devolve {"countries": null, "total": 0}.

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/storefront/locations/countries"

Resposta

200Países
json
{
  "countries": [
    { "code": "BR", "name": "Brazil", "name_pt": "Brasil", "status": "A" }
  ],
  "total": 1
}

Campos da resposta

countriesarray|null
Países. null quando nenhum atende ao filtro.
countries[].codestring
Código ISO de 2 letras (BR). É o valor de country_code nos estados e de country no endereço.
countries[].namestring
Nome em inglês.
countries[].name_ptstring
Nome em português.
countries[].statusstring
A (ativo).
totalinteger
Quantidade de países devolvidos.

Erros

StatusQuandoCorpo
500Falha ao listar{"error":"failed to list countries","detail":"..."}

Listar estados

GET/api/v1/storefront/locations/statesPública

Lista os estados de um país

Lista os estados (UFs). Sem filtro devolve todos os estados cadastrados; na loja de teste são os 27 do Brasil.

Parâmetros de consulta

country_codestring
Código do país (BR). Opcional.

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/storefront/locations/states?country_code=BR"

Resposta

200Estados
json
{
  "states": [
    {
      "id": "bd6860b2-2838-4eb7-ab27-37b0be2412ab",
      "country_code": "BR",
      "code": "AC",
      "name": "Acre",
      "name_pt": "Acre"
    },
    {
      "id": "fc855973-fe7d-407f-aa1f-f19c4490f06d",
      "country_code": "BR",
      "code": "AL",
      "name": "Alagoas",
      "name_pt": "Alagoas"
    }
  ],
  "total": 27
}

Campos da resposta

statesarray
Estados (o exemplo mostra dois dos 27).
states[].iduuid
Id do estado. É o state_id das cidades.
states[].country_codestring
País do estado.
states[].codestring
Sigla da UF (SP). É o valor de state no endereço.
states[].namestring
Nome do estado.
states[].name_ptstring
Nome em português.
totalinteger
Quantidade de estados devolvidos.

Erros

StatusQuandoCorpo
500Falha ao listar{"error":"failed to list states","detail":"..."}

Listar cidades

GET/api/v1/storefront/locations/citiesPública

Lista as cidades, com filtros e paginação

Lista as cidades, em ordem alfabética, 50 por página por padrão. Filtre por estado com state_id (o id de um item de states) e busque por parte do nome com search. O limite é de 1000 por página: um valor maior que isso (por exemplo, per_page=9999 para trazer o estado inteiro de uma vez) é reduzido para 1000.

Parâmetros de consulta

state_iduuid
Só as cidades deste estado.
searchstring
Parte do nome da cidade, sem diferenciar maiúsculas de minúsculas (Campinas acha também Campinas do Sul).
sort_dirstringpadrão: asc
ascdesc
Sentido da ordem alfabética.
pageintegerpadrão: 1
Página, a partir de 1.
per_pageintegerpadrão: 50
Itens por página, até 1000.

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/storefront/locations/cities?state_id=40ccb0c3-e36f-495c-846d-15464f01f43f&per_page=100"

Resposta

200Cidades
json
{
  "cities": [
    {
      "id": "52f3b670-a88e-4dae-8c0f-b81a672215d1",
      "state_id": "40ccb0c3-e36f-495c-846d-15464f01f43f",
      "state_name": "Goiás",
      "state_code": "GO",
      "name": "Abadia de Goiás",
      "ibge_code": "5200050"
    }
  ],
  "total": 246,
  "page": 1,
  "per_page": 50,
  "total_pages": 5
}

Campos da resposta

citiesarray
Cidades da página.
cities[].iduuid
Id da cidade. É o city_id dos bairros.
cities[].state_iduuid
Estado da cidade.
cities[].state_namestring
Nome do estado.
cities[].state_codestring
Sigla da UF.
cities[].namestring
Nome da cidade.
cities[].ibge_codestring
Código do município no IBGE (7 dígitos).
totalinteger
Total de cidades que atendem ao filtro (5.571 sem filtro).
pageinteger
Página devolvida.
per_pageinteger
Tamanho de página usado.
total_pagesinteger
Total de páginas.

Erros

StatusQuandoCorpo
500state_id que não é UUID{"error":"failed to list cities","detail":"o valor \"abc\" não é um uuid válido. ..."}
500Falha ao listar{"error":"failed to list cities","detail":"..."}
Filtros desconhecidos são ignorados

Parâmetros que a rota não conhece, como state_code ou q, não dão erro e não filtram: a resposta volta com as 5.571 cidades paginadas. Use state_id e search. O detail do 500 por id inválido é uma frase em português.

Listar bairros

GET/api/v1/storefront/locations/districtsPública

Lista os bairros de uma cidade, com paginação

Lista os bairros, 50 por página por padrão e até 3000. Cada bairro traz a faixa de CEP que ele cobre, útil para sugerir o bairro a partir do CEP digitado. Na loja de teste há mais de 74 mil bairros: sempre filtre por cidade.

Parâmetros de consulta

city_iduuid
Só os bairros desta cidade (o id de um item de cities).
searchstring
Parte do nome do bairro.
pageintegerpadrão: 1
Página, a partir de 1.
per_pageintegerpadrão: 50
Itens por página, até 3000.

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/storefront/locations/districts?city_id=26cfb7bb-3ba4-4b77-be38-1fb5c5bf11b7&per_page=100"

Resposta

200Bairros
json
{
  "districts": [
    {
      "id": "22f6bd51-65bd-470c-99cb-1b7662cd9d82",
      "city_id": "26cfb7bb-3ba4-4b77-be38-1fb5c5bf11b7",
      "city_name": "Ouro Preto",
      "name": "13 de Maio",
      "cep_range_start": "35406040",
      "cep_range_end": "35406082"
    }
  ],
  "total": 78,
  "page": 1,
  "per_page": 50,
  "total_pages": 2
}

Campos da resposta

districtsarray
Bairros da página.
districts[].iduuid
Id do bairro.
districts[].city_iduuid
Cidade do bairro.
districts[].city_namestring
Nome da cidade.
districts[].namestring
Nome do bairro, como cadastrado.
districts[].cep_range_startstring
Início da faixa de CEP, 8 dígitos sem hífen.
districts[].cep_range_endstring
Fim da faixa de CEP, 8 dígitos sem hífen.
totalinteger
Total de bairros que atendem ao filtro.
pageinteger
Página devolvida.
per_pageinteger
Tamanho de página usado.
total_pagesinteger
Total de páginas.

Erros

StatusQuandoCorpo
400city_id que não é UUID{"error":"invalid city_id","detail":"city_id must be a valid UUID"}
500Falha ao listar{"error":"failed to list districts","detail":"..."}

Veja também

  • Endereço, frete e pagamento no checkout
  • Idiomas da vitrine
  • Visão geral de idiomas e localidades
Anterior
Idiomas da vitrine
Próxima
SEO, testes A/B e envio de arquivos
Nesta página
  • Listar países
  • Exemplo de requisição
  • Resposta
  • Erros
  • Listar estados
  • Exemplo de requisição
  • Resposta
  • Erros
  • Listar cidades
  • Exemplo de requisição
  • Resposta
  • Erros
  • Listar bairros
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também