Documentação · dados abertos

A API do Baldio

Os projectos e eventos de transição do Baldio em JSON, para os mostrares no teu site, mapa ou aplicação.

A leitura é aberta e não precisa de chave: devolve a mesma informação que está nas páginas públicas do Baldio. Contactos que as pessoas marcaram como privados nunca são incluídos.

Também podes publicar um projecto ou evento pela API. Editar exige provar que és o responsável: sessão iniciada no Baldio ou o cookie de quem criou a entrada.

Beta. Os endpoints e campos documentados aqui são estáveis; o que não estiver documentado pode mudar sem aviso. Durante a migração do Baldio para a nova versão, adicionar e editar estão temporariamente fechados (respondem 503). A leitura funciona normalmente.

Listar projectosGET /projectos Pontos para um mapaGET /mapa Usar no browser/baldio.json, com CORS

URL base

https://baldio.eu/api/v1

Primeiro pedido

curl "https://baldio.eu/api/v1/projectos?categoria=quinta-agroecologia"

Começar

Acesso e boas práticas

Do teu servidor, não do browser

A API não tem CORS: chama-a a partir do teu servidor (PHP, Python, Node, um cron, Apps Script…). JavaScript a correr no browser de um visitante noutro domínio não consegue ler as respostas.

Para usar directamente no browser existe /baldio.json, um feed leve com CORS aberto.

Guarda em cache

Os dados mudam poucas vezes por dia. Guarda as respostas pelo menos 1 hora e não chames a API a cada visita ao teu site. Não há limite formal de pedidos, mas pedidos em excesso podem ser bloqueados.

Formato

JSON em UTF-8. Datas como AAAA-MM-DD; timestamps como AAAA-MM-DD hh:mm:ss (hora de Lisboa).
Imagens e url vêm como caminhos relativos: junta https://baldio.eu à frente.
Campos de texto sem valor vêm como "", não null.

PHP · com cache de 1 hora

$cache = __DIR__ . '/baldio-cache.json';
if (!is_file($cache) || filemtime($cache) < time() - 3600) {
    $json = file_get_contents('https://baldio.eu/api/v1/projectos');
    if ($json !== false) file_put_contents($cache, $json);
}
$projectos = json_decode(file_get_contents($cache), true);

foreach ($projectos as $p) {
    echo $p['name'], ' — https://baldio.eu', $p['url'], "\n";
}

Começar

Respostas e erros

Lista ou envelope

/projectos e /eventos devolvem uma lista quando chamados sem filtros. Com qualquer filtro (categoria, tag, lat/lng, upcoming…) devolvem um envelope {"items": [...], "meta": {...}}. Trata os dois casos no teu código.

Erros

Os erros vêm como {"error": "mensagem"}, com a mensagem em português.

HTTP	Quando
403	Sem acesso para editar: falta a sessão do dono ou o cookie de quem criou.
404	O projecto ou evento não existe, ou é um rascunho.
422	Dados inválidos ao adicionar (ex.: categoria inexistente, nome curto).
503	Escrita fechada durante a migração, ou servidor temporariamente ocupado. Tenta mais tarde; respeita `Retry-After` se vier.

Sem filtros → lista

GET /projectos
[ { "slug": "…", … }, … ]

Com filtros → envelope

GET /projectos?categoria=quinta-agroecologia
{
  "items": [ { "slug": "…", … } ],
  "meta": []
}

404Erro

{ "error": "Não encontrado" }

Registo

Changelog

2026-10-28 — Primeira versão pública da documentação.