# 汽车车型库数据
> 来源页面: https://www.gugudata.com/api/details/vehicle-catalog
## 概览
- API 标识: `vehicle-catalog`
- 分类: 元数据/资讯
- 描述: 提供品牌车系车型三级车型库数据
- 标签: 汽车数据 / 车型库
- 短标签: 基础数据 / 汽车数据
- 数据更新时间: 数据校验更新于 10 小时前
- 价格: 2999元/年
- 限时折扣: 1499元/年
- 详情页: https://www.gugudata.com/api/details/vehicle-catalog
- 数据预览: https://www.gugudata.com/preview/vehicle-catalog
## API 功能
- 提供品牌、车系、车型三级车型库数据查询能力；
- 超高的查询性能，保证您的业务稳定；
- 支持品牌到车系、车系到车型的稳定关联查询；
- 每周人工同步复核更新车型库数据，适合业务系统实时获取最新数据；
- 全接口支持 HTTPS（TLS v1.0 / v1.1 / v1.2 / v1.3）；
- 全面兼容 Apple ATS；
- 全国多节点 CDN 部署；
- 接口极速响应，多台服务器构建 API 接口负载均衡。
- 接口调用状态与状态监控: https://www.gugudata.com/status
## API 文档
- 接口地址: `https://api.gugudata.com/v1/vehicleBrands`
- 返回格式: `application/json; charset=utf-8`
- 请求方式: `GET`
- 请求协议: `HTTPS`
- 请求示例: `https://api.gugudata.com/v1/vehicleBrands?appkey=YOUR_APPKEY&pageIndex=1&pageSize=50`
- 接口测试: https://api.gugudata.com/v1/vehicleBrands/demo?pageIndex=1&pageSize=10
- Apifox: https://doc.gugudata.com/
- Postman: https://www.postman.com/gugudata/gugudata-official/collection/1163860-ee114343-4622-4a54-a39b-994173c27dac/?action=share&creator=1163860&active-environment=1163860-a95b31ef-324f-43db-b2fc-faa41f45bd35
- OpenAPI: https://www.gugudata.com/openapi/gugudata.openapi.3.1.json
## 请求参数
| 参数名 | 参数类型 | 是否必须 | 默认值 | 备注 |
| --- | --- | --- | --- | --- |
| appkey | string | 是 | YOUR_APPKEY | 付费后获取的 APPKEY |
| pageindex | integer | 否 | 1 | 页码，从 1 开始 |
| pagesize | integer | 否 | 50 | 每页返回数量，默认 50，最大 100 |
## 返回参数
| 参数名 | 参数类型 | 备注 |
| --- | --- | --- |
| DataStatus.StatusCode | integer | 接口返回状态码，100 为成功 |
| DataStatus.StatusDescription | string | 接口返回状态说明 |
| DataStatus.ResponseDateTime | string | 接口数据返回时间 |
| DataStatus.DataTotalCount | integer | 当前查询条件下的总品牌数量 |
| Data.Items | array | 品牌列表 |
| Data.Items[].BrandId | string | 品牌公开唯一 ID，可与关联接口中的 BrandId 进行关联 |
| Data.Items[].BrandName | string | 品牌名称 |
| Data.PageIndex | integer | 当前页码 |
| Data.PageSize | integer | 当前每页返回数量 |
| Data.TotalSize | integer | 品牌总数量 |
## 相关接口
### 获取品牌下车系列表
- 请求方式: `GET`
- 资源路径: `/v1/vehicleSeries`
- 描述: 根据品牌公开 ID 查询该品牌下的车系列表
#### 请求参数
| 参数名 | 参数类型 | 是否必须 | 备注 |
| --- | --- | --- | --- |
| brand_id | string | 是 | 品牌公开唯一 ID，由主接口返回 |
| appkey | string | 是 | APPKEY（查询参数） |
| pageIndex | integer | 否 | 页码，从 1 开始 |
| pageSize | integer | 否 | 每页返回数量，默认 50，最大 100 |
#### 响应示例
```json
[
{
"Key": "Items",
"Value": [
[
{
"Key": "SeriesId",
"Value": "1967e411adcb0634b7cd5c51a079bb93"
},
{
"Key": "BrandId",
"Value": "95b5e5f7fe82e8caef6805ee5a56afde"
},
{
"Key": "BrandName",
"Value": "大众"
},
{
"Key": "SubBrandId",
"Value": "f4e553fa9e5942dc077ed51d9c51aae4"
},
{
"Key": "SubBrandName",
"Value": "大众(进口)"
},
{
"Key": "SeriesName",
"Value": "途锐"
}
]
]
},
{
"Key": "PageIndex",
"Value": 1
},
{
"Key": "PageSize",
"Value": 10
},
{
"Key": "TotalSize",
"Value": 122
}
]
```
### 获取车系详情
- 请求方式: `GET`
- 资源路径: `/v1/vehicleSeries/{{seriesId}}`
- 描述: 根据车系公开 ID 获取单个车系详情
#### 请求参数
| 参数名 | 参数类型 | 是否必须 | 备注 |
| --- | --- | --- | --- |
| seriesId | string | 是 | 车系公开唯一 ID（路径参数） |
| appkey | string | 是 | APPKEY（查询参数） |
#### 响应示例
```json
[
{
"Key": "SeriesId",
"Value": "1967e411adcb0634b7cd5c51a079bb93"
},
{
"Key": "BrandId",
"Value": "95b5e5f7fe82e8caef6805ee5a56afde"
},
{
"Key": "BrandName",
"Value": "大众"
},
{
"Key": "SubBrandId",
"Value": "f4e553fa9e5942dc077ed51d9c51aae4"
},
{
"Key": "SubBrandName",
"Value": "大众(进口)"
},
{
"Key": "SeriesName",
"Value": "途锐"
}
]
```
### 获取车系下车型列表
- 请求方式: `GET`
- 资源路径: `/v1/vehicleTrims`
- 描述: 根据车系公开 ID 查询该车系下的车型列表
#### 请求参数
| 参数名 | 参数类型 | 是否必须 | 备注 |
| --- | --- | --- | --- |
| series_id | string | 是 | 车系公开唯一 ID，由关联接口返回 |
| appkey | string | 是 | APPKEY（查询参数） |
| pageIndex | integer | 否 | 页码，从 1 开始 |
| pageSize | integer | 否 | 每页返回数量，默认 50，最大 100 |
#### 响应示例
```json
[
{
"Key": "Items",
"Value": [
[
{
"Key": "TrimId",
"Value": "1d56d072e7d6ba79547b6ab32a50fab2"
},
{
"Key": "SeriesId",
"Value": "1967e411adcb0634b7cd5c51a079bb93"
},
{
"Key": "SeriesName",
"Value": "途锐"
},
{
"Key": "BrandId",
"Value": "95b5e5f7fe82e8caef6805ee5a56afde"
},
{
"Key": "SubBrandId",
"Value": "f4e553fa9e5942dc077ed51d9c51aae4"
},
{
"Key": "TrimName",
"Value": "2.0TSI 锐尚版"
},
{
"Key": "Year",
"Value": 2023
}
]
]
},
{
"Key": "PageIndex",
"Value": 1
},
{
"Key": "PageSize",
"Value": 10
},
{
"Key": "TotalSize",
"Value": 12
}
]
```
## 接口 HTTP 响应标准状态码
| 状态码 | 状态码解释 | 备注 |
| --- | --- | --- |
| 200 | 接口正常响应 | 请求成功，业务状态请结合响应体中的自定义业务码判断。 |
| 400 | 请求参数错误 | 请求参数缺失、格式错误或参数组合不合法。 |
| 401 | 鉴权失败 | 缺少 appkey 或 appkey 无效。 |
| 403 | 无权限访问 | 订单到期、权限不足或接口额度不可用。 |
| 404 | 资源不存在 | 请求路径不存在。 |
| 405 | 请求方法不允许 | 当前路径不支持该 HTTP 方法。 |
| 415 | 请求内容类型不支持 | 上传或请求体的内容类型不符合接口要求。 |
| 429 | 请求频率受限 | 一般建议同一个 IP 每秒请求不超过 5 次 (QPS<=5)，我们不限制同一个 key 的请求总次数，但当单位时间内同一个 IP 请求次数过多，或 AI CDN 判定为恶意抓取数据、流量攻击等异常时，CDN 会返回此状态码，请适当降低请求频率。如有特殊大并发请求场景需求，可联系我们添加白名单处理。 |
| 500 | 服务内部错误 | 服务端处理异常，请稍后重试。 |
| 502 | 上游依赖错误 | 上游依赖服务不可用或返回异常。 |
## 接口自定义状态码
| 自定义状态码 | 自定义状态码解释 | 备注 |
| --- | --- | --- |
| 100 | 正常返回 | |
| 501 | 参数错误 | 请检查品牌 ID、车系 ID、分页参数等参数是否正确 |
| 504 | APPKEY 错误 | 请检查传递的 APPKEY 是否正确 |
| 900 | 服务器内部错误 | 请联系技术支持 |
## cURL 请求示例
```bash
curl --location --request GET 'https://api.gugudata.com/v1/vehicleBrands?appkey=YOUR_APPKEY&pageIndex=1&pageSize=50'
```
## 常见问题 Q&A
### Q: 数据请求有缓存吗？
A: 我们为所有数据请求提供实时响应。对于定期更新的数据，我们在其更新周期内实施缓存策略，以优化性能。
### Q: 如何保证请求时 key 的安全性？
A: 建议将 API 请求放置在您的应用程序后端，避免在前端暴露密钥。
### Q: 接口可以用于哪些开发语言？
A: 支持所有可以进行网络请求的开发语言，便于快速集成。
### Q: 接口性能可以保证吗？
A: 接口后台使用商业级架构，您可通过测试接口评估性能。
## 服务协议以及服务免责声明
- [服务协议](https://www.gugudata.com/license)
- [服务免责声明](https://www.gugudata.com/disclaimer)
## 技术支持
- 技术支持邮箱: support@gugudata.com
- 微信客服: https://work.weixin.qq.com/kfid/kfcf9a60a6afe3337b7