小学名录 API：名称别名、学校类型与区县查询-优快云博客

GuGuData 全国小学基础信息 API 支持按学校名称或别名、学校类型和省市区县组合查询名录，返回 SchoolId、名称、地区及可获取的地址和电话。使用 GET 分页查询，每页最多 20 条；组合条件取交集，缺失地址或电话保留为 null。

原始 API 封面

接口概览

项目	说明
请求方法	GET
接口地址	`https://api.gugudata.com/metadata/primary-school`
返回格式	JSON，UTF-8
调用凭据	对应产品有效 AppKey，本例通过 Header 传递

请求参数

参数名	参数类型	是否必须	默认值	备注
appkey	string	否	无	支持 Query、AppKey/X-GUGUDATA-APPKEY/X-API-Key Header 和 Bearer；相同值可共存，冲突返回 501。
keyword	string	否	无	学校名称或别名包含匹配；NFKC 及首尾空白处理，最长 100 字符；空值不筛选。
schoolType	string	否	ALL	学校类型，大小写不敏感；未传或空值为 ALL。普通小学 PRIMARY_SCHOOL、教学点 TEACHING_POINT、九年一贯制 NINE_YEAR_SCHOOL、十二年一贯制 TWELVE_YEAR_SCHOOL；未知类别返回 501。
province	string	否	无	地区完整名称精确匹配；NFKC 及首尾空白处理，最长 50 字符；默认空值不筛选，组合条件取交集。
city	string	否	无	地区完整名称精确匹配；NFKC 及首尾空白处理，最长 50 字符；默认空值不筛选，组合条件取交集。
district	string	否	无	地区完整名称精确匹配；NFKC 及首尾空白处理，最长 50 字符；默认空值不筛选，组合条件取交集。
pageIndex	integer	否	1	正 Int32 页码，默认 1；显式空值或非法值返回 501；合法超范围页返回空数组和正确总数。
pageSize	integer	否	20	每页 1～20 条，默认 20；显式空值或非法值返回 501。

参数名、大小写与默认值以当前接口文档为准。AppKey 参数的“可选”表示可以改从 Header 提供，不表示无需鉴权。

请求示例

以下是集成示例，未使用真实凭据执行。YOUR_APPKEY 为占位符，正式调用需要有效凭据及对应接口权益，价格与套餐以官网为准。中文 GET 参数通过 URL 编码传递。

curl --get 'https://api.gugudata.com/metadata/primary-school' \
  --header 'X-GUGUDATA-APPKEY: YOUR_APPKEY' \
  --data-urlencode 'province=北京市' \
  --data-urlencode 'schoolType=PRIMARY_SCHOOL' \
  --data-urlencode 'pageIndex=1' \
  --data-urlencode 'pageSize=10'

返回字段

参数名	参数类型	备注
DataStatus.RequestParameter	string	本次实际业务请求参数，不包含鉴权凭据；Demo 展示对应样例输入。
DataStatus.StatusCode	integer	业务状态码。
DataStatus.StatusDescription	string	业务状态说明。
DataStatus.ResponseDateTime	string	响应时间。
DataStatus.DataTotalCount	integer	筛选后的全部匹配数量，失败为 0。
Data.SchoolId	string	学校固定唯一标识。 Data 为数组，本项描述其中每条记录。
Data.SchoolName	string	学校名称。 Data 为数组，本项描述其中每条记录。
Data.SchoolType	string	标准学校类型。可能值：PRIMARY_SCHOOL（普通小学）；TEACHING_POINT（小学教学点）；NINE_YEAR_SCHOOL（九年一贯制学校）；TWELVE_YEAR_SCHOOL（十二年一贯制学校）。 Data 为数组，本项描述其中每条记录。
Data.Province	string	省级名称。 Data 为数组，本项描述其中每条记录。
Data.City	string	城市名称。 Data 为数组，本项描述其中每条记录。
Data.District	string	区县名称。 Data 为数组，本项描述其中每条记录。
Data.Address	string\|null	学校地址，无数据时为 null。 Data 为数组，本项描述其中每条记录。
Data.Telephone	string\|null	联系电话，无数据时为 null。 Data 为数组，本项描述其中每条记录。
Data.Aliases	array	学校别名去重数组。 Data 为数组，本项描述其中每条记录。

字段口径与使用边界

keyword 匹配学校名称或别名；province、city、district 使用完整地区名称精确匹配。普通小学、教学点、九年一贯制和十二年一贯制学校分别使用文档枚举，不能混用中学接口的 schoolType。SchoolId 用于同步和去重，Aliases 是别名数组，不能当作多所学校。Address 与 Telephone 为空表示资料缺失，不代表学校没有地址或电话。页码合法但越界时返回空数组和正确总数；显式传空的分页参数属于参数错误。