{"schema_version":"1.0","name":"ResAPI","description":"中国公共数据只读 API，供 AI Agent、WorkBuddy、Cursor 等中台调用。覆盖节假日、区划、高校、手机号段、邮编、非遗等。","base_url":"https://www.resapi.cn","openapi_url":"https://www.resapi.cn/openapi.json","catalog_url":"https://www.resapi.cn/catalog.json","guide_url":"https://www.resapi.cn/docs/guide","mcp":{"mode":"stdio+http","binary":"resapi-mcp","config_doc":"https://www.resapi.cn/docs/agent/mcp","description":"通过 MCP 暴露 12 个核心工具；支持本地 stdio 或远程 Streamable HTTP","http":{"url":"https://www.resapi.cn/mcp","transport":"streamable-http","description":"无需安装二进制，Cursor / 支持 MCP HTTP 的客户端可直接连接"}},"principles":["只读 GET，无写入与数据托管","手机号、地址、证件等用户查询参数不缓存","当前无需 API Key，按 IP 计数限流","响应 JSON，UTF-8"],"tools":[{"id":"holidays_check","name":"节假日判断","description":"查询中国大陆某日是否为法定节假日、调休工作日或普通周末。","when_to_use":["用户问某天是否放假、要不要上班","判断调休补班日","写日程、排期前确认工作日"],"example_queries":["2026年国庆放假吗","明天要不要上班"],"method":"GET","path":"/v1/holidays/check","operation_id":"holidaysCheck","parameters":[{"name":"date","required":true,"description":"日期 YYYY-MM-DD","example":"2026-10-01"}],"api_category":"holidays"},{"id":"holidays_lunar","name":"农历与节气","description":"查询某日农历、节气、生肖、星座等历法信息。","when_to_use":["公历转农历语境","查节气、生肖","农历生日相关"],"example_queries":["今天农历几月几日","2026年立春是哪一天"],"method":"GET","path":"/v1/holidays/lunar","operation_id":"holidaysLunar","parameters":[{"name":"date","required":true,"description":"日期 YYYY-MM-DD","example":"2026-02-04"}],"api_category":"holidays"},{"id":"regions_search","name":"行政区划搜索","description":"按地名关键词搜索省、市、区县、乡镇等行政区划及标准编码。","when_to_use":["查地名对应区划代码","模糊搜索省市区","地址里的地名核验"],"example_queries":["海淀区区划代码","义乌市属于哪个省"],"method":"GET","path":"/v1/regions/search","operation_id":"regionsSearch","parameters":[{"name":"q","required":true,"description":"地名关键词","example":"海淀"},{"name":"level","required":false,"description":"层级 province/city/district/town/village"}],"api_category":"regions"},{"id":"regions_ancestors","name":"区划层级路径","description":"根据区划代码返回省→市→区县等完整层级路径。","when_to_use":["已知 adcode 需要补全省市区全称","表单回填省市区"],"method":"GET","path":"/v1/regions/{code}/ancestors","operation_id":"regionsAncestors","parameters":[{"name":"code","required":true,"description":"6 位区划代码（路径参数）","example":"110108"}],"api_category":"regions"},{"id":"phone_lookup","name":"手机号段归属","description":"根据 11 位手机号或前 7 位号段查询归属省、市与运营商。","when_to_use":["查手机号归属地","识别运营商","号段是否在库"],"example_queries":["132开头是哪里的号","这个手机号运营商"],"method":"GET","path":"/v1/phone/lookup","operation_id":"phoneLookup","parameters":[{"name":"number","required":true,"description":"11 位手机号或 7 位号段","example":"13213000000"}],"api_category":"phone"},{"id":"validate_idcard","name":"身份证校验","description":"校验中国大陆 18 位居民身份证号码格式与校验位。","when_to_use":["表单身份证合法性校验","注册前格式检查"],"method":"GET","path":"/v1/validate/idcard","operation_id":"validateIdcard","parameters":[{"name":"number","required":true,"description":"18 位身份证号"}],"api_category":"validate"},{"id":"validate_bank_card","name":"银行卡校验","description":"按 Luhn 算法校验银行卡号格式是否有效。","when_to_use":["银行卡号格式校验","支付表单预检"],"method":"GET","path":"/v1/validate/bank-card","operation_id":"validateBankCard","parameters":[{"name":"number","required":true,"description":"银行卡号"}],"api_category":"validate"},{"id":"zipcode_lookup","name":"邮编查地名","description":"根据 6 位邮政编码查询对应省市区县地名。","when_to_use":["已知邮编查地名","物流地址补全"],"method":"GET","path":"/v1/zipcode/lookup","operation_id":"zipcodeLookup","parameters":[{"name":"zip","required":true,"description":"6 位邮编","example":"100020"}],"api_category":"zipcode"},{"id":"zipcode_search","name":"地名查邮编","description":"按地名关键词模糊查询邮政编码。","when_to_use":["知道地名查邮编","地址标准化"],"method":"GET","path":"/v1/zipcode/search","operation_id":"zipcodeSearch","parameters":[{"name":"q","required":true,"description":"地名关键词","example":"朝阳区"}],"api_category":"zipcode"},{"id":"ich_search_projects","name":"非遗项目搜索","description":"搜索中国省级非物质文化遗产代表性项目。","when_to_use":["查非遗项目","文化调研","写非遗相关报告"],"example_queries":["黄梅戏非遗","浙江有哪些非遗"],"method":"GET","path":"/v1/ich/projects/search","operation_id":"ichSearchProjects","parameters":[{"name":"q","required":true,"description":"项目名或关键词","example":"黄梅戏"}],"api_category":"ich"},{"id":"colleges_search","name":"高校搜索","description":"搜索全国高校基础信息（名称、省份、层次等）。","when_to_use":["查大学信息","高考志愿参考","高校名单筛选"],"method":"GET","path":"/v1/colleges/search","operation_id":"collegesSearch","parameters":[{"name":"q","required":true,"description":"高校名称关键词","example":"浙江大学"}],"api_category":"colleges"},{"id":"address_parse","name":"地址解析","description":"从自由文本地址中识别省、市、区县及标准区划编码。","when_to_use":["用户粘贴一整段地址需要结构化","快递单地址解析"],"method":"GET","path":"/v1/address/parse","operation_id":"addressParse","parameters":[{"name":"text","required":true,"description":"待解析地址全文","example":"北京市海淀区中关村大街1号"}],"api_category":"address"}],"aggregates":[{"id":"agent_day","description":"合并工作日判断与农历历法信息","path":"/v1/agent/day","when_to_use":["用户问某天是否放假且需要农历","排期前一次拿齐日历上下文"],"replaces":["/v1/holidays/check","/v1/holidays/lunar"]},{"id":"agent_address","description":"地址解析并补全区划层级路径","path":"/v1/agent/address","when_to_use":["用户粘贴整段地址需要结构化","需要省市区全称与 adcode"],"replaces":["/v1/address/parse","/v1/regions/{code}/ancestors"]},{"id":"agent_phone","description":"手机号段归属与省级区划","path":"/v1/agent/phone","when_to_use":["查手机号归属地","需要运营商与省份区划对象"],"replaces":["/v1/phone/lookup"]},{"id":"agent_zipcode","description":"邮编/地名智能互查","path":"/v1/agent/zipcode","when_to_use":["不确定输入是邮编还是地名","邮编与地名双向查询"],"replaces":["/v1/zipcode/lookup","/v1/zipcode/search"]},{"id":"agent_suggest","description":"按自然语言推荐工具与聚合接口","path":"/v1/agent/suggest","when_to_use":["不确定该调哪个接口","意图路由与工具选择"]}],"integrations":[{"platform":"mcp","description":"Cursor / Claude Desktop / 支持 MCP 的 Agent","doc_url":"https://www.resapi.cn/docs/agent/mcp"},{"platform":"workbuddy","description":"腾讯 WorkBuddy Skill 包","doc_url":"https://www.resapi.cn/docs/agent/workbuddy"},{"platform":"openapi","description":"任意支持 OpenAPI Tool 的 Agent 框架","doc_url":"https://www.resapi.cn/openapi.json"}]}