查询美国地点建议并正确处理无匹配结果
查看 美国房产与房贷数据 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 功能
在线 API 演示
未找到可用的 API Key,请前往控制台创建后刷新本页。 控制台 →
/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>'
查询结果
使用场景
- 构建纽约地点选择器,让用户在纽约州、纽约市与曼哈顿候选项之间确认目标搜索区域。
- 当 autocomplete 为空且 meta.es_total_hits 为零时显示无建议提示,避免对已成功的搜索反复重试。
- 用 limit 控制简短的建议菜单,同时将匹配总数与当前可见候选项数量分开呈现。
- 在应用状态中保存选中地点的类别与地理信息,再核实后续房产搜索接口接受的输入。
- 使用文档列出的州、城市、地址和邮编输入测试统一搜索框,但不承诺所有地址都能定位到房产。
常见问题
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;直接选择首条结果不一定符合用户想查询的区域。
每条地址建议都能作为房产标识符使用吗?
不能。从地址查找房产是文档描述的用途,但现有测试仅确认了地点建议和零匹配情况。应确认选中候选项确实携带适用标识符,并核实后续接口是否接受该标识符。