Theblueground API

Access real-time furnished apartment listings, pricing, amenities, and availability calendars from Theblueground with this API. Ideal for real estate analysts, travel tech developers, and relocation platforms seeking structured, up-to-date rental data.

原始信息汇总

Theblueground API 数据集概述

基本信息

• 数据集名称: Theblueground API
• 类别: Travel
• API提供者: kakoto
• API版本: 1.0.0 (current)
• 流行度: 8.7 Popularity
• 服务等级: 100% Service Level
• 延迟: 2079ms Latency
• 测试通过率: 100% Test

订阅计划与定价

• BASIC: $0.00 / mo
• PRO: $15.00 / mo
• ULTRA: $49.00 / mo
• MEGA: $139.00 / mo

概述

该API提供对Theblueground平台实时数据的程序化访问，可获取带家具公寓的房源列表、定价、设施和可用性日历。适用于房地产分析师、旅行科技开发者和寻求结构化、最新租赁数据的搬迁平台。

核心功能

• 访问全球带家具、可随时入住的公寓数据，适用于中长期住宿（通常一个月或更长时间）。
• 检索结构化房源信息，包括租金定价、设施、可用性日历、位置详情和预订规则。
• 支持构建租赁比较工具、为搬迁仪表板提供支持、进行带家具公寓定价的市场研究以及为旅行科技平台聚合库存。

响应结构

成功响应

json { "statusCode": 200, "messageCode": "OK", "data": [ /* array of results */ ] }

错误响应

json { "statusCode": 400, "messageCode": "BAD_REQUEST", "message": "Descriptive error message" }

常见状态码:

• 200 — 成功
• 400 — 错误请求（参数无效）
• 404 — 未找到房源或结果
• 500 — 内部服务器错误

API端点

1. 搜索房源

• 端点: GET /property/search
• 描述: 根据位置、日期范围和可选过滤器检索分页的可用房源列表。适用于不需要完整房源详情的发现和浏览用例。

输入参数

参数	必需	类型	描述
place_id	✅ 是	string	从Theblueground搜索URL提取的位置标识符
check_in	✅ 是	string	入住日期，格式为 YYYY-MM-DD
check_out	✅ 是	string	退房日期，格式为 YYYY-MM-DD
currency	否	string	定价的货币代码（例如 USD, EUR, MXN）
bedrooms	否	string	按卧室数量筛选
bathrooms	否	string	按浴室数量筛选
price_from	否	string	最低价格筛选
price_to	否	string	最高价格筛选
offset	否	string	大型结果集的分页偏移量

示例请求

GET /property/search?place_id=ct-eyJ0eXBlIjoiY2l0eSIsImxhdCI6MTkuNDMyNjA3NywibG5nIjotOTkuMTMzMjA4fQ&check_in=2026-04-21&check_out=2026-05-21&currency=USD&bedrooms=2

2. 通过URL获取房源详情

• 端点: POST /property/get-by-url
• 描述: 使用完整的Theblueground房源URL获取单个房源的全面信息。返回详细的设施、照片、预订日历、定价、房屋规则、描述等。

输入正文

字段	必需	类型	描述
url	✅ 是	string	Theblueground上房源页面的完整URL

示例请求

POST /property/get-by-url Content-Type: application/json

{ "url": "https://www.theblueground.com/p/furnished-apartments/atx-249" }

返回的关键字段

字段	描述
lowest_rent	最低可用价格及货币
booking_calendar.options	每日入住可用性及最短退房时间
amenities.apartment	单元内设施列表（空调、洗碗机、电视等）
amenities.building	楼宇级设施（游泳池、健身房、停车场）
amenities_config	付费附加服务，如带费用的宠物
rules	宠物、吸烟和活动政策
sleeping_arrangements	每间卧室的床型（例如 QUEEN）
photos	带 primary 标志的标记照片URL
description	介绍、空间、位置的富HTML描述
virtual_tour_url	Matterport 3D导览链接（如果可用）

使用指南与最佳实践

1. 以编程方式提取 place_id: place_id 是嵌入在Theblueground搜索URL中的base64编码JSON。可以解码它以了解其代表的地理坐标（city, neighborhood, lat/lng），从而实现无需手动浏览的地理定位。
2. 先搜索，后获取详情: /property/search 端点轻量，适合按日期、预算和房间数进行筛选。获得候选房源路径后，使用 /property/get-by-url 来丰富数据，获取完整的设施明细、日历和定价配置。
3. 遵守最短住宿要求: Theblueground主要针对中期住宿。booking_calendar.options 数组包含每个入住日期的 min_stay_nights 字段（通常为30晚）。确保您的日期范围查询考虑此点，以避免收到空结果或筛选后的结果。
4. 处理大型市场的分页: 搜索响应中的 totals 字段表示匹配房源的总数。在高库存城市，使用 offset 参数对所有结果进行分页。

常见错误场景

错误	可能原因	解决方案
400 Bad Request	缺少必需参数或日期格式无效	确保 place_id、check_in、check_out 存在且格式为 YYYY-MM-DD
404 Not Found	URL无效或房源未列出	验证房源URL是当前活跃的Theblueground列表
500 Internal Server Error	上游抓取失败	使用指数退避重试；房源页面可能暂时更改