学校数据API怎么接入省份列表名称搜索和详情查询如何分流

发布时间：2026-08-14 14:57 点击：6984次

学校数据 API 应先加载支持省份，再按场景调用省份列表或名称搜索，选中学校后用 detailid 查详情；类型筛选需先确认 typeid 映射。它不提供个人学历或学籍核验。

学校数据 API 能查什么，不能查什么

该接口适合查询学校目录与学校基本信息，不能用于验证某个人是否就读、毕业，不能核验学历证书，也不能替代教育主管部门的资质或认可查询。

根据极速数据学校数据 API 文档，产品提供省份列表、学校类型、按省份获取学校、按名称搜索学校和学校详情五类接口。适用场景包括院校选择器、教育内容导航、学校资料页和表单中的学校名称规范化。

边界需要在产品需求阶段写清楚：

可以做：按省份或类型浏览学校，按名称搜索学校，查询学校详情。
不可以据此证明：某人的学籍、学历、毕业状态、录取状态或证书真伪。
不应直接推断：学校当前招生资格、专业认证状态或行政认可结论。

搜索词中常见的“学历查询 API”容易混淆个人学历核验与学校信息查询。如果实际需求是核验个人学历，应选择有明确授权、合法依据和身份校验流程的专门渠道，不能用学校数据接口代替。

为什么省份可直接加载，类型映射却要先联调

省份接口可以作为支持范围字典预先加载并缓存。学校类型则存在文档口径差异：类型端点的当前返回示例是类别名称数组，而列表与搜索接口的参数表要求整数 typeid，页面没有给出名称与 ID 的直接映射。

当前官方文档把以下五个接口都标注为支持 GET 和 POST。本文请求示例统一使用 GET。

省份接口为：

GET https://api.jisuapi.com/school/province

请求示例：

curl --get "https://api.jisuapi.com/school/province" \
  --data-urlencode "appkey=YOUR_APPKEY"

学校类型接口为：

GET https://api.jisuapi.com/school/type

请求示例：

curl --get "https://api.jisuapi.com/school/type" \
  --data-urlencode "appkey=YOUR_APPKEY"

省份数据和类型名称通常适合较长缓存，但仍要记录更新时间并保留刷新能力。不能把类型名称数组的下标当作 typeid，也不能假设示例代码中的 type 参数等同于参数表里的 typeid。在账号实测或技术支持确认映射前，建议先上线不带类型条件的省份浏览与名称搜索；确认后再把映射保存为受版本管理的业务配置。

初始化流程可以是：后端定时刷新省份和类型名称，自有接口向客户端返回经过校验的数据；当刷新失败时继续使用最近一次成功缓存，并在监控中记录异常。类型筛选只有在 typeid 映射已确认时才启用，否则应隐藏该筛选项，而不是猜值请求。

按省份浏览学校怎样接入

用户按地区浏览时，应调用学校列表接口，并把省份作为必填条件，类型和页码作为可选筛选条件。

列表接口为：

GET https://api.jisuapi.com/school/get

请求示例：

curl --get "https://api.jisuapi.com/school/get" \
  --data-urlencode "appkey=YOUR_APPKEY" \
  --data-urlencode "province=YOUR_PROVINCE" \
  --data-urlencode "pagenum=1"

官方文档显示，province 为必填参数，typeid 可选，pagenum 默认从第一页开始，每页 20 条。由于当前页面没有展示 typeid 映射，上例先省略该可选参数。列表结果使用 detailid 表示文档标注的学校 ID，并包含学校名称、类型、创建年份、logo、年份和地址等字段。

省份选择发生变化时，应清空旧列表并把页码重置为第一页。类型筛选也应采用相同处理。列表缓存键至少包含省份、类型和页码，避免不同筛选条件相互污染。

无限滚动页面要设置“没有更多数据”状态，传统分页则应在切换条件时回到第一页。不要根据某一页返回不足 20 条就永久判断全部数据结束，最终逻辑仍应结合当前响应和接口实际行为验证。

按名称搜索学校怎样接入

当用户已经知道学校名称时，应使用名称搜索接口，并将省份和类型作为缩小范围的可选条件；过于模糊的名称要引导用户补充关键词。

搜索接口为：

GET https://api.jisuapi.com/school/search

请求示例：

curl --get "https://api.jisuapi.com/school/search" \
  --data-urlencode "appkey=YOUR_APPKEY" \
  --data-urlencode "name=YOUR_SCHOOL_NAME" \
  --data-urlencode "province=YOUR_PROVINCE" \
  --data-urlencode "pagenum=1"

name 是必填参数，省份、typeid 和页码可选；typeid 仍应在映射确认后再传。官方文档显示搜索结果使用 detailid 表示学校 ID，并包含学校名称、类型、地址、省份、城市、城镇和 logo 等信息，每页 20 条。

搜索框建议先做首尾空格清理和长度检查，再设置防抖请求。收到“请输入略详细名称”时，不要自动选中第一条结果，而应提示用户补充地区或更完整的校名。对于同名学校、分校区或相近名称，页面应同时展示省份、城市和类型，交由用户确认。

业务侧应保存用户最终选中结果的 detailid，而不是只保存文本名称。以后回显时可同时展示名称快照；若接口详情发生变化，系统仍能追踪原选择和当前数据之间的差异。

学校详情怎样查询和存储

详情页应使用列表或搜索结果返回的详情标识发起查询，并允许字段为空；空值应显示“暂未提供”，不能被加工成未经证实的信息。

详情接口为：

GET https://api.jisuapi.com/school/detail

请求示例：

curl --get "https://api.jisuapi.com/school/detail" \
  --data-urlencode "appkey=YOUR_APPKEY" \
  --data-urlencode "detailid=YOUR_DETAIL_ID"

官方文档显示，detailid 为必填参数。详情可包含学校名称、类别、性质、logo、省份、城市、学校代码和网站等信息，但官方示例中也存在字段为 null 的情况。因此，数据库和页面组件都要支持可空值。

推荐保留以下三层数据：

{
  "source": "jisuapi-school",
  "sourceId": "YOUR_DETAIL_ID",
  "fetchedAt": "ISO_TIMESTAMP",
  "normalized": {
    "name": "SCHOOL_NAME",
    "province": "PROVINCE_NAME",
    "city": "CITY_NAME",
    "website": null
  },
  "rawResponse": "STORE_ACCORDING_TO_YOUR_DATA_POLICY"
}

这是业务侧示意模型，不代表官方原始字段。fetchedAt 用于提示数据抓取时间，rawResponse 是否保存及保存多久，应根据业务必要性和数据治理规则决定。

学校网站等外部链接在展示前应校验协议和格式，跳转时可增加外链提示。接口返回某个网站并不代表业务方已经核验其持续有效或安全性，因此不要绕过正常的链接安全控制。