用户在医院搜索框里输入“淮南市第二人民医院”，和在科室页输入“淮南二院”，其实是两种不同的查询。match参数就是为这两类输入准备的：name认全称，alias认别名，auto则交给服务端先精确后模糊。

示例接口来自数据鱼API的「全国医院查询」服务，本文关注其中的「精确查询」分支（GET /v1/api/hospital/query）。精确查询医院。

参数怎么选

GET /v1/api/hospital/query的必填参数是key和keyword，keyword是医院名称或别名，最大 128 字符。match可选auto、name、alias，默认auto。limit默认 10，最大 20；brief和fields用于裁剪返回。

返回里data.list[].name是医院全称，data.list[].alias是别名，两者可能不同。示例里淮南市第二人民医院的别名是淮南市痔瘘医院，这类信息对本地用户很有用。data.mode会告诉你本次是 exact 还是 like，data.total是匹配总数。

keyword最大 128 字符，医院全称通常够用，但如果输入里混了备注或地址，截断后反而匹配不上。提交前做一次清洗，去掉多余空格和不可见字符，比在后端做模糊兜底更有效。

auto 的利与弊

auto的便利在于不用判断用户输入的是全称还是别名，服务端先精确匹配，没有结果再走模糊。对搜索框来说，这是最省事的选择。

但它也有代价：用户输入一个很短的词，可能会回退到模糊匹配，返回多条相似记录。前端不能默认取第一条当确定结果，尤其在医院场景里，选错机构会带来实际麻烦。合理做法是展示完整名称、省份、城市和等级，让用户确认。

auto回退到模糊匹配时，返回的记录可能来自不同城市。接口本身不提供置信度字段，只有data.mode说明本次是精确还是模糊。业务侧可以约定：exact 且只有一条时自动选中，其余情况一律让用户确认。

什么场景用哪种

扫描条码或从后台名单导入，输入的是完整名称，用name最直接。用户口语化称呼，例如“淮南二院”，用alias或auto更合适。需要确定性结果的接口间调用，建议显式指定name，避免服务端策略调整后行为变化。

如果一次查询返回多条，说明命中了同名或近似机构，用province、city或等级信息辅助区分，而不是简单截断。

另外，别名不是唯一的。同一家医院可能有多个别名，不同医院也可能共用一个俗称。用alias检索后仍要结合省市信息核对，不能只看名称。查询结果里的id是后续详情和批量的主键，拿到后要存下来，别用名称反复查。

curl -s -G "$API_BASE/v1/api/hospital/query" \ --data-urlencode "key=$API_KEY" \ --data-urlencode "keyword=淮南市第二人民医院" \ --data-urlencode "match=name" \ --data-urlencode "limit=5"

{ "code": 200, "msg": "success", "data": { "list": [ { "id": 97, "name": "淮南市第二人民医院", "alias": "淮南市痔瘘医院", "province": "安徽省", "city": "淮南市", "district": "八公山区", "level": "二级医院" } ], "mode": "exact", "total": 1 } }

def resolve_hospital(keyword: str): r = requests.get(f"{API_BASE}/v1/api/hospital/query", params={"key": API_KEY, "keyword": keyword, "match": "auto", "limit": 5}, timeout=5) data = r.json()["data"] if not data["list"]: return None if len(data["list"]) == 1 and data["mode"] == "exact": return data["list"][0] return {"candidates": data["list"], "mode": data["mode"]}

几个边界

名称里的“市”“区”“县”是匹配的一部分，去掉后可能反而查不到。别名字段可能为空，match=alias时对没有别名的医院会直接落空。limit最大 20，精确查询正常只返回一条，返回多条时优先检查是否重名。

还有，data.mode为 like 时，结果只是相似，不代表同一家机构，程序里不要自动建立映射关系。

把精确查询用在确定的输入上，把模糊需求留给搜索接口，两个入口各司其职，结果质量会稳很多。如果业务需要把查询结果写回内部系统，建议保存id、name、province、city和mode，后续核对时有据可查，也不要把 like 结果自动写入主数据。如果同一个关键词既可能是医院名又可能是科室名，先按名称查询，再把未命中的输入交给搜索接口，两个接口的返回结构相似，可以复用展示组件。

本文只讨论数据鱼API「全国医院查询」接口的接入方式，具体行为以官方文档为准。