REST API v1

REAL NOW · API Pubblica

REST API autenticata con token Bearer. Intelligenza di mercato aggregata + inventario broker verificato + briefing AI. Risposte JSON, limiti di velocità basati su livelli.

Autenticazione

Tutti gli endpoint richiedono un token Bearer nel Authorization header:

# Request
curl -H "Authorization: Bearer rn_live_xxxxxxxxxxxxxxxxxxxxxxxxx" \
     https://realnow.com/api/v1/health

Come ottenere una chiave:

Enterprise users: self-service da impostazioni account.
PRO users: contatta l'amministratore per emettere una chiave per tuo conto.
Free users: L'accesso API richiede il livello PRO+.

Le chiavi in testo semplice sono mostrate UNA VOLTA alla creazione. Conservale in un gestore di segreti — non possono essere recuperate in seguito. Se perse, revoca e crea una nuova.

Limiti di velocità

Per chiave, per ora. I contatori si azzerano all'inizio di ogni ora UTC.

Livello	Limite orario	Giornaliero ~
free	—	Nessun accesso API
pro	100	~2,400
enterprise	1,000	~24,000
admin	Illimitato	—

Le risposte oltre il limite restituiscono HTTP 429 con retry_after_seconds.

Formato errore

{
  "ok": false,
  "error": "rate_limit",
  "message": "Hourly rate limit reached (100 req/h for tier pro).",
  "limit": 100,
  "used": 100,
  "retry_after_seconds": 1842
}

Codici di errore comuni:

auth_required — 401, missing key
invalid_key — 401, key revoked or owner inactive
scope_denied — 403, key lacks the required scope
rate_limit — 429, hourly limit hit
not_found — 404, no such resource

Endpoints

GET /api/v1/health ambito: read

Verifica se la chiave funziona + scopri il tuo livello.

curl -H "Authorization: Bearer $RN_KEY" \
  https://realnow.com/api/v1/health
# {"ok":true,"service":"real-now-api","version":"v1","tier":"pro",...}

GET /api/v1/zones ambito: read

Statistiche di mercato aggregate per zona in tutti gli 8 paesi LATAM (GT, SV, HN, CR, BZ, DO, PA, BR). Usa ?country=XX per filtrare.

Parametro	Tipo	Predefinito	Descrizione
`country`	string	GT	Codice paese

curl -H "Authorization: Bearer $RN_KEY" \
  https://realnow.com/api/v1/zones
# {"ok":true,"count":25,"zones":[
#   {"zone":"Zona 1","median_ppm2_usd":1340.5,"n_active":420,"median_dom":31,...},
#   ...
# ]}

GET /api/v1/zone/{slug} ambito: read

Panoramica dettagliata per una zona: mediane per tipo di proprietà + camere da letto + operazione, variazione 30 giorni, mix di fonti.

curl -H "Authorization: Bearer $RN_KEY" \
  https://realnow.com/api/v1/zone/zona-10

GET /api/v1/listings ambito: read

Solo inventario verificato di broker (broker_listings attivi). I dati estratti non sono MAI esposti tramite API.

Parametro	Tipo	Descrizione
`zone`	string	Zona N
`country`	string	GT (default)
`operation`	string	Venta \| Renta
`property_type`	string	Apartamento, Casa, Terreno, …
`price_min` / `price_max`	number	USD bounds
`limit` / `offset`	int	Paginazione — limite 1-200

curl -H "Authorization: Bearer $RN_KEY" \
  "https://realnow.com/api/v1/listings?zone=Zona+10&operation=Venta&price_max=200000"

GET /api/v1/briefings/personas ambito: read

Elenca le 5 personalità AI con il loro schema di input + vocabolario di verdetti.

POST /api/v1/briefings/{persona} ambito: write

Genera un briefing AI. Conta contro la quota mensile del proprietario della chiave (come l'interfaccia web). I cache hit entro 24h non consumano quota.

curl -X POST -H "Authorization: Bearer $RN_KEY" \
     -H "Content-Type: application/json" \
     -d '{"zone":"Zona 10","profile":"cash"}' \
     https://realnow.com/api/v1/briefings/inversor
# Returns: {"ok":true,"verdict":"Comprar","confidence":"Alta",
#           "headline":"Zona 10 ofrece yield bruto del 7.0%...",
#           "body_md":"## Veredicto\n**Comprar** · Confianza: Alta\n...",
#           "usage":{"used":3,"quota":20,"unlimited":false}}

Registro modifiche

v1.0 · 2026-05-07 — Rilascio iniziale. 6 endpoint. Autenticazione con token Bearer. Limiti di velocità per livello.