Integration guide
Six rules that prevent most of what goes wrong in an integration: limits hit, data re-fetched, and readers misled about how current what they are seeing is. The figures on this page are the ones the service applies.
The six rules
Incêndio · Sintra
Fonte: ANEPC · via api.emcurso.pt · 14:32
Say where it came from
Whoever reads your application has to be able to tell where the data came from and how recent it is. This is not a courtesy: an occurrence shown without a source or a time reads as yours and as current.
Do not poll faster
Each family of endpoints has an interval below which the response does not change. Polling faster than that spends quota to receive exactly the same body.
The response tells you what is left
Every response says what is left in each window. An integration that reads them slows down before hitting the limit; one that does not discovers the limit by receiving a 429.
Wait longer each time
On a 429 or a 5xx, wait and retry at growing intervals with a random jitter. Without the jitter, every client that failed at the same moment comes back in the same second.
Say who you are
A User-Agent that names the integration and allows contact. It is how we tell a legitimate spike from abuse — and how we warn you before limiting the key.
Not every error is alike
A 404 is not a 429 and neither is a 500. Treating everything as “it failed” makes the application retry what will never work and give up on what would have worked on the second attempt.
Show the source and the time of the last update beside the data, not in a footer or an about page. This is the minimum form:
<p class="attribution">
Fonte: ANEPC · via api.emcurso.pt · {{lastUpdated}}
</p>Below these intervals the response is the same. These are the values the service applies, not a recommendation.
| Nature | Interval | Endpoints |
|---|---|---|
| Live occurrences | 30 s | /prociv/ |
| Traffic constraints | 1 min | /traffic/ |
| ICNF occurrence record | 5 min | /icnf/ocorrencia |
| Detection and context | 5 min | /fires/ · /context |
| Weather warnings | 10 min | /ipma/warnings |
| Forecast and risk | 30 min | /ipma/forecast · /ipma/fire-risk |
| Historical series and routes | 1 h | /icnf/ · /geo/route |
| Reference data | 24 h | /prociv/distritos · /geo/municipality-boundary |
On every response. When `Remaining` reaches zero, further requests get a 429 until the moment given in `Reset`.
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 47
X-RateLimit-Reset: 1735689600
Retry-After: 23The essentials: honour `Retry-After` where present, grow the interval, and add a random jitter.
async function call(url, attempt = 0) {
const res = await fetch(url, { headers });
if (res.ok) return res.json();
if (res.status === 429 || res.status >= 500) {
if (attempt >= 5) throw new Error(`gave up: ${res.status}`);
// Honour Retry-After where the server sends one.
const after = Number(res.headers.get("Retry-After"));
const backoff = Number.isFinite(after)
? after * 1000
: 2 ** attempt * 1000;
// Jitter: without it, every client that failed together
// comes back in the same second.
await sleep(backoff + Math.random() * 1000);
return call(url, attempt + 1);
}
throw new Error(`request failed: ${res.status}`);
}The integration's name, its version, and a way to make contact. Keep it stable across versions.
User-Agent: CamaraDeSintra-Despacho/1.4 (+https://cm-sintra.pt)| Code | Means | Do |
|---|---|---|
| 200 | The request succeeded | Nothing. Check the quota headers. |
| 400 | Invalid parameter | Fix the request. Retrying will not help. |
| 401 | Missing or invalid key | Check the Authorization header. Do not retry in a loop. |
| 403 | Endpoint outside the key's scope | Request the extension in the console. |
| 404 | The resource does not exist | Treat as absence, not as an error. |
| 429 | Window limit reached | Back off. Honour Retry-After. |
| 503 | Upstream source unavailable | Retry with backoff. It is not your key. |