REST API v1 — 文档

认证

所有端点都需要在 Authorization header:

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

如何获取密钥：

Enterprise users: 自助服务来自账户设置.
PRO users: 联系管理员代表您发放密钥。
Free users: API访问需要PRO+级别。

明文密钥在创建时仅显示一次。请将其存储在机密管理器中——无法恢复。如丢失，请撤销并创建新密钥。

速率限制

每个密钥，每小时。计数器在每个UTC小时的开始重置。

层级	每小时限制	每日 ~
free	—	无API访问权限
pro	100	~2,400
enterprise	1,000	~24,000
admin	无限制	—

超限响应返回 HTTP 429 附带 retry_after_seconds.

错误格式

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

常见错误代码：

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 范围: read

验证密钥是否有效 + 查看您的级别。

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 范围: read

汇总所有8个拉美国家（GT, SV, HN, CR, BZ, DO, PA, BR）每个区域的市场统计数据。使用 ?country=XX 进行筛选。

参数	类型	默认	描述
`country`	string	GT	国家代码

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} 范围: read

单一区域的详细快照：按物业类型 + 卧室 + 操作的中位数，30天变化，来源组合。

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

GET /api/v1/listings 范围: read

仅限验证的经纪人库存（活跃的 broker_listings）。抓取的数据绝不通过API公开。

参数	类型	描述
`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	分页 — 限制 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 范围: read

列出5个AI角色及其输入模式 + 结论词汇。

POST /api/v1/briefings/{persona} 范围: write

生成AI简报。计入密钥所有者的月度配额（与网页UI相同）。24小时缓存命中不消耗配额。

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

更新日志

v1.0 · 2026-05-07 — 初始发布。6个端点。Bearer-token认证。级别速率限制。

REAL NOW · 公共API

认证

速率限制

错误格式

Endpoints

更新日志

ARI