跳转到主要内容
POST
市场数据
美国房产估值、租金估算、房产记录、出售及出租房源、邮编级市场统计和股票报价。选择操作,并提供地址、城市加州、邮编或股票代码。 所有操作返回规范化 output,以及最后一个 Run 的 id、provider 和生命周期 status。property_value、property_rent、market_stats、stock_quote 返回固定顶层字段;property_search、listings_sale、listings_rental 返回每行字段固定的 output.items[]。原生输出不在 output 中重复,保留在 Run 中,可通过 GET /v1/runs/:id 读取。数据提供商未报告的值为 null;房产金额为美元,股票报价包含 currency。 分别检查 result_status 和 status:前者为 success、no_result、error 或 pending。charge_usd 为本响应 runs 总费用,所有 Run 结算前为 null;runs[] 包含各自费用。指定数据提供商时不切换。对于 QUEUED/RUNNING,即 HTTP 202,在 API 服务地址上使用认证轮询 result_url。有意重试时复用相同 Idempotency-Key 和执行参数。

各操作输出

各操作的规范化字段。原生输出保留在 Run 中,可通过 GET /v1/runs/:id 读取。未报告的值为 null;有效空结果保留操作结构,各字段为 null 或 items 为 [],result_status 为 no_result。金额为美元,操作包含 currency 字段时除外。_date 为 YYYY-MM-DD,_at 为 ISO 8601 UTC,*_text 为原样返回的展示文本。
  • property_value: address, property_type, bedrooms, bathrooms, living_area_sqft ,居住面积, lot_size_sqft, year_built, latitude, longitude, estimated_value_usd, value_low_usd, value_high_usd, comparables_count ,估值所用的可比成交数
  • property_rent: address, property_type, bedrooms, bathrooms, living_area_sqft ,居住面积, lot_size_sqft, year_built, latitude, longitude, estimated_rent_usd ,月度, rent_low_usd, rent_high_usd, comparables_count ,估算所用的可比租赁数
  • property_search: items[]: property_id, address, property_type, bedrooms, bathrooms, living_area_sqft ,居住面积, lot_size_sqft, year_built, latitude, longitude, last_sale_price_usd, last_sale_date ,YYYY-MM-DD, owner_names[], owner_type, owner_mailing_address, owner_occupied
  • listings_sale: items[]: listing_id, address, property_type, bedrooms, bathrooms, living_area_sqft ,居住面积, lot_size_sqft, year_built, latitude, longitude, status, listing_type, listed_date ,YYYY-MM-DD, days_on_market, hoa_fee_usd ,月度 HOA 费用, mls_name, mls_number, agent {name, phone, email, website}, office {name, phone, email, website}, price_usd ,挂牌价
  • listings_rental: items[]: listing_id, address, property_type, bedrooms, bathrooms, living_area_sqft ,居住面积, lot_size_sqft, year_built, latitude, longitude, status, listing_type, listed_date ,YYYY-MM-DD, days_on_market, hoa_fee_usd ,月度 HOA 费用, mls_name, mls_number, agent {name, phone, email, website}, office {name, phone, email, website}, monthly_rent_usd
  • market_stats: zip, updated_at ,ISO 8601 UTC,RentCast 最近刷新汇总的时间, sale {average_price_usd, median_price_usd, average_price_per_sqft_usd, median_price_per_sqft_usd, average_days_on_market, median_days_on_market, total_listings, new_listings}, rental {average_rent_usd, median_rent_usd, average_rent_per_sqft_usd, median_rent_per_sqft_usd ,月租金, average_days_on_market, median_days_on_market, total_listings, new_listings}
  • stock_quote: symbol, name, exchange, currency, price ,常规时段最新价格,单位为 currency;Google Finance 报价可能延迟, change ,相对于上一常规收盘价的绝对变动,单位为 currency, change_percent ,相对于上一常规收盘价的百分点变动,1.5 表示 1.5%, extended_hours_session ,原样展示的时段标签,如 Pre-market 或 After hours,常规时段为 null, extended_hours_price, extended_hours_change、extended_hours_change_percent,盘前盘后报价相对于常规时段价格的变动,单位相同, as_of_text ,Google Finance 页面原样时间戳,不是 ISO 格式,也不是 price 的时间

请求头

idempotency-key
string
必填

为每次预期执行生成唯一值,推荐使用 UUID。使用同一个键和执行参数重试,可读取原 Run,避免再次扣费。使用同一个键但修改执行参数会返回 409;修改 task_id 或 metadata 不会更新原 Run。

Minimum string length: 1

请求体

application/json
action
enum<string>
必填

选择要获取的数据:

  • property_value 或 property_rent:提供 address。
  • property_search、listings_sale 或 listings_rental:提供 address、city 加 state,或 zip。
  • market_stats:提供 zip。
  • stock_quote:提供 symbol。
可用选项:
property_value,
property_rent,
property_search,
listings_sale,
listings_rental,
market_stats,
stock_quote
provider
enum<string> | null

默认为 auto,按 Glasser 偏好顺序选择第一家符合条件的数据提供商。指定的数据提供商必须支持请求且获得当前 API Key 的允许,不会切换到其他家。可用值见下方。

可用选项:
auto,
rentcast,
serpapi
address
string | null
Required string length: 1 - 300
city
string | null
Required string length: 1 - 100
state
string | null
Pattern: ^[A-Za-z]{2}$
zip
string | null
Pattern: ^\d{5}$
symbol
string | null
Required string length: 1 - 40
limit
integer | null

返回条数。请从较少条数开始:路由到的接口可能据此计费。各能力还会进一步限制上限。

必填范围: 1 <= x <= 100
task_id
string | null

将相关 Run,包括自动切换产生的 Run,归入同一个 Task。复用稳定字符串,并通过 Task 筛选 Run 列表。

metadata

可选追踪字段,随 Run 返回,也可用于筛选。不会发送给数据提供商,也不影响路由、价格或幂等。

  • 最多 20 个键:小写字母、数字和下划线,以字母开头,最长 40 个字符。
  • 值:长度为 1–500 的字符串。
  • user_id:终端用户的不透明 ID,不得使用邮箱或姓名。

无效条目整体丢弃,不截断。请求继续执行,Run 返回实际保存的字段。

响应

成功

id
string
必填
run_url
string
必填

在控制台打开 Run,需要工作空间成员权限。

provider
string
必填
Pattern: ^[a-z0-9][a-z0-9-]*$
endpoint
string
必填
Pattern: ^\/.+$
endpoint_version
integer
必填
status
enum<string>
必填

QUEUED 或 RUNNING 表示仍在执行。COMPLETED 表示已有数据提供商响应,包括非 2xx 响应。FAILED 请读取 failure。STOPPED 表示分派前停止。charge_usd 与状态分别检查。

可用选项:
QUEUED,
RUNNING,
COMPLETED,
FAILED,
STOPPED
failure
object | null
必填

Run 失败原因,仅在 status 为 FAILED 时非 null。

input
object
必填
output
object
必填

各操作的规范化字段。原生输出保留在 Run 中,可通过 GET /v1/runs/:id 读取。未报告的值为 null;有效空结果保留操作结构,各字段为 null 或 items 为 [],result_status 为 no_result。金额为美元,操作包含 currency 字段时除外。_date 为 YYYY-MM-DD,_at 为 ISO 8601 UTC,*_text 为原样返回的展示文本。

  • property_value: address, property_type, bedrooms, bathrooms, living_area_sqft ,居住面积, lot_size_sqft, year_built, latitude, longitude, estimated_value_usd, value_low_usd, value_high_usd, comparables_count ,估值所用的可比成交数
  • property_rent: address, property_type, bedrooms, bathrooms, living_area_sqft ,居住面积, lot_size_sqft, year_built, latitude, longitude, estimated_rent_usd ,月度, rent_low_usd, rent_high_usd, comparables_count ,估算所用的可比租赁数
  • property_search: items[]: property_id, address, property_type, bedrooms, bathrooms, living_area_sqft ,居住面积, lot_size_sqft, year_built, latitude, longitude, last_sale_price_usd, last_sale_date ,YYYY-MM-DD, owner_names[], owner_type, owner_mailing_address, owner_occupied
  • listings_sale: items[]: listing_id, address, property_type, bedrooms, bathrooms, living_area_sqft ,居住面积, lot_size_sqft, year_built, latitude, longitude, status, listing_type, listed_date ,YYYY-MM-DD, days_on_market, hoa_fee_usd ,月度 HOA 费用, mls_name, mls_number, agent {name, phone, email, website}, office {name, phone, email, website}, price_usd ,挂牌价
  • listings_rental: items[]: listing_id, address, property_type, bedrooms, bathrooms, living_area_sqft ,居住面积, lot_size_sqft, year_built, latitude, longitude, status, listing_type, listed_date ,YYYY-MM-DD, days_on_market, hoa_fee_usd ,月度 HOA 费用, mls_name, mls_number, agent {name, phone, email, website}, office {name, phone, email, website}, monthly_rent_usd
  • market_stats: zip, updated_at ,ISO 8601 UTC,RentCast 最近刷新汇总的时间, sale {average_price_usd, median_price_usd, average_price_per_sqft_usd, median_price_per_sqft_usd, average_days_on_market, median_days_on_market, total_listings, new_listings}, rental {average_rent_usd, median_rent_usd, average_rent_per_sqft_usd, median_rent_per_sqft_usd ,月租金, average_days_on_market, median_days_on_market, total_listings, new_listings}
  • stock_quote: symbol, name, exchange, currency, price ,常规时段最新价格,单位为 currency;Google Finance 报价可能延迟, change ,相对于上一常规收盘价的绝对变动,单位为 currency, change_percent ,相对于上一常规收盘价的百分点变动,1.5 表示 1.5%, extended_hours_session ,原样展示的时段标签,如 Pre-market 或 After hours,常规时段为 null, extended_hours_price, extended_hours_change、extended_hours_change_percent,盘前盘后报价相对于常规时段价格的变动,单位相同, as_of_text ,Google Finance 页面原样时间戳,不是 ISO 格式,也不是 price 的时间
provider_response
object | null
必填

仅在 status 为 COMPLETED 时非 null。

  • 2xx 响应:output 为任意结构的数据提供商原生 JSON;正文为空时为 null。
  • 非 2xx 响应:error 包含数据提供商错误正文,output 为 null。

两种正文均会移除敏感字段。

charge_usd
string | null
必填

此 Solution 响应所含 runs 的总费用,全部 Run 结算前为 null。每个 Run 保留各自费用;失败也可能收费。

Pattern: ^(0|[1-9]\d*)\.(\d{2}|\d{2}\d{0,3}[1-9])$
charge_basis
object | null
必填

单个 Run 的计费依据;多个 Run 汇总时为 null。各项费用请查看 runs[].charge_basis。

stoppable
boolean
必填

当前是否可接受停止请求。不保证能在分派前停止 Run。

stop_requested_at
string<date-time> | null
必填

请求停止的时间。如果已开始分派,Run 仍可能继续。

created_at
string<date-time>
必填

ISO 8601 UTC 时间戳。

started_at
string<date-time> | null
必填

ISO 8601 UTC 时间戳。

completed_at
string<date-time> | null
必填

ISO 8601 UTC 时间戳。

task_id
string | null
必填
metadata
object
必填

已保存的追踪字段,可用于筛选 Run,不发送给数据提供商,不影响路由、价格或幂等。

  • 最多 20 个键:小写字母、数字和下划线,以字母开头,最长 40 个字符。
  • 值:长度为 1–500 的字符串。
  • user_id:终端用户的不透明 ID,不得使用邮箱或姓名。
action
enum<string>
必填
可用选项:
property_value,
property_rent,
property_search,
listings_sale,
listings_rental,
market_stats,
stock_quote
result_status
enum<string>
必填

业务交付状态,与 status 中的最终 Run 生命周期独立。no_result 为有效空结果;error 表示数据提供商输出无法交付。

可用选项:
success,
no_result,
error,
pending
error
object | null
必填
runs
object[]
必填
result_url
string
必填

通过认证读取规范化结果和总费用的只读 URL 路径,配合 API 服务地址使用。不创建 Run,也不恢复切换。GET /v1/runs/:id 仍返回原生单个 Run。