{"info":{"description":"免费开放 API 平台 · 供 AI Agent 与人类开发者调用的中国公共数据只读接口","title":"ResAPI","version":"1.13.0"},"openapi":"3.0.3","paths":{"/agent.json":{"get":{"operationId":"agentDiscovery","responses":{"200":{"description":"成功"},"400":{"description":"参数无效"},"404":{"description":"资源不存在"},"429":{"description":"请求过于频繁"},"500":{"description":"服务器错误"}},"summary":"Agent 服务发现"}},"/catalog.json":{"get":{"operationId":"catalogJSON","responses":{"200":{"description":"成功"},"400":{"description":"参数无效"},"404":{"description":"资源不存在"},"429":{"description":"请求过于频繁"},"500":{"description":"服务器错误"}},"summary":"API 目录"}},"/health":{"get":{"operationId":"healthCheck","responses":{"200":{"description":"成功"},"400":{"description":"参数无效"},"404":{"description":"资源不存在"},"429":{"description":"请求过于频繁"},"500":{"description":"服务器错误"}},"summary":"健康检查"}},"/metrics":{"get":{"operationId":"metricsPrometheus","responses":{"200":{"description":"成功"},"400":{"description":"参数无效"},"404":{"description":"资源不存在"},"429":{"description":"请求过于频繁"},"500":{"description":"服务器错误"}},"summary":"Prometheus 指标"}},"/v1/address/normalize":{"get":{"operationId":"addressNormalize","parameters":[{"in":"query","name":"province","required":true,"schema":{"type":"string"}},{"in":"query","name":"city","required":true,"schema":{"type":"string"}},{"in":"query","name":"district","required":true,"schema":{"type":"string"}},{"in":"query","name":"detail","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"成功"},"400":{"description":"参数无效"},"404":{"description":"资源不存在"},"429":{"description":"请求过于频繁"},"500":{"description":"服务器错误"}},"summary":"地址标准化"}},"/v1/address/parse":{"get":{"description":"从自由文本地址中识别省、市、区县及标准区划编码。","operationId":"addressParse","parameters":[{"in":"query","name":"text","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"成功"},"400":{"description":"参数无效"},"404":{"description":"资源不存在"},"429":{"description":"请求过于频繁"},"500":{"description":"服务器错误"}},"summary":"地址解析","x-agent-tool-id":"address_parse","x-agent-when-to-use":["用户粘贴一整段地址需要结构化","快递单地址解析"]}},"/v1/address/suggest":{"get":{"operationId":"addressSuggest","parameters":[{"in":"query","name":"q","required":true,"schema":{"type":"string"}},{"in":"query","name":"limit","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"成功"},"400":{"description":"参数无效"},"404":{"description":"资源不存在"},"429":{"description":"请求过于频繁"},"500":{"description":"服务器错误"}},"summary":"地址候选"}},"/v1/agent/address":{"get":{"operationId":"agentAddress","parameters":[{"description":"待解析地址","in":"query","name":"text","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"成功"},"400":{"description":"参数无效"},"404":{"description":"资源不存在"},"429":{"description":"请求过于频繁"},"500":{"description":"服务器错误"}},"summary":"聚合：地址解析+区划层级"}},"/v1/agent/day":{"get":{"operationId":"agentDay","parameters":[{"description":"日期 YYYY-MM-DD","in":"query","name":"date","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"成功"},"400":{"description":"参数无效"},"404":{"description":"资源不存在"},"429":{"description":"请求过于频繁"},"500":{"description":"服务器错误"}},"summary":"聚合：工作日+农历"}},"/v1/agent/phone":{"get":{"operationId":"agentPhone","parameters":[{"description":"手机号或号段","in":"query","name":"number","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"成功"},"400":{"description":"参数无效"},"404":{"description":"资源不存在"},"429":{"description":"请求过于频繁"},"500":{"description":"服务器错误"}},"summary":"聚合：号段归属+省级区划"}},"/v1/agent/suggest":{"get":{"operationId":"agentSuggest","parameters":[{"description":"用户问题或关键词","in":"query","name":"q","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"成功"},"400":{"description":"参数无效"},"404":{"description":"资源不存在"},"429":{"description":"请求过于频繁"},"500":{"description":"服务器错误"}},"summary":"意图路由：推荐工具与聚合接口"}},"/v1/agent/zipcode":{"get":{"operationId":"agentZipcode","parameters":[{"description":"地名或 6 位邮编","in":"query","name":"q","required":false,"schema":{"type":"string"}},{"description":"6 位邮编","in":"query","name":"zip","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"成功"},"400":{"description":"参数无效"},"404":{"description":"资源不存在"},"429":{"description":"请求过于频繁"},"500":{"description":"服务器错误"}},"summary":"聚合：邮编/地名互查"}},"/v1/colleges":{"get":{"operationId":"collegesList","parameters":[{"in":"query","name":"page","required":false,"schema":{"type":"string"}},{"in":"query","name":"page_size","required":false,"schema":{"type":"string"}},{"in":"query","name":"province","required":false,"schema":{"type":"string"}},{"in":"query","name":"q","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"成功"},"400":{"description":"参数无效"},"404":{"description":"资源不存在"},"429":{"description":"请求过于频繁"},"500":{"description":"服务器错误"}},"summary":"高校列表"}},"/v1/colleges/code/{code}":{"get":{"operationId":"collegesGetByCode","parameters":[{"description":"路径参数","in":"path","name":"code","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"成功"},"400":{"description":"参数无效"},"404":{"description":"资源不存在"},"429":{"description":"请求过于频繁"},"500":{"description":"服务器错误"}},"summary":"按学校代码查询"}},"/v1/colleges/search":{"get":{"description":"搜索全国高校基础信息（名称、省份、层次等）。","operationId":"collegesSearch","parameters":[{"in":"query","name":"q","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"成功"},"400":{"description":"参数无效"},"404":{"description":"资源不存在"},"429":{"description":"请求过于频繁"},"500":{"description":"服务器错误"}},"summary":"高校搜索","x-agent-tool-id":"colleges_search","x-agent-when-to-use":["查大学信息","高考志愿参考","高校名单筛选"]}},"/v1/colleges/{id}":{"get":{"operationId":"collegesGetByID","parameters":[{"description":"路径参数","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"成功"},"400":{"description":"参数无效"},"404":{"description":"资源不存在"},"429":{"description":"请求过于频繁"},"500":{"description":"服务器错误"}},"summary":"高校详情"}},"/v1/holidays/check":{"get":{"description":"查询中国大陆某日是否为法定节假日、调休工作日或普通周末。","operationId":"holidaysCheck","parameters":[{"description":"日期 YYYY-MM-DD","in":"query","name":"date","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"成功"},"400":{"description":"参数无效"},"404":{"description":"资源不存在"},"429":{"description":"请求过于频繁"},"500":{"description":"服务器错误"}},"summary":"判断单日是否节假日","x-agent-tool-id":"holidays_check","x-agent-when-to-use":["用户问某天是否放假、要不要上班","判断调休补班日","写日程、排期前确认工作日"]}},"/v1/holidays/countdown":{"get":{"operationId":"holidaysCountdown","parameters":[{"description":"起始日期","in":"query","name":"from","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"成功"},"400":{"description":"参数无效"},"404":{"description":"资源不存在"},"429":{"description":"请求过于频繁"},"500":{"description":"服务器错误"}},"summary":"法定节假日倒计时"}},"/v1/holidays/lunar":{"get":{"description":"查询某日农历、节气、生肖、星座等历法信息。","operationId":"holidaysLunar","parameters":[{"description":"日期 YYYY-MM-DD","in":"query","name":"date","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"成功"},"400":{"description":"参数无效"},"404":{"description":"资源不存在"},"429":{"description":"请求过于频繁"},"500":{"description":"服务器错误"}},"summary":"农历节气生肖星座","x-agent-tool-id":"holidays_lunar","x-agent-when-to-use":["公历转农历语境","查节气、生肖","农历生日相关"]}},"/v1/holidays/lunar-to-solar":{"get":{"operationId":"holidaysLunarToSolar","parameters":[{"description":"农历年","in":"query","name":"lunar_year","required":true,"schema":{"type":"string"}},{"description":"农历月 1-12","in":"query","name":"lunar_month","required":true,"schema":{"type":"string"}},{"description":"农历日","in":"query","name":"lunar_day","required":true,"schema":{"type":"string"}},{"description":"1/true 表示闰月","in":"query","name":"leap_month","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"成功"},"400":{"description":"参数无效"},"404":{"description":"资源不存在"},"429":{"description":"请求过于频繁"},"500":{"description":"服务器错误"}},"summary":"农历转公历"}},"/v1/holidays/range":{"get":{"operationId":"holidaysRange","parameters":[{"in":"query","name":"start","required":true,"schema":{"type":"string"}},{"in":"query","name":"end","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"成功"},"400":{"description":"参数无效"},"404":{"description":"资源不存在"},"429":{"description":"请求过于频繁"},"500":{"description":"服务器错误"}},"summary":"批量判断日期区间"}},"/v1/holidays/solar-to-lunar":{"get":{"operationId":"holidaysSolarToLunar","parameters":[{"description":"公历日期 YYYY-MM-DD","in":"query","name":"date","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"成功"},"400":{"description":"参数无效"},"404":{"description":"资源不存在"},"429":{"description":"请求过于频繁"},"500":{"description":"服务器错误"}},"summary":"公历转农历"}},"/v1/holidays/terms":{"get":{"operationId":"holidaysTerms","parameters":[{"description":"公历年份，默认今年","in":"query","name":"year","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"成功"},"400":{"description":"参数无效"},"404":{"description":"资源不存在"},"429":{"description":"请求过于频繁"},"500":{"description":"服务器错误"}},"summary":"年度二十四节气"}},"/v1/ich/inheritors":{"get":{"operationId":"ichListInheritors","parameters":[{"in":"query","name":"province","required":false,"schema":{"type":"string"}},{"in":"query","name":"project","required":false,"schema":{"type":"string"}},{"in":"query","name":"name","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"成功"},"400":{"description":"参数无效"},"404":{"description":"资源不存在"},"429":{"description":"请求过于频繁"},"500":{"description":"服务器错误"}},"summary":"非遗传承人列表"}},"/v1/ich/inheritors/search":{"get":{"operationId":"ichSearchInheritors","parameters":[{"in":"query","name":"q","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"成功"},"400":{"description":"参数无效"},"404":{"description":"资源不存在"},"429":{"description":"请求过于频繁"},"500":{"description":"服务器错误"}},"summary":"非遗传承人搜索"}},"/v1/ich/projects":{"get":{"operationId":"ichListProjects","parameters":[{"in":"query","name":"province","required":false,"schema":{"type":"string"}},{"in":"query","name":"city","required":false,"schema":{"type":"string"}},{"in":"query","name":"category","required":false,"schema":{"type":"string"}},{"in":"query","name":"batch","required":false,"schema":{"type":"string"}},{"in":"query","name":"year","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"成功"},"400":{"description":"参数无效"},"404":{"description":"资源不存在"},"429":{"description":"请求过于频繁"},"500":{"description":"服务器错误"}},"summary":"非遗项目列表"}},"/v1/ich/projects/search":{"get":{"description":"搜索中国省级非物质文化遗产代表性项目。","operationId":"ichSearchProjects","parameters":[{"in":"query","name":"q","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"成功"},"400":{"description":"参数无效"},"404":{"description":"资源不存在"},"429":{"description":"请求过于频繁"},"500":{"description":"服务器错误"}},"summary":"非遗项目搜索","x-agent-tool-id":"ich_search_projects","x-agent-when-to-use":["查非遗项目","文化调研","写非遗相关报告"]}},"/v1/ich/projects/{id}":{"get":{"operationId":"ichGetProject","parameters":[{"description":"路径参数","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"成功"},"400":{"description":"参数无效"},"404":{"description":"资源不存在"},"429":{"description":"请求过于频繁"},"500":{"description":"服务器错误"}},"summary":"非遗项目详情含传承人"}},"/v1/ich/stats/cities":{"get":{"operationId":"ichStatsCities","responses":{"200":{"description":"成功"},"400":{"description":"参数无效"},"404":{"description":"资源不存在"},"429":{"description":"请求过于频繁"},"500":{"description":"服务器错误"}},"summary":"各市非遗数量统计"}},"/v1/ich/stats/provinces":{"get":{"operationId":"ichStatsProvinces","responses":{"200":{"description":"成功"},"400":{"description":"参数无效"},"404":{"description":"资源不存在"},"429":{"description":"请求过于频繁"},"500":{"description":"服务器错误"}},"summary":"各省非遗数量统计"}},"/v1/phone/lookup":{"get":{"description":"根据 11 位手机号或前 7 位号段查询归属省、市与运营商。","operationId":"phoneLookup","parameters":[{"description":"11 位手机号或 7 位号段","in":"query","name":"number","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"成功"},"400":{"description":"参数无效"},"404":{"description":"资源不存在"},"429":{"description":"请求过于频繁"},"500":{"description":"服务器错误"}},"summary":"手机号段归属地查询","x-agent-tool-id":"phone_lookup","x-agent-when-to-use":["查手机号归属地","识别运营商","号段是否在库"]}},"/v1/regions":{"get":{"operationId":"regionsList","parameters":[{"in":"query","name":"level","required":false,"schema":{"type":"string"}},{"in":"query","name":"parent_code","required":false,"schema":{"type":"string"}},{"in":"query","name":"page","required":false,"schema":{"type":"string"}},{"in":"query","name":"page_size","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"成功"},"400":{"description":"参数无效"},"404":{"description":"资源不存在"},"429":{"description":"请求过于频繁"},"500":{"description":"服务器错误"}},"summary":"行政区划列表"}},"/v1/regions/children":{"get":{"operationId":"regionsChildren","parameters":[{"in":"query","name":"parent_code","required":true,"schema":{"type":"string"}},{"in":"query","name":"level","required":false,"schema":{"type":"string"}},{"in":"query","name":"page","required":false,"schema":{"type":"string"}},{"in":"query","name":"page_size","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"成功"},"400":{"description":"参数无效"},"404":{"description":"资源不存在"},"429":{"description":"请求过于频繁"},"500":{"description":"服务器错误"}},"summary":"子级区划"}},"/v1/regions/provinces":{"get":{"operationId":"regionsProvinces","parameters":[{"in":"query","name":"page","required":false,"schema":{"type":"string"}},{"in":"query","name":"page_size","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"成功"},"400":{"description":"参数无效"},"404":{"description":"资源不存在"},"429":{"description":"请求过于频繁"},"500":{"description":"服务器错误"}},"summary":"省级列表"}},"/v1/regions/search":{"get":{"description":"按地名关键词搜索省、市、区县、乡镇等行政区划及标准编码。","operationId":"regionsSearch","parameters":[{"in":"query","name":"q","required":true,"schema":{"type":"string"}},{"in":"query","name":"level","required":false,"schema":{"type":"string"}},{"in":"query","name":"province","required":false,"schema":{"type":"string"}},{"in":"query","name":"city","required":false,"schema":{"type":"string"}},{"in":"query","name":"page","required":false,"schema":{"type":"string"}},{"in":"query","name":"page_size","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"成功"},"400":{"description":"参数无效"},"404":{"description":"资源不存在"},"429":{"description":"请求过于频繁"},"500":{"description":"服务器错误"}},"summary":"区划搜索","x-agent-tool-id":"regions_search","x-agent-when-to-use":["查地名对应区划代码","模糊搜索省市区","地址里的地名核验"]}},"/v1/regions/{code}":{"get":{"operationId":"regionsGetByCode","parameters":[{"description":"路径参数","in":"path","name":"code","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"成功"},"400":{"description":"参数无效"},"404":{"description":"资源不存在"},"429":{"description":"请求过于频繁"},"500":{"description":"服务器错误"}},"summary":"区划详情"}},"/v1/regions/{code}/ancestors":{"get":{"description":"根据区划代码返回省→市→区县等完整层级路径。","operationId":"regionsAncestors","parameters":[{"description":"路径参数","in":"path","name":"code","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"成功"},"400":{"description":"参数无效"},"404":{"description":"资源不存在"},"429":{"description":"请求过于频繁"},"500":{"description":"服务器错误"}},"summary":"区划层级路径","x-agent-tool-id":"regions_ancestors","x-agent-when-to-use":["已知 adcode 需要补全省市区全称","表单回填省市区"]}},"/v1/time/convert":{"get":{"operationId":"timeConvert","parameters":[{"in":"query","name":"datetime","required":true,"schema":{"type":"string"}},{"in":"query","name":"from","required":false,"schema":{"type":"string"}},{"in":"query","name":"to","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"成功"},"400":{"description":"参数无效"},"404":{"description":"资源不存在"},"429":{"description":"请求过于频繁"},"500":{"description":"服务器错误"}},"summary":"时区与时间转换"}},"/v1/time/now":{"get":{"operationId":"timeNow","parameters":[{"description":"IANA 时区","in":"query","name":"tz","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"成功"},"400":{"description":"参数无效"},"404":{"description":"资源不存在"},"429":{"description":"请求过于频繁"},"500":{"description":"服务器错误"}},"summary":"指定时区当前时间"}},"/v1/time/timestamp":{"get":{"operationId":"timeTimestamp","parameters":[{"in":"query","name":"value","required":true,"schema":{"type":"string"}},{"in":"query","name":"tz","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"成功"},"400":{"description":"参数无效"},"404":{"description":"资源不存在"},"429":{"description":"请求过于频繁"},"500":{"description":"服务器错误"}},"summary":"时间戳互转"}},"/v1/time/timezones":{"get":{"operationId":"timeTimezones","responses":{"200":{"description":"成功"},"400":{"description":"参数无效"},"404":{"description":"资源不存在"},"429":{"description":"请求过于频繁"},"500":{"description":"服务器错误"}},"summary":"时区列表"}},"/v1/validate/bank-card":{"get":{"description":"按 Luhn 算法校验银行卡号格式是否有效。","operationId":"validateBankCard","parameters":[{"in":"query","name":"number","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"成功"},"400":{"description":"参数无效"},"404":{"description":"资源不存在"},"429":{"description":"请求过于频繁"},"500":{"description":"服务器错误"}},"summary":"银行卡号 Luhn 校验","x-agent-tool-id":"validate_bank_card","x-agent-when-to-use":["银行卡号格式校验","支付表单预检"]}},"/v1/validate/idcard":{"get":{"description":"校验中国大陆 18 位居民身份证号码格式与校验位。","operationId":"validateIdcard","parameters":[{"in":"query","name":"number","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"成功"},"400":{"description":"参数无效"},"404":{"description":"资源不存在"},"429":{"description":"请求过于频繁"},"500":{"description":"服务器错误"}},"summary":"居民身份证校验","x-agent-tool-id":"validate_idcard","x-agent-when-to-use":["表单身份证合法性校验","注册前格式检查"]}},"/v1/validate/uscc":{"get":{"operationId":"validateUscc","parameters":[{"in":"query","name":"code","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"成功"},"400":{"description":"参数无效"},"404":{"description":"资源不存在"},"429":{"description":"请求过于频繁"},"500":{"description":"服务器错误"}},"summary":"统一社会信用代码校验"}},"/v1/zipcode/lookup":{"get":{"description":"根据 6 位邮政编码查询对应省市区县地名。","operationId":"zipcodeLookup","parameters":[{"description":"6 位邮政编码","in":"query","name":"zip","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"成功"},"400":{"description":"参数无效"},"404":{"description":"资源不存在"},"429":{"description":"请求过于频繁"},"500":{"description":"服务器错误"}},"summary":"邮编查地名","x-agent-tool-id":"zipcode_lookup","x-agent-when-to-use":["已知邮编查地名","物流地址补全"]}},"/v1/zipcode/search":{"get":{"description":"按地名关键词模糊查询邮政编码。","operationId":"zipcodeSearch","parameters":[{"description":"地名关键词","in":"query","name":"q","required":true,"schema":{"type":"string"}},{"description":"返回条数，默认 20","in":"query","name":"limit","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"成功"},"400":{"description":"参数无效"},"404":{"description":"资源不存在"},"429":{"description":"请求过于频繁"},"500":{"description":"服务器错误"}},"summary":"地名查邮编","x-agent-tool-id":"zipcode_search","x-agent-when-to-use":["知道地名查邮编","地址标准化"]}}},"servers":[{"url":"https://www.resapi.cn"}]}