Made-up example. Cinco Chaminés is an invented company: the homes, prices, availability and bookings are simulated, and the pictures are AI-generated. The weather, sea, UV and events are real, read live from data.promptugal.news. What is this site?

Cinco Chaminésholiday homes in the Algarve (a made-up example)

Use the data

Cinco Chaminés is a made-up example, but the weather, sea, UV, warnings and events on its pages are real. They come from public JSON files that anyone can read. This page shows where they are, how to read them, the terms that come with them, and how a real business could build something like this site.

What data.promptugal.news is

data.promptugal.news is the raw data behind the PrompTugal.news sites: public data about Portugal, collected by code on a schedule and served as plain JSON files. There are no articles and no model in the loop. Every file is a GET request with no key, and any website may read it from a visitor's browser (CORS is open). The catalogue lists every source with its addresses, and the contract says the version 1 addresses stay for the life of version 1.

Each source has three files in its own folder, https://data.promptugal.news/api/v1/<source>/: latest.json (the records from the last read, with their provenance), reads.json (a log of the collector's runs, newest first: address, HTTP status, size, checksum and whether the bytes changed; it logs runs, not values) and card.json (who publishes the data, the terms, the schedule). Read the card before you reuse a value.

The five sources this site reads

SourceWhatPublisherFilesStatus now
ipma-city-forecastsFive-day forecasts by place (today and the next four days)IPMAlatest, reads, cardnot read yet
ipma-warningsYellow, orange and red weather warnings by areaIPMAlatest, reads, cardnot read yet
ipma-seaWaves, period, direction and sea temperature, three days aheadIPMAlatest, reads, cardnot read yet
ipma-uvUV index forecast by place and dayIPMAlatest, reads, cardnot read yet
events-ptPublic events on now or in the next 60 days, as schema.org Event recordsCâmara Municipal de Lagos, Teatro das Figuras (Faro), Câmara Municipal de Tavira (and the Lisbon agenda, not read at the time of writing)latest, reads, cardnot read yet

Two helper files are also useful: /api/v1/events/by-place/lagos.json (the same events, for one place; also faro and tavira; the index lists every Algarve place, most with none) and /api/v1/by-place/now/lagos.json (for each of the 16 Algarve municipalities, the nearest IPMA values already picked out; good for a "now" strip, not for a stay).

Addresses from data.promptugal.news's llms.txt and catalogue; each address on this page answered HTTP 200 to curl on 18 November 2026 at 16:30 UTC. The status column is filled in your browser from the catalogue when the page opens: each source's status and read_at.

The status column needs JavaScript; without it, see the catalogue directly.

The Algarve in these files

The files cover all of Portugal; the Algarve is a small part. What exists for it, as read on 18 November 2026:

So each made-up home on this site uses the nearest place that has data: the Salt House in Tavira shows Faro's forecast, for example, and says so. The mapping is in /data/homes.json.

Copy and paste

JavaScript, in a browser or Node 18 and later

const base = 'https://data.promptugal.news/api/v1';

// Faro's five-day forecast (IPMA). Match the place by id.
const f = await (await fetch(`${base}/ipma-city-forecasts/latest.json`)).json();
const faro = f.cities.find(c => c.id === 1080500);
for (const d of faro.days)
  console.log(d.date, d.t_min_c, d.t_max_c, `${d.rain_prob_pct}% rain`);
console.log('Source: IPMA, read', faro.read_at);

// Warnings for the Algarve (area FAR). None listed means no yellow, orange or red warning.
const w = await (await fetch(`${base}/ipma-warnings/latest.json`)).json();
const far = w.active.filter(a => a.area === 'FAR');
console.log(far.length
  ? far.map(a => `${a.level} ${a.type}, ${a.start} to ${a.end}`).join('\n')
  : 'No warning for the Faro district');

// Events in Lagos between two dates (inclusive, local dates).
const from = '2026-11-21', to = '2026-11-28';
const e = await (await fetch(`${base}/events/by-place/lagos.json`)).json();
const on = e.events.filter(ev =>
  ev.startDate.slice(0, 10) <= to && (ev.endDate || ev.startDate).slice(0, 10) >= from);
for (const ev of on) console.log(ev.startDate, ev.name, ev.url);

curl and jq, in a terminal

# Faro's forecast, one line per day
curl -s https://data.promptugal.news/api/v1/ipma-city-forecasts/latest.json \
  | jq -c '.cities[] | select(.id == 1080500) | .days[] | {date, t_min_c, t_max_c, rain_prob_pct}'

# Active warnings for the Algarve (area FAR)
curl -s https://data.promptugal.news/api/v1/ipma-warnings/latest.json \
  | jq -c '.active[] | select(.area == "FAR") | {level, type, start, end}'

# Events in Lagos from 21 to 28 November 2026
curl -s https://data.promptugal.news/api/v1/events-pt/latest.json \
  | jq -c '.places.lagos[]
      | select(.startDate[0:10] <= "2026-11-28" and ((.endDate // .startDate)[0:10]) >= "2026-11-21")
      | {startDate, name, url}'

# Who publishes a source, and on what terms
curl -s https://data.promptugal.news/api/v1/ipma-uv/card.json | jq '{publisher, terms: .terms.summary}'

Each example was run against the live files on 18 November 2026 at about 16:30 UTC and returned data. The dates are examples: events-pt only holds events from now to 60 days ahead, so change them to dates in that window.

How to read a source card

Every source has a card.json. These are the fields to show beside any figure you reuse:

publisher
Who publishes the data, for example "IPMA, Instituto Português do Mar e da Atmosfera". Name them beside every figure.
terms
terms.summary in plain English, terms.quote in the publisher's own words (with terms.quote_lang), terms.page where they were read, terms.republish (whether you may republish) and terms.open_question (anything not yet settled).
license
The licence of the file's structure: CC BY 4.0, held by PrompTugal.news. Every value inside keeps its source's own terms, which are stricter.
schedule.cadence
How often the collector is meant to read the source: hourly for the IPMA sources, every 6 hours for events-pt. Runs can be late; reads.json shows when they really happened.
read_at
Not on the card but on latest.json (and in the catalogue): the time the collector last read the source, in UTC. Show it with every figure.

The terms, as the cards give them

Staleness

A file is only as fresh as the collector's last run. Check read_at on latest.json, and status in the catalogue ("ok", "partly failed" or "archived"). In reads.json, runs[0].failed above 0 means the last run partly failed. This site calls an IPMA file stale after 2 hours and events after 12 hours, and says so beside the figure; those limits are our choice, not the publishers'. When a file is missing or stale, say so on the page. Never guess a value.

How a real business could build this

This is a proposal for how it could be done, not advice on a particular case.

  1. Start from your own homes. A small JSON file like /data/homes.json: each home with its town, and the nearest forecast place, sea coast, UV place and events place.
  2. Read the data in the visitor's browser. Fetch latest.json and card.json when the page opens, as in the examples above. Your site then holds no data and needs no server of its own.
  3. Show the source beside every figure: the publisher, the time read and the terms from the card, and a clear message when a file is missing or old.
  4. Keep your own calendar and bookings in your own system. On this site they are simulated; a real business needs a real booking and payment system, with its own terms and data protection.
  5. Or take the bookings from where they already are. A host who already lists homes on a holiday-rental booking platform could read the bookings from that service's calendar feed or its partner connection, where the service offers one, so the site and the platform show the same taken dates. This is a proposal: nothing on this site connects to any booking service, and we name such services by type only.
  6. Host it as a static site. Most of the cost is the static host and a domain name; the data files themselves cost nothing to read.

What it must check first:

This page is part of a made-up example: Cinco Chaminés and its homes are invented. The data sources, their addresses and their terms are real, as read on 18 November 2026.

Ask the agent (a simulation: pre-written answers, no live model)