InfraNode

Deutsch | English

InfraNode

A API REST de dados abertos para a Alemanha: uma API HTTP sem chave de API para dados abertos sobre infraestrutura pública, também disponível como servidor MCP.

Cidades alemãs publicam muitos dados abertos, mas cada fonte tem seu próprio formato, seus próprios campos e suas próprias peculiaridades, e para várias delas é necessário um registro no respectivo portal. O InfraNode normaliza cerca de 20 categorias, clima (DWD), qualidade do ar (UBA), transporte público (incluindo partidas em tempo real), trânsito, preço de energia (SMARD), valores de referência de terrenos (BORIS), estacionamento, infraestrutura de recarga, níveis de água, demografia, energia e mais, para 84+ cidades alemãs por trás de uma interface. Sem chave de API, sem conta. Cada resposta usa o mesmo envelope canônico { data, meta } com licença e atribuição por conjunto de dados. Os mesmos dados também estão disponíveis para agentes de IA como servidor MCP (12 ferramentas leves somente leitura em 78 tipos de dados). O início é get_city_overview, uma única chamada: ela fornece um catálogo de todos os tipos de dados disponíveis para uma cidade, além de um trecho ao vivo dos valores mais importantes. Assim, os agentes veem toda a amplitude e não apenas o clima. O InfraNode cresce continuamente, novos tipos de dados e cidades são adicionados regularmente.

Entre as fontes estão o Serviço Meteorológico Alemão (DWD), a Agência Ambiental Federal (UBA), Mobilithek/DELFI, o VBB (Associação de Transporte de Berlim-Brandemburgo, CC-BY 4.0), GovData, OpenStreetMap, a Agência Federal de Redes, o KBA e outras.

Em uso

Uma única chamada get_city_overview("koeln"): clima atual, qualidade do ar oficial, alertas do DWD, partidas de trem ao vivo com atrasos, obras e o catálogo completo de dados da cidade, a partir de um endpoint sem chave de API. Cada cidade pode ser testada ao vivo em infranode.dev.

Como funciona

Um cliente HTTP comum consulta as fontes upstream, cada resposta é mapeada para o esquema canônico, passa pelo gate de licença com sua atribuição e é armazenada em cache no Redis (com fallback stale-on-error), depois é entregue por meio de uma API REST e um servidor MCP. Se uma fonte falhar, isso se reflete em source_status. A chamada em si nunca falha por causa disso.

flowchart LR
    subgraph SRC["25+ deutsche Open-Data-Quellen"]
        direction TB
        S1["DWD, UBA<br/>Wetter, Luft"]
        S2["Mobilithek, DELFI, DB<br/>ÖPNV, Echtzeit"]
        S3["SMARD, BNetzA, MaStR<br/>Energie"]
        S4["BORIS, GovData, OSM,<br/>KBA, ..."]
    end

    subgraph CORE["InfraNode-Kern"]
        direction TB
        N["Normalisieren<br/>ein kanonisches Schema"] --> L["Lizenz-Gate<br/>Attribution je Datensatz"] --> C["Redis-Cache<br/>Stale-on-Error-Fallback"]
    end

    SRC --> CORE
    CORE --> API["REST-API<br/>infranode.dev/api/v1<br/>84 Städte, ohne API-Key"]
    CORE --> MCP["MCP-Server<br/>mcp.infranode.dev<br/>12 Read-only-Tools"]
    API --> APPS["Apps &amp; Dashboards"]
    MCP --> AGENTS["KI-Agenten<br/>Claude, ChatGPT"]

Se o InfraNode economizar uma integração de dados para você: uma estrela ajuda outros desenvolvedores a encontrar o projeto.

Início rápido

URL base https://infranode.dev/api/v1. Sem chave, sem conta, basta chamar:

curl https://infranode.dev/api/v1/cities/koeln/weather

{
  "data": {
    "city_slug": "koeln",
    "observed_at": "2026-06-18T13:00:00Z",
    "source": "dwd",
    "attribution": { "text": "Datenbasis: Deutscher Wetterdienst", "modified": true },
    "payload": { "kind": "weather", "temperature_c": 30.4, "humidity": 43.0, "station_id": "02667" }
  },
  "meta": { "source_status": "ok", "cache_status": "hit", "correlation_id": "..." }
}

Cada resposta segue o mesmo envelope { data, meta }: cada conjunto de dados carrega sua attribution (licença e fonte), e meta.source_status indica se a fonte upstream entregou dados. Uma fonte morta degrada de forma limpa, em vez de fazer a chamada falhar.

Em todos os tipos de dados, os nomes dos campos são snake_case e em inglês, e o mesmo conceito sempre tem o mesmo nome: post_code, street, house_number, place, name, start, end, distance_km, power_kw, lat, lon. post_code é sempre uma string de cinco dígitos (zeros à esquerda são preservados), timestamps são ISO 8601 com fuso horário, e um valor que a fonte não fornece é null, nunca uma string vazia. Algumas respostas também incluem nomes duplicados mais antigos com valores idênticos (plz, zip, strasse, hausnummer, ort, city, bezeichnung, beginn, ende, art, dist_km, leistung_kw, einheit_typ, além dos campos brutos camelCase das mensagens de trânsito rodoviário). Esses nomes estão obsoletos; use os canônicos.

Dica: chame primeiro /api/v1/cities para encontrar os slugs canônicos das cidades (por exemplo, koeln, berlin, hamburg) e depois um endpoint específico da cidade.

O {slug} é resolvido de forma tolerante, então você raramente precisa da forma ASCII exata: o nome alemão com ou sem umlauts, qualquer combinação de maiúsculas e minúsculas, exônimos ingleses comuns e formas abreviadas levam todos ao slug canônico (München/münchen/munich/munchen → muenchen, cologne → koeln, frankfurt → frankfurt-am-main). Um nome desconhecido retorna 404 com a dica Meintest du ...?, que menciona o slug mais próximo.

A referência interativa completa e a cobertura por cidade estão em infranode.dev. A API InfraNode no Postman API Network espelha cada endpoint com exemplos de respostas reais, para que a Coleção Postman da API InfraNode possa ser testada diretamente no navegador sem chave de API.

Dados (84 cidades, 124 endpoints)

Cada categoria abaixo é um endpoint REST em /api/v1/cities/{slug}/<key>. Via MCP, os mesmos dados chegam por 12 ferramentas leves: algumas nomeadas (get_city_overview, weather, air_quality, pois, compare, os painéis ao vivo) e uma genérica get_city_resource(slug, resource=<key>) para qualquer outro tipo de dados (seu enum resource lista todas as 81 chaves).

Grupo	Tipos de dados (chaves de endpoint)
Descobrir	list_cities, sources, compare (um tipo de dados em várias cidades), overview (catálogo mais trecho ao vivo em uma chamada)
Clima & Meio Ambiente	weather, weather-warnings, civil-protection-warnings (BBK NINA), air-uba (oficial), air (ao vivo), pollen-uv, water-level, flood, fire-danger, bathing-water
Mobilidade	transit, partidas ao vivo por parada (ferramenta transit_departures), stations (catálogo), painéis de estação por EVA (ferramentas station_board_departures/station_board_arrivals, incluindo transporte regional e interrupções), station-departures, station-arrivals, traffic, road-events, webcams, charging, parking (ocupação ao vivo), parking-onstreet, park-and-ride, mobility-points, bike-parking, sharing, fuel-prices, bike-counts
Cidade & Pessoas	base, geo, demographics, indicators, sustainability (indicadores SDG por município como série temporal 2006-2023, Wegweiser Kommune / Fundação Bertelsmann, CC0), unemployment, tourism, construction, accidents, crime-stats, health, icu-live, holidays, election, events, council-papers (informações municipais do conselho via OParl: propostas, pedidos e decisões por cidade), pois, parques infantis, mercados, banheiros e outros tipos OSM
Economia & Imóveis	land-values, tax-rates (alíquotas de imposto comercial e predial por município), business-registrations (dinâmica de criação de empresas por distrito), insolvencies (processos de insolvência por distrito: empresas e outros devedores, anualmente), public-tenders (licitações públicas: concursos em andamento e contratos adjudicados por cidade)
Energia & Veículos	power-load, power-price, energy, solar, solar-roofs, district-heating, vehicle-registrations

Comportamento em operação

• Sem chave, somente leitura. Sem credenciais, sem acessos de escrita, sem contas de usuário.
• Envelope canônico. { data, meta } com status e atribuição por fonte.
• Degradação suave. Uma fonte com falha entrega source_status, não um erro.
• Projetado com segurança. Gates de SSRF e injeção verificam cada solicitação, entradas passam por allowlists fixas.

O modelo de segurança está em SECURITY.md.

Paginação e predefinições de canal

Listas de tipos de dados (charging, energy, events, transit, os endpoints de recursos OSM) têm uma predefinição dependente de canal na mesma URL:

• REST direto entrega a lista completa em uma chamada (limit=null, returned == total, truncated=false).
• GPT Actions (cabeçalho OpenAI) e MCP estão limitados a um tamanho de página predefinido para manter as respostas pequenas para agentes.
• limit=all (ou ?all=1) força a lista completa em qualquer canal, limit e offset navegam explicitamente.
• meta.pagination (total/returned/limit/offset/truncated) está disponível em todos os canais, então o trecho entregue é sempre rastreável.

Em traffic, a polyline bruta é opcional: adicione include=geometry (ou ?full=1), a resposta padrão permanece enxuta.

Estabilidade, changelog e roadmap

Você está construindo em produção com o InfraNode? Então fique por dentro das mudanças:

• Changelog lista cada mudança visível (novos tipos de dados, novas cidades, comportamento alterado, correções de bugs, deprecações), as mais recentes primeiro. Assinável via RSS.
• Roadmap mostra o planejado e o compromisso de estabilidade: a API cresce de forma aditiva, o envelope permanece estável e mudanças em respostas existentes são anunciadas com antecedência (geralmente 30+ dias).
• Página de status e os releases do GitHub cobrem disponibilidade e mudanças versionadas.

Usar como servidor MCP

A mesma API está disponível como servidor MCP remoto, então agentes de IA podem chamar todos os 78 tipos de dados como ferramentas. Com Claude Code, basta uma linha:

claude mcp add --transport http infranode https://mcp.infranode.dev/mcp

Qualquer outro cliente MCP pode ser configurado no mesmo endpoint remoto (Streamable HTTP):

{
  "mcpServers": {
    "infranode": { "url": "https://mcp.infranode.dev/mcp" }
  }
}

• Cursor / Windsurf: insira o bloco acima em ~/.cursor/mcp.json (ou nas configurações de MCP do aplicativo).
• VS Code: code --add-mcp '{"name":"infranode","url":"https://mcp.infranode.dev/mcp"}'
• Claude Desktop: insira o mesmo bloco mcpServers em claude_desktop_config.json.
• ChatGPT: crie um conector com a URL https://mcp.infranode.dev/mcp.

Todas as ferramentas carregam as anotações readOnlyHint: true / destructiveHint: false / idempotentHint: true, então clientes MCP podem liberá-las automaticamente com segurança. A camada MCP também inclui prompts prontos (city_briefing, compare_air_quality, commute_check) e recursos (infranode://cities, infranode://sources). O guia de instalação completo, o manifesto completo de ferramentas com exemplos de saída, o modelo de permissões e uma transcrição de exemplo estão em docs/mcp-install.md. O manifesto do registro é server.json.

Usar no ChatGPT (ação de GPT personalizado)

GPT pronto: InfraNode: German City Data - Weather & Transit está na loja GPT (Research & Analysis) e funciona imediatamente.

Para uma variante própria, o InfraNode fornece uma especificação OpenAPI curada para GPT Actions: 23 das operações mais úteis (o ChatGPT permite no máximo 30 por ação), sem chave, todas GET.

1. No Editor GPT, abra Configure → Actions → Create new action → Import from URL e insira https://infranode.dev/actions/openapi.json.
2. Deixe a autenticação em None, e insira https://infranode.dev/datenschutz/ como política de privacidade.
3. Nas instruções do GPT, registre: comece com getCityOverview(slug), resolva nomes de cidades via getCities e cite data.attribution (as licenças de dados exigem atribuição).

Detalhes e instruções recomendadas: infranode.dev/chatgpt/. A especificação é gerada por scripts/build_actions_spec.py a partir de docs/openapi.yaml.

Alternativas e como o InfraNode se posiciona

Outros servidores MCP cobrem partes do espaço de dados alemão ou europeu. Para dados abertos em nível municipal, o InfraNode é o mais abrangente, e os projetos abaixo frequentemente se complementam:

• germany-mcp-server Dados federais e governamentais (Autobahn, DWD, NINA, SMARD, Bundestag). Em todo o país, sem profundidade por cidade.
• db-mcp-server / db-timetable-mcp apenas horários da Deutsche Bahn.
• mcp-server-public-transport Transporte público na Europa; na Alemanha, cobre Berlim/Brandemburgo (VBB).
• Servidores para cidades individuais (como Munique, Berlim) cobrem uma cidade cada.

O InfraNode cobre 84 cidades alemãs e 82 tipos de dados por trás de um endpoint hospedado sem chave de API: meio ambiente, mobilidade, energia, economia e vida urbana. A comparação completa lado a lado está em infranode.dev/mcp-vergleich.

Autohospedagem (opcional)

Não é necessário; o endpoint hospedado acima é o caminho mais rápido. O código, no entanto, é aberto. Inicie a pilha da API localmente com Docker (Compose v2):

cp .env.example .env          # example config, contains NO real secrets
docker compose -f deploy/docker-compose.yml up
curl http://localhost/api/v1/health   # -> {"status":"ok","version":"1.0.0","redis":true}

Opere o próprio servidor MCP localmente via stdio (contra a API pública):

uv sync --group mcp
INFRANODE_MCP_API_BASE=https://infranode.dev/api/v1 uv run python -m infranode.mcp.server

Para todas as configurações, aplica-se o prefixo de ambiente INFRANODE_ (veja .env.example), cada fonte de dados tem seu próprio switch INFRANODE_ENABLE_*. Segredos reais nunca entram no repositório; apenas .env.example é versionado, e a CI executa uma verificação gitleaks.

Licença: código e dados são separados

• Código: Apache-2.0 (veja LICENSE).
• Dados: Os dados abertos que o InfraNode entrega mantêm as licenças de suas fontes upstream (por exemplo, ODbL para OpenStreetMap, DL-DE-BY para GovData, atribuição para DWD). Essas licenças de dados e a atribuição são gerenciadas separadamente em DATA-LICENSES.md. A licença Apache-2.0 aplica-se apenas ao código-fonte da API, não aos dados repassados.

Contribua

Contribuições são bem-vindas. Configuração, comandos de gate e a regra de segredos estão em CONTRIBUTING.md. Para uma nova fonte de dados, o registro declarativo de fontes em src/infranode/registry/source_specs.py é o ponto de partida (uma entrada SourceSpec por upstream); a lista de verificação completa está em CONTRIBUTING.md.