全国医院查询API接口全解析：13个子接口调用指南

什么是全国医院查询API接口

全国医院查询API接口（产品标识 hospital）是一套面向医疗数据场景的标准化 HTTP 接口，数据源为 2024 年全国省市县医院名单，共 53792 条医院记录，覆盖 34 个省级行政区、400 个城市、10 种医院等级与 20 种医院类型。接口以 JSON 返回，支持按医院名称精确查询、按关键词全文检索、按省/市/区县/等级/类型/经营方式/医保多维度筛选，以及按 ID 批量查询与详情获取。

相比直接维护一份医院名录，通过接口调用可以让业务系统实时获得结构化的医院数据，免去数据采集、清洗与持续更新的成本。本文从接口清单、认证方式、参数约定到调用示例，完整梳理这套接口的使用方法。

接口清单

该产品以 /api/hospital 为统一前缀，下挂 13 个子接口（12 个 GET + 1 个 POST），其中 7 个元数据接口免鉴权，可用于前端下拉框、筛选项的初始化。

认证方式与响应结构

鉴权

业务查询接口需要携带 API Key，支持两种传递方式（任选其一）：

• X-API-Key 请求头（推荐）：X-API-Key: <your-key>
• 查询参数：?api_key=<your-key>

ping、stats、provinces、levels、types、modes、fields 这 7 个元数据接口免鉴权，便于前端直接初始化筛选条件。

统一响应结构

{
  "code": 0,
  "msg": "success",
  "data": { }
}

code 为 0 表示成功，非 0 为业务错误码。data 中通常包含 list（结果数组）与 total（命中总数），部分接口还会返回 mode 表示实际使用的匹配模式。

通用参数约定

• 业务查询接口（query、search、list、detail、batch）均支持 brief 与 fields 两个通用参数控制返回字段。
• brief=true 时只返回 13 个核心字段（id/province/city/district/name/alias/level/type/operation_mode/insurance/beds/address/phone），可显著减小响应体积。
• fields 支持逗号或空白分隔，最多 30 个字段，单字段最长 64 字符。
• limit / page_size 上限固定为 50；元数据接口 limit 上限 500。

核心接口详解

精确查询 /query

按医院名称或别名精确匹配，match=auto 时在 name、alias 两个字段精确匹配；若零命中则自动降级为 LIKE 模糊匹配，因此对用户输入的容错性较好。

curl "https://www.shujuyu.cn/api/hospital/query?keyword=同仁医院&match=auto&limit=10" \
  -H "X-API-Key: <your-key>"

{
  "code": 0,
  "msg": "success",
  "data": {
    "list": [
      {
        "id": 12001,
        "province": "北京市",
        "city": "北京市",
        "district": "东城区",
        "name": "首都医科大学附属北京同仁医院",
        "alias": "同仁医院",
        "level": "三级甲等",
        "type": "综合医院",
        "operation_mode": "公立",
        "insurance": "医保",
        "beds": 1800,
        "address": "北京市东城区东交民巷1号",
        "phone": "010-58269911"
      }
    ],
    "total": 1,
    "mode": "exact"
  }
}

mode 取值说明：exact 精确匹配、like 降级模糊、empty 空关键词、error 数据库异常。

全文搜索 /search

按关键词全文检索医院，底层使用 MySQL FULLTEXT 索引配合 ngram 中文分词，可同时搜索医院名称、别名、简介与科室，并叠加省/市/区县/等级/类型/经营方式/医保等结构化过滤。关键词长度 ≥2 字时走全文检索，单字或含特殊字符时降级为 LIKE 模糊匹配。

搜索结果会附带 relevance 相关度分数，并按相关度倒序返回，便于做「最相关医院」排序。

curl "https://www.shujuyu.cn/api/hospital/search?keyword=骨科&scope=all&province=安徽省&level=三级甲等&limit=20" \
  -H "X-API-Key: <your-key>"

分页列表 /list

按 id ASC 分页返回医院列表，适合做「按地区/等级浏览医院名录」这类页面。除 page、page_size 外，过滤参数与 search 一致。

curl "https://www.shujuyu.cn/api/hospital/list?page=1&page_size=20&province=安徽省&level=三级甲等&type=综合医院&brief=true" \
  -H "X-API-Key: <your-key>"

响应中的 pages 为总页数，可直接用于前端分页控件渲染。

医院详情 /detail

按主键 ID 获取医院完整信息，包含建院年份、院长、床位、年门诊量、医护人数、科室、邮箱、邮编、简介等扩展字段；未找到时返回业务码 4041。

curl "https://www.shujuyu.cn/api/hospital/detail?id=21005" \
  -H "X-API-Key: <your-key>"

批量查询 /batch

请求体为 JSON，可按 id / name / alias 一次查询多个医院。返回结果与输入顺序一一对应，未命中的项以 error: "not_found" 标记。items 最多 200 个输入，单次最多返回 50 条，超出部分会截断并置 truncated: true。

curl -X POST "https://www.shujuyu.cn/api/hospital/batch" \
  -H "X-API-Key: <your-key>" \
  -H "Content-Type: application/json" \
  -d '{"items":["北京协和医院","复旦大学附属华山医院"],"key":"name"}'

{
  "code": 0,
  "msg": "success",
  "data": {
    "total": 2,
    "returned": 2,
    "ok": 1,
    "not_found": 1,
    "truncated": false,
    "max_limit": 50,
    "list": [
      { "id": 10001, "name": "北京协和医院", "province": "北京市", "city": "北京市", "level": "三级甲等" },
      { "query": "复旦大学附属华山医院", "error": "not_found" }
    ]
  }
}

元数据接口

元数据接口全部免鉴权，用于初始化筛选条件或做数据概览：

• /provinces：省份去重列表及各省医院数，按数量降序；
• /levels、/types、/modes：医院等级、类型、经营方式的去重列表及数量；
• /fields：全部业务字段及其中文标签，可据此拼接 fields 参数；
• /stats：返回 total_records（总记录数）、provinces、cities、levels、types 等统计值，适合做数据概览页；
• /ping：服务探活。

{
  "code": 0,
  "msg": "success",
  "data": {
    "total_records": 53792,
    "provinces": 34,
    "cities": 400,
    "levels": 10,
    "types": 20,
    "operation_modes": 5,
    "fulltext_enabled": true
  }
}

返回字段说明

医院记录最多包含 20 个业务字段，可通过 fields 参数按需裁剪：

错误码说明

当数据库不可用时，业务接口返回 HTTP 200 且 data.error 为 db_unavailable（元数据接口返回空列表），而不是直接抛出 500，便于调用方做降级处理。

调用示例

以 PHP 为例，封装一个按名称查询医院的方法：

<?php
function searchHospital(string $keyword, string $apiKey, int $limit = 10): array
{
    $url = 'https://www.shujuyu.cn/api/hospital/query?' . http_build_query([
        'keyword' => $keyword,
        'limit'   => $limit,
        'brief'   => 'true',
    ]);

    $ch = curl_init($url);
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT        => 10,
        CURLOPT_HTTPHEADER     => ['X-API-Key: ' . $apiKey],
    ]);
    $resp = curl_exec($ch);
    curl_close($ch);

    $json = json_decode((string)$resp, true);
    if (!is_array($json) || ($json['code'] ?? -1) !== 0) {
        return [];
    }
    return $json['data']['list'] ?? [];
}

// 用法
$list = searchHospital('同仁医院', '<your-key>');
foreach ($list as $h) {
    echo $h['name'], ' / ', $h['level'], ' / ', $h['address'], PHP_EOL;
}

典型应用场景

• 在线挂号与就医导诊：用户输入医院名称或科室关键词，调用 query / search 快速定位目标医院并展示等级、地址与电话。
• 保险与理赔网点查询：按省市区筛选「医保定点」医院，作为理赔材料提交或合作医院展示的数据来源。
• 医疗数据可视化：结合 stats、provinces、levels 等元数据接口，绘制各省医院数量、等级分布的统计图表。
• 批量数据校对：用 batch 接口一次性核验一批医院名称是否存在、别名与等级是否一致。

接口以 brief 与 fields 控制返回粒度，配合元数据接口缓存筛选条件，即可在保证响应速度的同时完成上述场景的数据支撑。