Documentação da GeoAPI

Bem-vindo à documentação oficial da GeoAPI. Nossa API fornece dados geográficos e de metadados para divisões administrativas, começando pelo Brasil e com planos de expansão global.

A API foi projetada para ser simples, rápida e fácil de integrar em qualquer aplicação que necessite de dados de localização precisos, desde a renderização de mapas interativos até a população de formulários de endereço.

Conceitos Principais

Nossa API é dividida em duas categorias principais de endpoints para otimizar o desempenho e a usabilidade:

1. API de Metadados (/meta)

Propósito: Fornecer dados leves e de referência, como IDs, nomes e códigos.

Formato: Retorna JSON padrão (application/json).

Caso de Uso: Ideal para popular menus, formulários, ou para obter o ID de um recurso antes de solicitar seus dados geográficos completos.

2. API Geográfica (/geo)

Propósito: Fornecer os dados geográficos completos, incluindo as geometrias dos polígonos.

Formato: Retorna GeoJSON (application/geo+json), pronto para ser renderizado em mapas.

Caso de Uso: Para desenhar as formas de países, estados e cidades em um mapa interativo.

Autenticação

Console Interativa

Para usar a console interativa, insira sua chave de API abaixo. Ela será usada para autenticar todas as requisições feitas a partir desta página.

Não tem uma chave? Crie uma agora no seu painel.

Todas as requisições à API devem ser autenticadas usando uma Chave de API (API Key). A chave deve ser enviada no cabeçalho Authorization de cada requisição, utilizando o esquema Bearer.

Exemplo de Cabeçalho:

Authorization: Bearer SUA_CHAVE_DE_API_SECRETA

Requisições sem autenticação ou com uma chave inválida retornarão um erro 401 Unauthorized.

API de Metadados (/meta)

Países

GET/meta/countries

Retorna uma lista de todos os países disponíveis. Atualmente, a GeoAPI provê dados apenas para o Brasil.

Regiões

GET/meta/regions

Retorna uma lista de todas as regiões do Brasil.

GET/meta/regions/{region}

Retorna os dados de uma região específica do Brasil a partir do nome (norte, nordeste, sudeste, sul, centro-oeste).

Parâmetros

Nome	Local	Tipo	Descrição
`{region}`	Path	string	O nome da região (ex: `sul`).

Parâmetro de URL: {region}

GET/meta/regions/{region}/states

Retorna uma lista de todos os estados pertencentes a uma determinada região.

Parâmetro de URL: {region}

GET/meta/regions/{region}/cities

Retorna uma lista de todas as cidades pertencentes a uma determinada região.

Parâmetro de URL: {region}

Estados

GET/meta/states

Retorna uma lista com informações de todos os estados do Brasil.

GET/meta/states/{uf}

Retorna os dados de um estado específico do Brasil a partir do código da UF.

Parâmetro de URL: {uf}

GET/meta/states/{uf}/cities

Retorna uma lista de todas as cidades pertencentes a um determinado estado.

Parâmetro de URL: {uf}

Cidades

GET/meta/cities

Retorna uma lista de todas as cidades do Brasil.

API Geográfica (/geo)

Todos os endpoints /geo retornam uma FeatureCollection no formato GeoJSON, ideal para renderização em mapas.

Regiões

POST/geo/regions

Retorna o GeoJSON para uma ou mais regiões a partir dos IDs informados.

Corpo da Requisição (application/json)

{
  "ids": [1, 2]
}

Corpo da Requisição (JSON)

GET/geo/regions/{region}

Retorna o GeoJSON de uma região específica do Brasil.

Parâmetro de URL: {region}

GET/geo/regions/{region}/states

Retorna o GeoJSON de todos os estados pertencentes a uma determinada região.

Parâmetro de URL: {region}

GET/geo/regions/{region}/cities

Retorna o GeoJSON de todas as cidades pertencentes a uma determinada região.

Parâmetro de URL: {region}

Estados

POST/geo/states

Retorna o GeoJSON para um ou mais estados a partir dos códigos UF informados.

Corpo da Requisição (JSON)

GET/geo/states/{uf}

Retorna o GeoJSON de um estado específico a partir do código da UF.

Parâmetro de URL: {uf}

GET/geo/states/{uf}/cities

Retorna o GeoJSON de todas as cidades pertencentes a um determinado estado.

Parâmetro de URL: {uf}

Cidades

POST/geo/cities

Retorna o GeoJSON para uma ou mais cidades a partir dos códigos IBGE informados.

Corpo da Requisição (JSON)

GET/geo/cities/{ibge_code}/sector

Retorna o GeoJSON de uma cidade específica a partir do seu código IBGE.

Parâmetro de URL: {ibge_code}

Tratamento de Erros

A GeoAPI utiliza códigos de status HTTP padrão para indicar o sucesso ou falha de uma requisição. Respostas de erro seguirão um formato JSON padronizado para facilitar o debug.

Exemplo de Resposta de Erro:

{
  "error": "Not Found",
  "message": "O recurso solicitado não foi encontrado.",
  "status": 404
}

Código	Descrição
`200 OK`	A requisição foi bem-sucedida.
`400 Bad Request`	A requisição está malformada (ex: um parâmetro inválido ou corpo JSON incorreto).
`401 Unauthorized`	A chave de API está faltando ou é inválida.
`403 Forbidden`	Sua chave de API não tem permissão para acessar este recurso.
`404 Not Found`	O recurso solicitado não foi encontrado.
`429 Too Many Requests`	Você excedeu seu limite de requisições (quota).
`500 Internal Server Error`	Ocorreu um erro inesperado em nosso servidor.