API · Finodex

01 · Começa por aqui

Três pedidos. Três minutos.

Sem SDK obrigatório. Funciona em terminal, JavaScript, Python, ou o que quiseres atirar a um endpoint HTTPS.

# 1. estatísticas nacionais
$ curl http://finodex.pt/api/stats

# 2. preços por distrito
$ curl http://finodex.pt/api/districts

# 3. últimas entradas aprovadas
$ curl "http://finodex.pt/api/entries?limit=10"

const r = await fetch("http://finodex.pt/api/districts");
const d = await r.json();

// encontrar o distrito mais barato
const top = d.sort((a, b) => a.avg_price - b.avg_price)[0];
console.log(`${top.district}: €${top.avg_price.toFixed(2)}`);

import requests

r = requests.get("http://finodex.pt/api/stats")
d = r.json()

print(f"Média nacional: €{d['national']['avg']:.2f}")
# → Média nacional: €1.85

library(httr); library(jsonlite)

r  <- GET("http://finodex.pt/api/districts")
df <- fromJSON(content(r, "text"))

# ordenar por preço médio
df[order(df$avg_price), ]

02 · Catálogo

Cinco endpoints. Mais não fazem falta.

Todos respondem em <200 ms. CORS aberto — chama diretamente do browser.

base · http://finodex.pt/api

GET /stats Média nacional, mín, máx e total de entradas. json

GET /districts Lista dos 18 distritos com a última média, mín, máx e n. json

GET /entries Entradas aprovadas. Suporta ?district= e ?limit=. json

GET /live As últimas 10 submissões aprovadas. Ideal para feeds em tempo real. json

GET /random[/:district] Bar aleatório com menu. Exemplo: /random/porto. json

03 · Esquema

O que vais receber.

Estrutura estável. Campos novos são aditivos — nunca quebramos o que já funciona.

{ "district": "Lisboa", // nome canónico "avg_price": 1.84, // €, média "min_price": 1.10, // € mínimo "max_price": 3.20, // € máximo "count": 412 // entradas válidas } // Objeto entrada { "price": 1.20, // € "brand": "Super Bock", "size_liters": 0.2, // 20cl "venue": "Café Central", "city": "Lisboa", "approved_at": "2026-05-17" // ISO-8601 }

Parâmetro	Tipo	Descrição
district	string	Filtrar por distrito. Ex: Lisboa, Porto.
limit	number	Número de resultados. Default 50, máx 50.
brand	string	Filtrar por marca. Super Bock, Sagres, ou Outra.
size	number	Tamanho em litros. 0.2 (fino), 0.33 (imperial).
callback	string	JSONP para browsers antigos. Não recomendado.

04 · Justiça pelo balcão

O limite é amigável.

Não pomos chave porque confiamos em ti. Não abuses, e não precisamos de o tornar mais chato. Tudo conta por IP.

Pedidos / minuto

120

Cabeçalhos X-RateLimit-* em todas as respostas.

Pedidos / dia

20 mil

Para mais, manda um email — quase de certeza dizemos que sim.

Latência (p50)

68 ms

p99 abaixo de 240 ms. Cache no edge quando possível.

Uptime · 90d

99.9 %

Sem rateios silenciosos. Se partir, sabemos antes de ti.

05 · Coisinhas que ajudam

Pequenos truques que poupam tempo.

— 01

Try it live

Todos os endpoints têm um botão ▶ Experimentar — corre no browser, sem instalar nada. Os dados são os reais.

— 02

CORS aberto

Podes chamar diretamente do browser — sem proxy, sem CORS errors. Usamos Access-Control-Allow-Origin: *.

— 03

Dados validados

Só devolvemos entradas aprovadas manualmente. Nenhum spam, nenhum preço fictício. A qualidade é o ponto.

Constrói algo.
E conta-nos.

Se fizeres alguma coisa com a API — site, bot, papel, gráfico, qualquer coisa — manda. Se partires alguma coisa, também: abrimos uma issue e ajudamos a arranjar.

+ Submeter preço geral@finodex.pt

curl-shaped love letter

$ curl http://finodex.pt/api/manifesto

{
  "data":     "é tua",
  "quem":     "quem submeter",
  "porque":   "o fino é património",
  "custo":    0
}

Dados abertos. Sem chave. Sem mexer com ninguém.