REST API v1

REAL NOW · Öffentliches API

REST API mit Bearer-Token-Authentifizierung. Aggregierte Marktintelligenz + verifizierte Maklerbestände + KI-Briefings. JSON-Antworten, ratenbasierte Begrenzungen.

Authentifizierung

Alle Endpunkte erfordern ein Bearer-Token im Authorization header:

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

So erhalten Sie einen Schlüssel:

Enterprise users: Selbstbedienung über Kontoeinstellungen.
PRO users: Kontaktieren Sie den Administrator, um einen Schlüssel in Ihrem Namen auszustellen.
Free users: API-Zugriff erfordert PRO+ Stufe.

Klartextschlüssel werden EINMAL bei der Erstellung angezeigt. Speichern Sie sie in einem Geheimnis-Manager — sie können später nicht wiederhergestellt werden. Bei Verlust widerrufen und einen neuen erstellen.

Ratenbegrenzungen

Pro Schlüssel, pro Stunde. Zähler werden zu Beginn jeder UTC-Stunde zurückgesetzt.

Stufe	Stündliches Limit	Täglich ~
free	—	Kein API-Zugriff
pro	100	~2,400
enterprise	1,000	~24,000
admin	Unbegrenzt	—

Antworten über dem Limit geben zurück HTTP 429 mit retry_after_seconds.

Fehlerformat

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

Häufige Fehlercodes:

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 Umfang: read

Überprüfen Sie, ob der Schlüssel funktioniert + sehen Sie Ihren Tarif.

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 Umfang: read

Aggregierte Marktstatistiken pro Zone in allen 8 LATAM-Ländern (GT, SV, HN, CR, BZ, DO, PA, BR). Verwenden Sie ?country=XX zum Filtern.

Parameter	Typ	Standard	Beschreibung
`country`	string	GT	Ländercode

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} Umfang: read

Detaillierte Momentaufnahme für eine Zone: Mediane nach Immobilientyp + Schlafzimmer + Betrieb, 30-Tage-Delta, Quellmix.

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

GET /api/v1/listings Umfang: read

Nur verifiziertes Maklerinventar (aktive broker_listings). Gescrapte Daten werden NIEMALS über die API offengelegt.

Parameter	Typ	Beschreibung
`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	Paginierung — Limit 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 Umfang: read

Listen Sie die 5 KI-Personas mit ihrem Eingabeschema + Urteilswortschatz auf.

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

Erstellen Sie ein KI-Briefing. Zählt gegen das monatliche Kontingent des Schlüsselinhabers (wie die Web-UI). 24h-Cache-Treffer verbrauchen kein Kontingent.

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}}

Änderungsprotokoll

v1.0 · 2026-05-07 — Erstveröffentlichung. 6 Endpunkte. Bearer-Token-Authentifizierung. Tarifbegrenzungen.