宠物大全API怎么接入名称详情分类列表与评分字段如何建模

发布时间：2026-08-18 11:20 点击：7401次

宠物大全 API 应把分类列表用于发现宠物名称，再按名称查询详情；粘人、喜叫、友善等 1 至 5 级字段适合内容筛选，不应被解释成对某只宠物个体行为或健康状况的保证。

宠物大全 API 有哪些查询路径

截至 2026 年 8 月 18 日，极速数据宠物大全 API 提供按名称查询详情和按类型分页获取列表两个端点。两个端点当前均使用 GET 请求。

任务	端点	主要参数
按名称查询详情	`https://api.jisuapi.com/pet/query`	`name` 必填
按类型获取列表	`https://api.jisuapi.com/pet/byclass`	`type`、`page`、`pagesize` 可选

如果用户已经知道宠物名称，可直接走详情查询；如果需要浏览猫咪或狗狗品种，应先走分类列表，再把列表中的名称传给详情端点。官方参数表没有列出独立的宠物 ID，因此名称是当前两条路径之间的主要关联值。

分类列表怎样分页

分类列表的 type 默认为 0，表示狗狗；1 表示猫咪。page 默认 1，pagesize 默认 1，最大 10。

curl --get "https://api.jisuapi.com/pet/byclass" \
  --data-urlencode "appkey=YOUR_APPKEY" \
  --data-urlencode "type=1" \
  --data-urlencode "page=1" \
  --data-urlencode "pagesize=10"

返回结果包含总数、当前页、每页条数以及由名称和图片组成的列表。业务侧应使用返回的 total 判断是否还有下一页，不要假设每页一定返回请求数量。type 应限制为文档列出的值；若产品还需要其他宠物类别，当前页面没有给出相应枚举，不能自行添加并声称接口支持。

列表适合作为浏览入口，不宜承载完整详情。用户点击某一项后，再以列表返回的原始名称调用详情接口，可以减少手工输入的别名和错别字问题。

怎样按名称查询宠物详情

详情端点要求 name，官方示例使用宠物名称进行查询。

curl --get "https://api.jisuapi.com/pet/query" \
  --data-urlencode "appkey=YOUR_APPKEY" \
  --data-urlencode "name=YOUR_PET_NAME"

后端应先去除首尾空格，但不要擅自截断名称或使用模糊匹配替换用户输入。若需要支持俗称、别名或中英文名称，可以在自有系统维护别名到官方名称的映射，并保留用户原始输入，以便无结果时排查。

APPKEY 应由服务端持有。客户端请求自有后端，由后端完成参数校验、缓存、错误转换和日志脱敏，避免密钥随着网页或安装包分发。

详情字段应该怎样分层

详情参数表包含名称 name、外文名称 engname、原产地 nation、寿命 life、价格 price、图片 pic，以及基本信息 message、喂养方法 feed、优缺点 relative 和鉴别方法 pick。

这些字段可以分为三层：

身份与概览：名称、外文名称、原产地和图片。
描述性资料：寿命、价格、基本信息、喂养方法、优缺点和鉴别方法。
等级字段：粘人、喜叫、友善、掉毛、美容、体味、口水和可训程度。

自有系统可以保存原始字段，并增加抓取时间：

{
  "source": "jisuapi-pet",
  "sourceName": "SOURCE_PET_NAME",
  "englishName": "SOURCE_ENGLISH_NAME",
  "ratings": {
    "clinginess": "SOURCE_VALUE",
    "vocalization": "SOURCE_VALUE",
    "friendliness": "SOURCE_VALUE",
    "shedding": "SOURCE_VALUE",
    "grooming": "SOURCE_VALUE",
    "odor": "SOURCE_VALUE",
    "drooling": "SOURCE_VALUE",
    "trainability": "SOURCE_VALUE"
  },
  "fetchedAt": "ISO_TIMESTAMP"
}

这是业务侧映射示例，键名是对官方八项等级概念的内部命名，不代表官方原始响应。文档参数表将等级字段标为字符串，并说明范围为 1 至 5、由低到高；接入时应允许字符串或数字形式，再规范化为内部整数。超出范围、为空或无法解析的值应标记未知，不能自动修正为最近的等级。