REST API v1

REAL NOW · API publique

API REST authentifiée par jeton Bearer. Intelligence de marché agrégée + inventaire vérifié des courtiers + briefings IA. Réponses JSON, limites de taux basées sur les niveaux.

Authentification

Tous les points de terminaison nécessitent un jeton Bearer dans le Authorization header:

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

Comment obtenir une clé :

Enterprise users: en libre-service depuis les paramètres du compte.
PRO users: contactez l'administrateur pour émettre une clé en votre nom.
Free users: L'accès à l'API nécessite le niveau PRO+.

Les clés en texte brut sont affichées UNE SEULE FOIS lors de la création. Stockez-les dans un gestionnaire de secrets — elles ne peuvent pas être récupérées plus tard. En cas de perte, révoquez et créez-en une nouvelle.

Limites de taux

Par clé, par heure. Les compteurs se réinitialisent au début de chaque heure UTC.

Niveau	Limite horaire	Quotidien ~
free	—	Pas d'accès à l'API
pro	100	~2,400
enterprise	1,000	~24,000
admin	Illimité	—

Les réponses au-delà de la limite renvoient HTTP 429 avec retry_after_seconds.

Format d'erreur

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

Codes d'erreur courants :

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 portée: read

Vérifiez que la clé fonctionne + voyez votre niveau.

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 portée: read

Statistiques de marché agrégées par zone dans les 8 pays d'Amérique latine (GT, SV, HN, CR, BZ, DO, PA, BR). Utilisez ?country=XX pour filtrer.

Paramètre	Type	Par défaut	Description
`country`	string	GT	Code du pays

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} portée: read

Instantané détaillé pour une zone : médianes par type de propriété + chambre + opération, delta sur 30 jours, mix de sources.

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

GET /api/v1/listings portée: read

Inventaire vérifié des courtiers uniquement (broker_listings actifs). Les données extraites ne sont JAMAIS exposées via l'API.

Paramètre	Type	Description
`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	Pagination — 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 portée: read

Listez les 5 personas IA avec leur schéma d'entrée + vocabulaire de verdict.

POST /api/v1/briefings/{persona} portée: write

Générez un briefing IA. Compte dans le quota mensuel du propriétaire de la clé (comme l'interface web). Les accès en cache de 24h ne consomment pas de 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}}

Journal des modifications

v1.0 · 2026-05-07 — Première version. 6 points de terminaison. Authentification par jeton porteur. Limites de taux par niveau.