Radar Perene / api/docs

Public API & widget

Radar Perene's Today's reading is available as a public JSON endpoint and embeddable widget. No signup, no API key, no per-user rate limits. Attribution required.

This documentation covers the endpoint, the response schema, three widget sizes, and the usage policy.

1. Endpoint

GET https://radarperene.com/api/todays-reading.json

Response: `application/json`. CDN cache: 4 hours. CORS: open (any origin). Refresh: daily, at Brazilian market close.

2. Call example

curl -s https://radarperene.com/api/todays-reading.json | jq

Sample response:

{
  "reference_date": "2026-06-04",
  "risk_br_score": 38.1,
  "regime_br": "moderately_defensive",
  "global_regime_score": 51.6,
  "regime_global": "neutral",
  "featured_lens": "wealth",
  "analog": "2018-09",
  "visible_components": {
    "reits_ibov_percentile": 78,
    "finance_ibov_percentile": 22,
    "vale_gold_percentile": 35
  },
  "divergences": ["BR defensive × Global neutral — contained reading"],
  "cadence": "daily",
  "updated_at": "2026-06-04T19:00:00-03:00",
  "methodology": "https://radarperene.com/methodology",
  "disclaimer": "Descriptive reading. Not advice or recommendation. Consult a licensed professional."
}

3. Response schema

Field	Type	Description
`reference_date`	`string` (ISO 8601 — `YYYY-MM-DD`)	Reading close date.
`risk_br_score`	`number` (0–100)	Brazil Regime aggregate score.
`regime_br`	`string` (enum)	Brazil Regime categorical bucket: `strong_risk_off` · `moderate_risk_off` (`moderately_defensive`) · `neutral` · `moderate_risk_on` · `broad_risk_on`.
`global_regime_score`	`number` (0–100)	Global Regime aggregate score.
`regime_global`	`string` (enum)	Global Regime categorical bucket, same set.
`featured_lens`	`string` (enum)	Lens pressing the aggregate reading most: `wealth` · `macro` · `institutional` · `real_estate` · `electoral`.
`analog`	`string` or `null`	Slug of the analog historical window (e.g., `2018-09`), or `null` when similarity is insufficient.
`visible_components`	`object`	Map of editorially exposed percentiles. Weights and formulas are not exposed by design (see Methodology §2.4).
`divergences`	`array<string>`	Relevant cross-axis divergences of the day.
`cadence`	`string`	Always `"daily"` for this endpoint.
`updated_at`	`string` (ISO 8601 with timezone)	Snapshot timestamp.
`methodology`	`string` (URL)	Link to the canonical methodology page.
`disclaimer`	`string`	Required notice when the output is displayed publicly.

Fields may be added in future versions without breaking compatibility. Existing fields will not be removed without a 90-day declared deprecation.

4. Embeddable widget — three sizes

All widgets render crawler-readable static HTML (content does not depend on JavaScript).

Small (300×120 px) — Risk-BR score and bucket only:

<iframe
  src="https://radarperene.com/widget/todays-reading?size=small&theme=light"
  width="300" height="120"
  frameborder="0"
  loading="lazy"
  title="Radar Perene — Today's reading">
</iframe>

Medium (480×280 px) — score + regime + analog + one-line comment:

<iframe
  src="https://radarperene.com/widget/todays-reading?size=medium&theme=light"
  width="480" height="280"
  frameborder="0"
  loading="lazy"
  title="Radar Perene — Today's reading">
</iframe>

Large (720×440 px) — full reading including divergences and visible percentiles:

<iframe
  src="https://radarperene.com/widget/todays-reading?size=large&theme=light"
  width="720" height="440"
  frameborder="0"
  loading="lazy"
  title="Radar Perene — Today's reading">
</iframe>

Optional parameters:

`theme=light | dark` (default: `light`).
`lang=pt | en` (default: detected from visitor's Accept-Language).

Automatic citation to Radar Perene is rendered inside the widget. Removing it is not permitted.

5. Usage policy

Summary. Full terms at /terms §6.

Free. No key, no signup, no per-user rate limit.
Mandatory attribution: "Source: Radar Perene" with a clickable link to the URL of origin. The widget already carries the attribution.
Commercial use permitted under the same attribution.
Output modification permitted if the citation specifies that the data has been processed.
Prohibited: reselling the output as your own without attribution; generating clearly abusive call volume; using for false attribution of advice; training proprietary AI models on the full corpus without authorization.

6. Versioning

The API follows semantic versioning. This is v1.

Changes that add fields: minor (v1.x.x → v1.(x+1).0). Compatibility preserved.
Changes that alter the semantics of existing fields: major (v1 → v2). Announced 90 days in advance. Old version remains accessible during transition at `/api/v1/todays-reading.json` (the current URL without prefix always aliases the latest stable version).

7. No formal SLA

Radar Perene does not offer a contractual SLA for the public endpoint — it is a free service. We employ reasonable efforts to keep the endpoint available with aggressive CDN caching. In case of prolonged incident, the main page (/) carries a notice.

For an SLA, consider the Founder Access plan (authenticated platform access with applicable SLA on the core services).

8. Support

Technical questions about the API or the widget: [contact to be defined]@radarperene.com. No response-time promise for free-tier use; responses in order of arrival per solo operator capacity.

---