Levar a agenda

Os dados em bruto

A agenda sai em formatos que outras máquinas leem: RSS para leitores de notícias, iCalendar para calendários, JSON para quem quer montar a sua própria página. É a agenda — o que está para vir. O arquivo das edições passadas dos ciclos vive nas páginas deles e não sai por aqui; quem o quiser, escreva.

Não é preciso chave nem registo. Os endereços abaixo respondem a qualquer pedido, de qualquer origem — e são para quem quer montar a lista com o seu próprio desenho. Quem só procura uma caixa pronta para colar não precisa de escrever código nenhum: está aqui em cima.

Endereços globais

https://coreto-sage.vercel.app/feed.xml

RSS 2.0 com os próximos 50 eventos dos 11 concelhos.

https://coreto-sage.vercel.app/agenda.ics

Calendário iCalendar com os próximos 100 eventos. Para subscrever, não para descarregar uma vez.

https://coreto-sage.vercel.app/api/events

A agenda em JSON, com filtros. É a base do widget e de qualquer integração.

https://coreto-sage.vercel.app/sitemap.xml

Mapa do sítio: as páginas fixas, os 11 concelhos, os espaços, os ciclos com programação e os eventos por acontecer. O que já passou não entra — um mapa do sítio é para o que se pode visitar.

Por concelho

Cada concelho tem os seus dois endereços. O padrão é /feed/<concelho>.xml e /agenda/<concelho>.ics.

Cada evento tem também o seu próprio calendário, em /evento/<endereço>/agenda.ics — é o botão «adicionar ao calendário» da ficha.

A API em JSON

GET /api/events devolve { events, total, page, limit, license, attribution, documentation }. Aceita pedidos de qualquer origem (CORS aberto) e responde sempre em UTF-8. Um parâmetro inválido devolve 400 com a lista dos parâmetros aceites dentro da própria resposta.

Cada evento traz as colunas do cartão e, ao lado dos identificadores, o que eles querem dizer: municipality_name, category_name, venue_name, o updated_at e as sessions com data, hora de início e hora de fim. Sem isso, quem integra ficava com venue_id e sem forma de saber de que espaço se trata.

https://coreto-sage.vercel.app/api/events?municipality=tomar&category=musica&free=1&limit=10

{
  "events": [
    {
      "id": "…",
      "slug": "concerto-de-ano-novo-tomar",
      "title": "Concerto de Ano Novo",
      "description_short": "A Banda dos Bombeiros abre o ano no Cine-Teatro.",
      "municipality_id": "tomar",
      "venue_id": "cine-teatro-paraiso",
      "location_name": null,
      "category_slug": "musica",
      "date_start": "2027-01-01",
      "date_end": "2027-01-01",
      "is_free": true,
      "price_display": null,
      "image_url": "…",
      "image_alt": "…",
      "wheelchair_accessible": true,
      "audience": "all_ages",
      "url": "https://coreto-sage.vercel.app/evento/concerto-de-ano-novo-tomar"
    }
  ],
  "total": 37,
  "page": 1,
  "limit": 10
}

Sem nos deitar abaixo

• Os feeds são recalculados de hora a hora. Ir buscá-los mais vezes do que isso não traz nada de novo.
• Não há limite publicado nem chaves a distribuir. Há bom senso: um pedido por minuto por feed é muito mais do que suficiente.
• Identifiquem-se no User-Agent com um nome e um contacto. É assim que vos conseguimos avisar em vez de vos bloquear.
• Precisam da exportação completa e não de uma janela dos próximos eventos? Escrevam — é mais barato para os dois lados do que percorrer a paginação toda.

Licença