查询美国地点建议并正确处理无匹配结果

查看 美国房产与房贷数据 API 的全部接口 →

通过必填的 input 字符串搜索美国地点建议,可使用可选的数值参数 limit 指定希望返回的条目数。文档说明支持州、城市、行政区、街道地址和邮政编码,输入示例包括 California、Los Angeles 和 2425 Sahalee Dr W Sammamish, WA;参数示例为 input=new york、limit=10。limit 用于指定请求的结果数量,此接口未提供 offset、分页令牌,也未保证可以遍历全部匹配结果。 成功实测确认响应包含 autocomplete 数组和 meta.es_total_hits 匹配总数。使用 input=New York、limit=3 时,响应的 meta.es_total_hits 为 5731,并返回 state:ny、city:ny_new-york、city:ny_manhattan 三个候选项,state_code 为 NY,country 为 USA。因此,匹配总数不一定等于实际返回的建议数量。输入一个特意构造的不存在地点时,接口返回 HTTP 200、meta.es_total_hits=0、autocomplete=[],且没有错误对象。这种组合应作为正常的无建议结果处理,而非请求失败。这些实测仅说明具有代表性的响应情况,并不保证匹配数量、排序或未来仍会返回相同候选项。 另一个被截断的文档示例列出 _id、_score、area_type、centroid.lat、centroid.lon、city、state_code、country、包含 fips/name/state_code 的 counties,以及 geo_id 和 slug_id 等候选字段。示例还列出随地点类别而变化的 city_slug_id、county_needed_for_uniq、line、postal_code、has_catchment、school 和 school_id。这些附加字段并未全部经过实测确认,也不是每个候选项的必备字段。应保留用户选中项的标识符、类别及可用地理信息,再核实后续接口接受什么输入。虽然文档提到可从地址查找房产标识符,但现有实测并未证明地址一定能解析为房产。

API 功能

实测区分州与城市候选项 纽约实测返回 state:ny、city:ny_new-york 和 city:ny_manhattan,适合让用户明确选择目标区域,而不是自动选中首条建议。
分开展示建议数量与匹配总数 可选 limit 用于指定希望返回的列表数量,meta.es_total_hits 提供匹配总数背景;一次返回三条建议的实测响应报告了 5731 条匹配。
将零匹配识别为正常响应 不存在地点的实测返回 HTTP 200、meta.es_total_hits=0 和 autocomplete=[],应显示正常的无匹配状态。
统一接收地址与邮编检索文本 文档说明同一个必填 input 字段可接收州、城市、行政区、地址或邮编;现有实测尚未确认地址与邮编输入的具体返回情况。
保留选中地点上下文供后续核验 保存候选项的标识符、类别和已有地理信息,供后续接口核对;不假定所有可选示例字段都存在,也不将每个地点都视为房产。

在线 API 演示

GET /api/project/realty-in-us/locations-v2-auto-complete

调用成本暂不可用,未假定任何价格。

查看价格

API 响应 (JSON)

{}
curl -X GET 'https://api.opendata-api.com/api/project/realty-in-us/locations-v2-auto-complete?key=<API_KEY>&input=<input>'
📢
需要帮助?
如遇接口异常,或需要其他接口需求,可联系我们
联系我们

使用场景

常见问题

input 可以填写哪些检索内容?

文档说明支持州、城市、行政区、街道地址和邮政编码。New York 已成功实测并返回建议,但现有测试不能确认所有地址或邮编输入的具体行为。

autocomplete 数组为空是否表示出错?

仅凭空数组不能判断出错。不存在地点的测试返回 HTTP 200、autocomplete=[]、meta.es_total_hits=0,且没有错误对象。界面应将这种组合作为无建议结果处理。

为什么 meta.es_total_hits 会大于建议列表长度?

纽约实测请求使用 limit=3,返回三条建议,但报告的匹配总数为 5731。应区分匹配总数与返回列表长度;此接口未说明 offset 或分页令牌参数。

应该如何区分州和城市建议?

保留每条候选项返回的标识符、地点类别和可用地理信息。纽约实测响应包含 state:ny、city:ny_new-york、city:ny_manhattan;直接选择首条结果不一定符合用户想查询的区域。

每条地址建议都能作为房产标识符使用吗?

不能。从地址查找房产是文档描述的用途,但现有测试仅确认了地点建议和零匹配情况。应确认选中候选项确实携带适用标识符,并核实后续接口是否接受该标识符。

相关接口

相关指南

查看订阅方案 →