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.
- llms.txt: the data site in one text file, for people and agents.
- Catalogue (
api/v1/index.json): every source with its title, publisher, cadence,read_at,statusand addresses. Read addresses from here rather than building them by hand. - OpenAPI 3.1 (
api/v1/openapi.json): every path with a schema. - Contract (
api/v1/README.md).
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
| Source | What | Publisher | Files | Status now |
|---|---|---|---|---|
ipma-city-forecasts | Five-day forecasts by place (today and the next four days) | IPMA | latest, reads, card | not read yet |
ipma-warnings | Yellow, orange and red weather warnings by area | IPMA | latest, reads, card | not read yet |
ipma-sea | Waves, period, direction and sea temperature, three days ahead | IPMA | latest, reads, card | not read yet |
ipma-uv | UV index forecast by place and day | IPMA | latest, reads, card | not read yet |
events-pt | Public events on now or in the next 60 days, as schema.org Event records | Câ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, card | not 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:
- Forecasts (
ipma-city-forecasts): four places with area"FAR": Faro1080500, Loulé1080800, Portimão1081100and Sagres1081505. Match byid, not by name, because names carry accents. - Warnings (
ipma-warnings): one area for the whole Algarve,"FAR"(the Faro district). No activeFARentry means no yellow, orange or red warning. - Sea (
ipma-sea): two coasts, "Faro, costa"1080526and "Sagres, costa"1081526. - UV (
ipma-uv): Faro1080500, and1081525, which the file leaves unnamed and the by-place files call Sagres. - Events (
events-pt): three places,lagos,faroandtavira, underplaces, an object keyed by place, each holding a list of events.
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.
termsterms.summaryin plain English,terms.quotein the publisher's own words (withterms.quote_lang),terms.pagewhere they were read,terms.republish(whether you may republish) andterms.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.jsonshows 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
- IPMA (forecasts, warnings, sea, UV): "free to copy and use for personal or public use if the use has no profit-making or offensive purpose; always name IPMA as the source." So: always name IPMA, and no profit-making use. A real holiday-rental business making money would need IPMA's permission first.
- events-pt: no reuse licence or terms page was found for any of the hosts, so the card says "reference use only, name the source, link to the event, no AI training", and leaves to a person whether that is enough to republish. On this site an event shows only its name, date, venue, source and a link to the organiser's page, and you are asked to check the details there.
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.
- 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.
- Read the data in the visitor's browser. Fetch
latest.jsonandcard.jsonwhen the page opens, as in the examples above. Your site then holds no data and needs no server of its own. - 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.
- 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.
- 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.
- 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:
- The terms of every source. IPMA's terms rule out profit-making use, so a business needs IPMA's permission to show its data. events-pt is reference use only; showing events commercially needs each organiser's permission.
- Permission for commercial use of anything it did not make, in writing.
- Camera operators' permission before showing any live camera on its site; until then, link to the operator's page, as Live from the Algarve does.
- Local accommodation registration. Holiday lets in Portugal must be registered as local accommodation (alojamento local) with the municipality, and the registration number shown. Check the current rules with the municipality before taking guests.
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.