REST API v1

REAL NOW · API pública

API REST autenticada con token Bearer. Inteligencia de mercado agregada + inventario de corredores verificado + resúmenes de IA. Respuestas JSON, límites de tasa basados en niveles.

Datos del mercado visible: anuncios publicados a precio de lista. No incluye preventa ni ventas fuera de listado.

Autenticación

Todos los endpoints requieren un token Bearer en el Authorization header:

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

Cómo obtener una clave:

Enterprise users: autoservicio desde configuración de la cuenta.
PRO users: contactar al administrador para emitir una clave en su nombre.
Free users: El acceso a la API requiere el nivel PRO+.

Las claves en texto plano se muestran UNA VEZ al crearse. Guárdelas en un gestor de secretos — no se pueden recuperar más tarde. Si se pierden, revoque y cree una nueva.

Límites de tasa

Por clave, por hora. Los contadores se reinician al inicio de cada hora UTC.

Plan	Límite por hora	Diario ~
free	—	Sin acceso a la API
pro	100	~2,400
enterprise	1,000	~24,000
admin	Ilimitados	—

Las respuestas por sobrepaso de límite devuelven HTTP 429 con retry_after_seconds.

Formato de error

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

Códigos de error comunes:

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

Verifique que la clave funcione + vea su nivel.

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

Estadísticas de mercado agregadas por zona en los 8 países de LATAM (GT, SV, HN, CR, BZ, DO, PA, BR). Use ?country=XX para filtrar.

Parámetro	Tipo	Por defecto	Descripción
`country`	string	GT	Código de país

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

Instantánea detallada para una zona: medianas por tipo de propiedad + dormitorio + operación, delta de 30d, mezcla de fuentes.

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

GET /api/v1/listings scope: read

Solo inventario de corredores verificado (active broker_listings). Los datos extraídos NUNCA se exponen a través de la API.

Parámetro	Tipo	Descripción
`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	Paginación — límite 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 scope: read

Liste las 5 personalidades de IA con su esquema de entrada + vocabulario de veredicto.

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

Genere un resumen de IA. Cuenta contra la cuota mensual del propietario de la clave (igual que la interfaz web). Los aciertos de caché de 24h no consumen cuota.

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

Historial de cambios

v1.0 · 2026-05-07 — Lanzamiento inicial. 6 endpoints. Autenticación con token Bearer. Límites de tasa por nivel.