01Visão geral

Esta API entrega os pontos atendidos pelo serviço de Cata-Bagulho. Os dados são organizados como setores → logradouros → trechos → coordenadas, conforme o DIS PRODAM v1.1.

Convenções

• Base URL: https://prodam.gestorurbano.com.br
• Método HTTP: GET (somente leitura)
• Formato: application/json (UTF-8)
• Autenticação: usuário e senha (HTTP Basic)
• HTTPS: obrigatório (HTTP é redirecionado com 308)

02Autenticação

A API usa autenticação HTTP padrão. Você passa usuário e senha em cada requisição — qualquer cliente HTTP moderno já tem suporte nativo, sem você precisar construir nada manualmente.

Onde informar

03Endpoint

O servidor expõe um único padrão de URL, com o nome do arquivo no path:

Parâmetros do path

Exemplos de URL

# Parte 1 (sempre o arquivo inicial)
GET /empresa/cata_bagulho/json/cata_bagulho_empresa.json

# Parte 2 (informado em proximoArquivo da parte 1)
GET /empresa/cata_bagulho/json/cata_bagulho_empresa_2.json

# Parte N (continua seguindo a cadeia ate proximoArquivo = "Final")
GET /empresa/cata_bagulho/json/cata_bagulho_empresa_N.json

04Cadeia de partes

Quando o conjunto de dados é grande, ele é dividido em várias partes. Cada parte tem no final do JSON o campo detalheArquivo.proximoArquivo, que indica o nome literal do próximo arquivo a buscar.

{
  "empresas": [ ... ],
  "detalheArquivo": {
    "qtdeSetores": 25,
    "proximoArquivo": "cata_bagulho_empresa_2.json"
  }
}

O cliente continua iterando até que proximoArquivo seja a string literal "Final":

# Pseudocodigo do fluxo
atual = "cata_bagulho_empresa.json"
todas_partes = []

while atual != "Final":
    resposta = GET "/empresa/cata_bagulho/json/" + atual
    todas_partes.append(resposta.json())
    atual = resposta.json()["detalheArquivo"]["proximoArquivo"]

05Schema do JSON

Conforme o DIS PRODAM v1.1. A raiz tem um array empresas (cada item é um setor) e o metadado detalheArquivo.

Setor (item do array empresas)

Logradouro

Trecho

Coordenada

detalheArquivo (raiz)

Modelo montado (exemplo)

Como uma parte fica quando montada — 1 setor resumido (na prática o array empresas traz vários setores por arquivo):

{
  "empresas": [
    {
      "id": "1",
      "codigoSetor": "AA10500GO0001",
      "subprefeitura": "Subprefeitura Exemplo",
      "frequencia": "Quinzenal",
      "horarioInicial": "06:00",
      "horarioFinal": "14:20",
      "dias": ["2026-03-16", "2026-03-30"],
      "servico": "cata_bagulho",
      "empresa": "Concessionária Exemplo",
      "logradouros": [
        {
          "logradouro": "Rua Exemplo",
          "latitude": -23.603269,
          "longitude": -46.779871,
          "cep": "08490-000",
          "trechos": [
            {
              "id": "1",
              "enderecoInicial": "Rua A",
              "enderecoFinal": "Rua B",
              "coordenadas": [
                { "latitude": -23.603225, "longitude": -46.780112 },
                { "latitude": -23.603248, "longitude": -46.779987 }
              ]
            }
          ]
        }
      ]
    }
  ],
  "detalheArquivo": {
    "qtdeSetores": 25,
    "proximoArquivo": "cata_bagulho_empresa_2.json"
  }
}

06Exemplos de código

Selecione a linguagem ou ferramenta. Substitua empresa, usuario e senha pelos seus valores reais.

# Uma parte
curl -u "usuario:senha" \
  https://prodam.gestorurbano.com.br/empresa/cata_bagulho/json/cata_bagulho_empresa.json

# Cadeia completa (script bash com jq)
URL="https://prodam.gestorurbano.com.br/empresa/cata_bagulho/json"
ARQ="cata_bagulho_empresa.json"
while [ "$ARQ" != "Final" ] && [ -n "$ARQ" ]; do
  echo "Baixando $ARQ..."
  RESP=$(curl -s -u "usuario:senha" "$URL/$ARQ")
  echo "$RESP" > "$ARQ"
  ARQ=$(echo "$RESP" | jq -r '.detalheArquivo.proximoArquivo')
done

# Com a biblioteca requests (recomendado)
import requests

BASE = "https://prodam.gestorurbano.com.br/empresa/cata_bagulho/json"
AUTH = ("usuario", "senha")

session = requests.Session()
session.auth = AUTH

atual = "cata_bagulho_empresa.json"
todas = []
while atual and atual.lower() != "final":
    r = session.get(f"{BASE}/{atual}", timeout=60)
    r.raise_for_status()
    data = r.json()
    todas.append(data)
    atual = data["detalheArquivo"]["proximoArquivo"]

print(f"Baixei {len(todas)} parte(s)")

import json
from urllib import request
from urllib.request import HTTPPasswordMgrWithDefaultRealm, HTTPBasicAuthHandler, build_opener

BASE = "https://prodam.gestorurbano.com.br/empresa/cata_bagulho/json"

pm = HTTPPasswordMgrWithDefaultRealm()
pm.add_password(None, BASE, "usuario", "senha")
opener = build_opener(HTTPBasicAuthHandler(pm))

def baixar(arquivo):
    with opener.open(f"{BASE}/{arquivo}", timeout=60) as r:
        return json.loads(r.read())

atual = "cata_bagulho_empresa.json"
todas = []
while atual and atual.lower() != "final":
    data = baixar(atual)
    todas.append(data)
    atual = data["detalheArquivo"]["proximoArquivo"]

// Fetch nativo do navegador
const BASE = "https://prodam.gestorurbano.com.br/empresa/cata_bagulho/json";
const AUTH = "Basic " + btoa("usuario:senha");

async function baixar(arquivo) {
  const r = await fetch(`${BASE}/${arquivo}`, {
    headers: { "Authorization": AUTH }
  });
  if (!r.ok) throw new Error(`HTTP ${r.status}`);
  return r.json();
}

let atual = "cata_bagulho_empresa.json";
const todas = [];
while (atual && atual.toLowerCase() !== "final") {
  const data = await baixar(atual);
  todas.push(data);
  atual = data.detalheArquivo.proximoArquivo;
}
console.log(`${todas.length} parte(s) baixadas`);

// Node.js 18+ (fetch nativo)
const BASE = "https://prodam.gestorurbano.com.br/empresa/cata_bagulho/json";
const AUTH = "Basic " + Buffer.from("usuario:senha").toString("base64");

async function baixarTudo() {
  let atual = "cata_bagulho_empresa.json";
  const todas = [];

  while (atual && atual.toLowerCase() !== "final") {
    const r = await fetch(`${BASE}/${atual}`, {
      headers: { Authorization: AUTH }
    });
    if (!r.ok) throw new Error(`HTTP ${r.status} em ${atual}`);

    const lastModified = r.headers.get("Last-Modified");
    const data = await r.json();
    todas.push({ arquivo: atual, lastModified, data });
    atual = data.detalheArquivo?.proximoArquivo;
  }
  return todas;
}

baixarTudo().then(p => console.log(`Baixei ${p.length} parte(s)`));

07Códigos de retorno

08Rate limits e desempenho

• 60 requisições / minuto por IP em endpoints de dados
• 20 falhas de autenticação / hora por IP → bloqueio temporário
• Tamanho típico de uma parte: 500 KB a 3,5 MB
• Tamanho típico de uma cadeia completa: 1 a 10 MB

09Suporte e ferramentas

• Visualizador público — login com sua credencial, vê os JSONs no mapa
• Status da API — página de uptime e healthcheck visual

Especificação oficial: DIS - Integração CataBagulho JSON - PRODAM v1.1 (07/03/2025).