GET/v1/maps/style.json•/v1/maps/tiles/{z}/{x}/{y}.pbf

Mapas & Vector Tiles Vetoriais

Forneça mapas vetoriais do território nacional de ultra performance diretamente em sua aplicação Web, Mobile ou Desktop. Compatível nativamente com o padrão aberto MapLibre GL, Mapbox, Leaflet, Flutter e React Native.

10x Mais Rápido & Leve

Tiles vetoriais compactados (.pbf) pesam apenas 15-30KB por quadrante, consumindo 80% menos tráfego que mapas em imagem raster.

Web & Mobile Multiplataforma

Renderização via GPU em 60fps no iOS, Android, Flutter, React Native e navegadores com MapLibre GL.

Estilização Customizável

Total controle sobre paleta de cores, tipografia de ruas, camadas 3D e densidade predial.

Endpoints de Mapas

Método	Endpoint	Formato	Descrição
GET	/v1/maps/style.json	application/json	Retorna a especificação de estilo oficial MapLibre GL JSON contendo as fontes vetoriais e camadas visuais (rodovias, água, edificações, rótulos).
GET	/v1/maps/tiles/{z}/{x}/{y}.pbf	application/x-protobuf	Entrega o tile vetorial (.pbf / MVT) binário compactado para o nível de zoom (z) e coordenadas de grade (x, y) do OpenStreetMap Brasil.

Autenticação & Query Parameters

Como bibliotecas de mapas (MapLibre, Leaflet, Flutter) fazem requisições automáticas para carregar dezenas de quadrantes ao navegar, você pode autenticar via Query Parameter ou Cabeçalho HTTP:

Método de Envio	Formato / Exemplo	Recomendado Para
URL Query Param	?key=gc_live_... ou ?apiKey=gc_live_...	MapLibre GL JS, Mapbox GL, Leaflet, Flutter Map e SDKs Mobile onde a URL do estilo é configurada diretamente.
Cabeçalho HTTP	X-API-Key: gc_live_... ou Authorization: Bearer ...	Chamadas diretas de backend, microserviços, proxies reversos e scripts de automação.

Exemplos de Código (Web & Backend)

# 1. Obter folha de estilo MapLibre GL JSON (pública)
curl -s "https://geocep.api.br/v1/maps/style.json"

# 2. Baixar um Vector Tile .pbf específico (z=12, x=1500, y=2000)
curl -s -o tile.pbf "https://geocep.api.br/v1/maps/tiles/12/1500/2000.pbf"

🌐 Modo público: Gratuito até 100 requisições/hora por IP sem cadastro.HTTPS / TLS 1.3

Integração em Frameworks Mobile & Frontend

1. React / Next.js (MapLibre GL)npm install maplibre-gl

import React, { useEffect, useRef } from "react";
import maplibregl from "maplibre-gl";
import "maplibre-gl/dist/maplibre-gl.css";

export function MeuMapa() {
  const mapContainer = useRef(null);

  useEffect(() => {
    if (!mapContainer.current) return;

    const map = new maplibregl.Map({
      container: mapContainer.current,
      style: "https://geocep.api.br/v1/maps/style.json?key=gc_live_sua_chave",
      center: [-46.6565, -23.5615], // Av. Paulista, São Paulo
      zoom: 13
    });

    map.addControl(new maplibregl.NavigationControl(), "top-right");
    return () => map.remove();
  }, []);

  return <div ref={mapContainer} style={{ width: "100%", height: "450px", borderRadius: "12px" }} />;
}

2. Flutter (Mobile iOS & Android)pubspec.yaml: maplibre_gl

import 'package:flutter/material.dart';
import 'package:maplibre_gl/maplibre_gl.dart';

class MapaGeoCepPage extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: Text('Mapa Brasil - GeoCEP')),
      body: MapLibreMap(
        initialCameraPosition: CameraPosition(
          target: LatLng(-1.4526, -48.4812), // Belém - PA
          zoom: 12.0,
        ),
        styleString: "https://geocep.api.br/v1/maps/style.json?key=gc_live_sua_chave",
        myLocationEnabled: true,
      ),
    );
  }
}

Políticas de Rate Limit & Cache Inteligente

• Usuários Anônimos (Sem Chave): Limitados a 100 requisições/hora por IP público.
• Clientes Autenticados (Planos Starter / Pro / Enterprise): Limite de acordo com a cota mensal contratada.
• Cache Imutável: Os tiles vetoriais acompanham cabeçalho Cache-Control: public, max-age=604800, immutable (7 dias). Isso garante que o navegador e apps façam download de cada quadrante apenas uma vez, economizando requisições do seu plano.

Crowdsourcing & Bônus Otimização de Rotas (TSP)