位置质量评分的API

您需要快速对社区进行排名——自动完成地址、在边界框内提取活动列表，并获取物业的完整详细信息——以便为您的应用计算位置质量评分。在本指南结束时，您将能够调用Zyla API Hub上的三个真实端点，以获取您将评分的原始数据：基于关键字的位置建议、地理边界内的住宅库存以及详细的物业信息。

此API为评分位置提供的内容

加拿大房地产API汇总了您可以用来推导自己“位置质量”指标的住宅列表数据。借助它，您可以：

使用基于关键字的位置建议快速解析用户意图。
在纬度/经度边界框内提取列表，以计算密度、多样性和价格分布。
提取完整的物业详细信息（描述、ID等），以丰富您的评分逻辑或构建深入视图。

这些构建块通常用于买家指南、社区发现工具、线索路由和投资分析仪表板。如果您需要一个可靠的源，您可以在本周交付，这是Zyla API Hub上的一个简单选项。

在Zyla API Hub上开始

打开API的市场页面并开始试用以获取API密钥。身份验证是在每个请求上的简单头部：Authorization: Bearer YOUR_API_KEY。Zyla使用订阅和配额模型——没有按调用付费。首次使用时，预计有7天的试用期或50个请求以在您的环境中进行测试。请查看API页面以获取当前访问选项和定价。

从这里开始：在加拿大房地产API上开始7天试用

您将使用的端点来构建位置质量评分

1) 自动完成 (GET)

使用此功能将用户输入转换为精确的可操作建议——街道、城市和您可以映射到搜索的参考。

URL: https://zylalabs.com/api/5902/canada-real-estate-api/7768/auto-complete
目的: 返回基于关键字的位置建议。
所需参数：
- 查询 (字符串): 示例: Quebec
可选参数：
- CultureId (字符串): 示例: 1
- IncludeLocations (字符串): 示例: true

复制粘贴cURL:

curl -s -X GET "https://zylalabs.com/api/5902/canada-real-estate-api/7768/auto-complete?Query=Quebec&CultureId=1&IncludeLocations=true" \
-H "Authorization: Bearer YOUR_API_KEY"

官方示例响应：

{"ErrorCode":{"Id":200,"Description":"Success - OK","ProductName":"Realtor API 7 | 20241202.1 | 1018e702fe06dda8279318e12b199910ca21c3ff | Monday, December 2, 2024 12:21:41 PM","Version":"1.0.9102.31292"},"Results":[{"Type":1,"ListingId":"27656697","ReferenceNumber":"X10440405","Address_EN":"191 QUEBEC STREET","Address_FR":"191 QUEBEC STREET","City":"Bracebridge (Macaulay)","PostalCode":"p1l1e3","Province":"ON","Details_Small_EN":null,"Details_Small_FR":null,"RelativeURLEn":"\/real-estate\/27656697\/191-quebec-street-bracebridge-macaulay-macaulay","RelativeURLFr":"\/immobilier\/27656697\/191-quebec-street-bracebridge-macaulay","isReferenceMatch":false,"isPostalCodeMatch":false},{"Type":1,"ListingId":"27661192","ReferenceNumber":"X10428998","Address_EN":"549 QUEBEC STREET","Address_FR":"549 QUEBEC STREET","City":"London","PostalCode":"n5w3y9","Province":"ON","Details_Small_EN":null,"Details_Small_FR":null,"RelativeURLEn":"\/real-estate\/27661192\/549-quebec-street-london-east-g","RelativeURLFr":"\/immobilier\/27661192\/549-quebec-street-london","isReferenceMatch":false,"isPostalCodeMatch":false},{"Type":1,"ListingId":"27720876","ReferenceNumber":"R2949266","Address_EN":"212 4928 QUEBEC STREET","Address_FR":"212 4928 QUEBEC STREET","City":"Vancouver","PostalCode":"v5w2n2","Province":"BC","Details_Small_EN":null,"Details_Small_FR":null,"RelativeURLEn":"\/real-estate\/27720876\/212-4928-quebec-street-vancouver","RelativeURLFr":"\/immobilier\/27720876\/212-4928-quebec-street-vancouver","isReferenceMatch":false,"isPostalCodeMatch":false},{"Type":1,"ListingId":"27741486","ReferenceNumber":"X11894528","Address_EN":"558 QUEBEC STREET","Address_FR":"558 QUEBEC STREET","City":"Hamilton (Parkview)","PostalCode":"l8h6v4","Province":"ON","Details_Small_EN":null,"Details_Small_FR":null,"RelativeURLEn":"\/real-estate\/27741486\/558-quebec-street-hamilton-parkview-parkview","RelativeURLFr":"\/immobilier\/27741486\/558-quebec-street-hamilton-parkview","isReferenceMatch":false,"isPostalCodeMatch":false},{"Type":1,"ListingId":"27754883","ReferenceNumber":"S11901084","Address_EN":"267 QUEBEC STREET","Address_FR":"267 QUEBEC STREET","City":"Clearview (Stayner)","PostalCode":"l0m1s0","Province":"ON","Details_Small_EN":null,"Details_Small_FR":null,"RelativeURLEn":"\/real-estate\/27754883\/267-quebec-street-clearview-stayner-stayner","RelativeURLFr":"\/immobilier\/27754883\/267-quebec-street-clearview-stayner","isReferenceMatch":false,"isPostalCodeMatch":false}],"ResultsMapBox":[{…

从中读取内容：

ErrorCode: 使用Id和描述在非200流中短路。
Results: 每个建议为您提供ListingId、ReferenceNumber、Address_EN/FR、City、PostalCode、Province和相对URL。这些可以直接在您的UI中显示，并用于为该区域的列表生成后续搜索。

2) 列出住宅 (GET)

在纬度/经度边界框内提取一页住宅物业。非常适合密度指标、价格聚合和映射聚类。

URL: https://zylalabs.com/api/5902/canada-real-estate-api/7769/list-residential
目的: 返回基于地理边界的可用住宅物业出售或出租。
所需参数：
- LatitudeMax (数字): 81.14747595814636
- LatitudeMin (数字): -22.26872153207164
- LongitudeMax (数字): -10.267941690981388
- LongitudeMin (数字): -136.83037765324116

示例cURL（按原样复制并更改头部密钥）：

节省时间的注意事项：

响应包括一个Paging对象，其中包含RecordsPerPage、CurrentPage和TotalRecords。使用它来分页并计算每个区域的列表密度指标。
ErrorCode.Status可能包括缓存提示，例如“Pins-Via-Cache:false;Sidebar-Items-Via-Cache:0;”。不要依赖这些逻辑，但它们可以解释日志中的响应时间。
RecordsShowing和Pins可以帮助您调试服务器打算每页显示多少个地图标记或项目。

3) 物业详细信息 (GET)

使用ReferenceNumber和PropertyID的组合提取单个物业的综合信息。使用此功能丰富您的评分UI，提供完整的描述，并确认所选候选人的详细信息。

URL: https://zylalabs.com/api/5902/canada-real-estate-api/7770/property-detail
目的: 获取详细的列表信息，例如图像、描述和物业特征。
所需参数：
- ReferenceNumber (字符串): 67b74ee58bc56b22659786b3
- PropertyID (字符串): 27935110

示例cURL：

实用指导：

在读取字段之前检查ErrorCode块。
使用公共备注和核心标识符在您的应用中锚定物业档案页面。

Python示例：解析查询并计算简单的列表密度评分

此示例调用自动完成以确认用户输入的目标区域，然后调用列出住宅以获取广泛的边界框。您将根据用户选择的建议调整边界框（例如，缩小到您从自己数据中推导出的特定城市或社区几何形状）。

import requests

API_KEY = "YOUR_API_KEY"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}

# 1) 使用自动完成解析用户意图
auto_complete_url = "https://zylalabs.com/api/5902/canada-real-estate-api/7768/auto-complete"
params = {
"Query": "Quebec",
"CultureId": "1",
"IncludeLocations": "true"
}
ac_resp = requests.get(auto_complete_url, headers=HEADERS, params=params, timeout=30)
ac_data = ac_resp.json()

if ac_data.get("ErrorCode", {}).get("Id") != 200:
raise SystemExit(f"自动完成失败: {ac_data.get('ErrorCode')}")

suggestions = ac_data.get("Results", [])
# 在真实应用中，根据用户操作选择一个建议。
first = suggestions[0] if suggestions else None
if first:
print("顶级建议:", first.get("Address_EN"), first.get("City"), first.get("Province"))

# 2) 在边界框内提取列表（来自文档的演示值）
list_url = "https://zylalabs.com/api/5902/canada-real-estate-api/7769/list-residential"
list_params = {
"LatitudeMax": 81.14747595814636,
"LatitudeMin": -22.26872153207164,
"LongitudeMax": -10.267941690981388,
"LongitudeMin": -136.83037765324116
}
list_resp = requests.get(list_url, headers=HEADERS, params=list_params, timeout=30)
list_data = list_resp.json()

if list_data.get("ErrorCode", {}).get("Id") != 200:
raise SystemExit(f"列出住宅失败: {list_data.get('ErrorCode')}")

paging = list_data.get("Paging", {})
total_records = paging.get("TotalRecords")
records_per_page = paging.get("RecordsPerPage")
current_page = paging.get("CurrentPage")
print("列表页面:", current_page, "页面大小:", records_per_page, "总计:", total_records)

# 3) 最小的“位置质量”代理：密度评分（每N平方公里的记录数），基于您的边界。
# 您必须计算所选边界的面积；在这里我们只是展示这个想法，而不进行大地测量数学。
results = list_data.get("Results", [])
count = len(results) if isinstance(results, list) else 0
print("密度代理（bbox中的计数）:", count)

提示：

保持请求超时合理（20-30秒），以应对网络变化。
使用ErrorCode对象在成功与重试或回退流之间分支。
持久化Paging总数以进行分析，并避免在每次用户翻页时重新计数。

如何将这些响应转换为“位置质量”评分

由于评分标准因产品而异，API返回原始列表和建议数据。您可以计算一个复合评分，如下所示：

库存密度：您边界框内每个面积单位的列表数量（来自列出住宅 + 您自己的面积计算）。
多样性：根据Results中存在的物业属性进行计数（例如，如果在Building对象中可用，则为StoriesTotal）以估算多样性。
时效性/可用性代理：使用分页总数来了解某个区域是否“活跃”。
文本信号：从物业详细信息中挖掘公共备注（可用时）以向您的模型呈现关键字（翻新、靠近交通）。

从密度和多样性开始。它们提供了可操作的基线，并且计算速度快。

AI代理：通过MCP调用API

如果您更喜欢从AI代理或IDE助手中协调调用，您可以使用Zyla的MCP端点。任何兼容MCP的客户端（例如Claude Code、Cursor、Windsurf）都可以通过MCP网关使用您的相同密钥访问Zyla API。请参见： MCP。

工作流程概述：

向您的MCP客户端提供MCP端点和您的API密钥：https://mcp.zylalabs.com/mcp?apikey=YOUR_API_KEY
指示您的代理首先调用自动完成端点以获取用户输入，然后调用列出住宅以获取所选区域。
可选地提取物业详细信息，以在聊天中丰富摘要。

有助于生产的操作细节

身份验证：在每个请求中发送Authorization: Bearer YOUR_API_KEY。
分页：在列出住宅中读取Paging对象以进行分页和缓存计数。
缓存：ErrorCode.Status字符串可能包含提示（例如，Pins-Via-Cache）。将其视为信息性。
本地化：自动完成支持CultureId和Address_EN/FR。在您的UI中尊重用户的语言。
配额：Zyla使用订阅 + 配额。首次API通常提供7天的试用或50个请求以进行评估。有关当前限制，请参见市场页面。

本周交付的端到端流程

在市场页面上获取密钥并将其存储在您的秘密管理器中。
在您的搜索框中实现自动完成，以快速解析用户的意图区域。
将所选建议转换为边界框。如果您的应用存储多边形，请将建议映射到您的几何形状。否则，从您维护的城市范围框开始。
调用列出住宅并计算：
- 列表计数（密度代理）。
- 来自Results数组的属性多样性分布。
在选择时，调用物业详细信息以获取深入视图并提取文本特征以进行评分。
公开复合的“位置质量”评分，并提供链接以查看基础数据（列表数量、示例物业）。

故障排除检查清单

401/403：验证Authorization: Bearer YOUR_API_KEY和订阅状态。
空建议：在自动完成中尝试更广泛的查询字符串，或确认IncludeLocations在需要时设置为true。
意外分页：记录整个Paging对象以确认RecordsPerPage和TotalPages。
慢查询：预缓存频繁的边界框并重用计算的评分。

常见问题

我如何进行身份验证？
在每个请求中发送头部Authorization: Bearer YOUR_API_KEY。

我可以按价格、卧室或其他属性进行过滤吗？
本指南中描述了列出住宅端点的地理边界。如果您需要额外的过滤器，请查看API页面以获取可用参数和示例。

我如何对结果进行分页？
使用列出住宅响应中的Paging对象。像RecordsPerPage、CurrentPage和TotalPages这样的字段指示要请求多少页。在您的API层中处理此内容并流式传输到UI。

我应该使用什么来计算位置质量评分？
从您边界框内的列表密度开始，然后通过物业属性和来自物业详细信息的文本关键字信号添加多样性。保持模型透明，以便用户可以看到为什么某个区域得分高或低。

是否有免费计划？
Zyla使用订阅 + 配额。对于首次评估，预计有7天的试用或50个请求。请查看API页面以获取当前访问选项和定价。

交付您的位置评分功能

获取您的密钥，连接上述三个端点，并开始计算适合您产品的意见位置评分。从这里开始：在加拿大房地产API上开始7天试用。您可以随时通过额外的Zyla API进行扩展——在Zyla API Hub上有超过10,000个公共API可用。

官方API响应

{"ErrorCode":{"Id":200,"Description":"成功 - OK","ProductName":"Realtor API 7 | 20241202.1 | 1018e702fe06dda8279318e12b199910ca21c3ff | 2024年12月2日星期一12:21:41 PM","Version":"1.0.9102.31292"},"Results":[{"Type":1,"ListingId":"27656697","ReferenceNumber":"X10440405","Address_EN":"191 QUEBEC STREET","Address_FR":"191 QUEBEC STREET","City":"Bracebridge (Macaulay)","PostalCode":"p1l1e3","Province":"ON","Details_Small_EN":null,"Details_Small_FR":null,"RelativeURLEn":"\/real-estate\/27656697\/191-quebec-street-bracebridge-macaulay-macaulay","RelativeURLFr":"\/immobilier\/27656697\/191-quebec-street-bracebridge-macaulay","isReferenceMatch":false,"isPostalCodeMatch":false},{"Type":1,"ListingId":"27661192","ReferenceNumber":"X10428998","Address_EN":"549 QUEBEC STREET","Address_FR":"549 QUEBEC STREET","City":"London","PostalCode":"n5w3y9","Province":"ON","Details_Small_EN":null,"Details_Small_FR":null,"RelativeURLEn":"\/real-estate\/27661192\/549-quebec-street-london-east-g","RelativeURLFr":"\/immobilier\/27661192\/549-quebec-street-london","isReferenceMatch":false,"isPostalCodeMatch":false},{"Type":1,"ListingId":"27720876","ReferenceNumber":"R2949266","Address_EN":"212 4928 QUEBEC STREET","Address_FR":"212 4928 QUEBEC STREET","City":"Vancouver","PostalCode":"v5w2n2","Province":"BC","Details_Small_EN":null,"Details_Small_FR":null,"RelativeURLEn":"\/real-estate\/27720876\/212-4928-quebec-street-vancouver","RelativeURLFr":"\/immobilier\/27720876\/212-4928-quebec-street-vancouver","isReferenceMatch":false,"isPostalCodeMatch":false},{"Type":1,"ListingId":"27741486","ReferenceNumber":"X11894528","Address_EN":"558 QUEBEC STREET","Address_FR":"558 QUEBEC STREET","City":"Hamilton (Parkview)","PostalCode":"l8h6v4","Province":"ON","Details_Small_EN":null,"Details_Small_FR":null,"RelativeURLEn":"\/real-estate\/27741486\/558-quebec-street-hamilton-parkview-parkview","RelativeURLFr":"\/immobilier\/27741486\/558-quebec-street-hamilton-parkview","isReferenceMatch":false,"isPostalCodeMatch":false},{"Type":1,"ListingId":"27754883","ReferenceNumber":"S11901084","Address_EN":"267 QUEBEC STREET","Address_FR":"267 QUEBEC STREET","City":"Clearview (Stayner)","PostalCode":"l0m1s0","Province":"ON","Details_Small_EN":null,"Details_Small_FR":null,"RelativeURLEn":"\/real-estate\/27754883\/267-quebec-street-clearview-stayner-stayner","RelativeURLFr":"\/immobilier\/27754883\/267-quebec-street-clearview-stayner","isReferenceMatch":false,"isPostalCodeMatch":false}],"ResultsMapBox":[{…

官方API响应

{"ErrorCode":{"Id":200,"Description":"成功 - OK","ProductName":"Realtor API 7 | 20241202.1 | 1018e702fe06dda8279318e12b199910ca21c3ff | 2024年12月2日星期一12:21:41 PM","Version":"1.0.9102.31292"},"Results":[{"Type":1,"ListingId":"27656697","ReferenceNumber":"X10440405","Address_EN":"191 QUEBEC STREET","Address_FR":"191 QUEBEC STREET","City":"Bracebridge (Macaulay)","PostalCode":"p1l1e3","Province":"ON","Details_Small_EN":null,"Details_Small_FR":null,"RelativeURLEn":"\/real-estate\/27656697\/191-quebec-street-bracebridge-macaulay-macaulay","RelativeURLFr":"\/immobilier\/27656697\/191-quebec-street-bracebridge-macaulay","isReferenceMatch":false,"isPostalCodeMatch":false},{"Type":1,"ListingId":"27661192","ReferenceNumber":"X10428998","Address_EN":"549 QUEBEC STREET","Address_FR":"549 QUEBEC STREET","City":"London","PostalCode":"n5w3y9","Province":"ON","Details_Small_EN":null,"Details_Small_FR":null,"RelativeURLEn":"\/real-estate\/27661192\/549-quebec-street-london-east-g","RelativeURLFr":"\/immobilier\/27661192\/549-quebec-street-london","isReferenceMatch":false,"isPostalCodeMatch":false},{"Type":1,"ListingId":"27720876","ReferenceNumber":"R2949266","Address_EN":"212 4928 QUEBEC STREET","Address_FR":"212 4928 QUEBEC STREET","City":"Vancouver","PostalCode":"v5w2n2","Province":"BC","Details_Small_EN":null,"Details_Small_FR":null,"RelativeURLEn":"\/real-estate\/27720876\/212-4928-quebec-street-vancouver","RelativeURLFr":"\/immobilier\/27720876\/212-4928-quebec-street-vancouver","isReferenceMatch":false,"isPostalCodeMatch":false},{"Type":1,"ListingId":"27741486","ReferenceNumber":"X11894528","Address_EN":"558 QUEBEC STREET","Address_FR":"558 QUEBEC STREET","City":"Hamilton (Parkview)","PostalCode":"l8h6v4","Province":"ON","Details_Small_EN":null,"Details_Small_FR":null,"RelativeURLEn":"\/real-estate\/27741486\/558-quebec-street-hamilton-parkview-parkview","RelativeURLFr":"\/immobilier\/27741486\/558-quebec-street-hamilton-parkview","isReferenceMatch":false,"isPostalCodeMatch":false},{"Type":1,"ListingId":"27754883","ReferenceNumber":"S11901084","Address_EN":"267 QUEBEC STREET","Address_FR":"267 QUEBEC STREET","City":"Clearview (Stayner)","PostalCode":"l0m1s0","Province":"ON","Details_Small_EN":null,"Details_Small_FR":null,"RelativeURLEn":"\/real-estate\/27754883\/267-quebec-street-clearview-stayner-stayner","RelativeURLFr":"\/immobilier\/27754883\/267-quebec-street-clearview-stayner","isReferenceMatch":false,"isPostalCodeMatch":false}],"ResultsMapBox":[{…