# @cardog/api 中文文档

规范地址：https://npmcn.com/package/%40cardog/api/

版本：3\.4\.0
npm 元数据更新时间：2026-11-05T19:08:03.600Z
中文译文更新时间：2026-11-09T12:27:53.215Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40cardog/api
原文对照：https://npmcn.com/package/%40cardog/api/?lang=original
项目主页：https://cardog.app/docs

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：4.2 MB，12 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：react ^18\.0\.0 \|\| ^19\.0\.0，react-dom ^18\.0\.0 \|\| ^19\.0\.0，@tanstack/react-query ^5\.0\.0
- 首次发布：2026-03-15T18:52:51.360Z
- 最新版本发布：2026-11-05T19:08:03.424Z
- 近 30 天下载量：2734（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：21（近 12 个月 19 个）

## 中文简介

Cardog API的TypeScript客户端——加拿大VIN解码,车辆规格,活上市,市场报价,以及Transport Canada + NHTSA回想.

## 安装

```sh
npm install @cardog/api
```

也可以使用：`pnpm add @cardog/api`、`yarn add @cardog/api`、`bun add @cardog/api`

## README

# @ cardog/ api (帮助)

Cardog API的TypeScript客户端——加拿大车辆的记录系统. 解码VINs,解析姓名给永久裁判,搜索加拿大的活版名单,引用 请检查access-date=中的日期值 (帮助) Market,并检查 Transport Canada + NHTSA 回顾一键后.

## 安装

```bash
npm install @cardog/api
# or
pnpm add @cardog/api
# or
yarn add @cardog/api
```

对于反应钩,也安装:

```bash
npm install @tanstack/react-query
```

## 快开始

```ts
import { CardogV2 } from "@cardog/api";

const cardog = new CardogV2({ apiKey: process.env.CARDOG_API_KEY });

// Free text enters exactly once. Everything after this takes refs.
const { best } = await cardog.entities.resolve("2021 Civic");
// best.ref === "model-year:honda/civic/2021"

const vehicle = await cardog.vin.getByVin("2HGFC2F53MH500001");
const recalls = await cardog.recalls.vin("2HGFC2F53MH500001");
const quote = await cardog.quotes.getByRef(best.ref);
```

加拿大VIN解码覆盖率为 99.77%. 类型、方法和出错来自 aPI 验证的 OpenAPI 合同相同,所以客户端不能从中漂移 服务器.

**错误是按键和可操作的 .** 每个非-2xx携带 `{ code, message, hint, docs_url, suggestions }`。一位未知的裁判返回了400个名字,并提示 最近的真人——API从不把你们弄错了.

```ts
import { APIErrorV2 } from "@cardog/api";

try {
  await cardog.listings.search({ filters: { makes: ["make:teslla"] } });
} catch (err) {
  if (err instanceof APIErrorV2) {
    err.code; // "unknown_entity_refs"
    err.hint; // what to do instead
    err.suggestions; // nearest real refs — advisory, never auto-applied
  }
}
```

整个平台在一个获取中 : **[https://cardog.app/docs.md\* (中文(简体) )](https://cardog.app/docs.md*)\* 联合国 参考: [https://cardog.app/docs (英语)](https://cardog.app/docs) ·: `pip install cardog` 校正离线: [`@cardog/entities`](https://www.npmjs.com/package/@cardog/entities)**

## 种子

{\\fn黑体\\fs22\\bord1\\shad0\\3aHBE\\4aH00\\fscx67\\fscy66\\2cHFFFFFF\\3cH808080}一个信号 {\\fn黑体\\fs22\\bord1\\shad0\\3aHBE\\4aH00\\fscx67\\fscy66\\2cHFFFFFF\\3cH808080}是组织自己的一套车辆身份线 {\\fn黑体\\fs22\\bord1\\shad0\\3aHBE\\4aH00\\fscx67\\fscy66\\2cHFFFFFF\\3cH808080}每天晚上重建 作为文件移交。 与组织阅读 `crdg_org_` 键。 每一个种子读取 成本0入分.

```ts
import { CardogClient } from "@cardog/api";

const client = new CardogClient({ apiKey: process.env.CARDOG_ORG_KEY });

const { feeds } = await client.v2.feeds.list();

const run = await client.v2.feeds.latest("vehicle-identity@1");
run.runId; // the SHA-256 of the uncompressed full file
run.deliveryId; // the complete delivery context, when present
run.columns; // the files' columns, in order, under the names the organization chose
run.manifest; // kind, baselineRunId, artifacts with record counts and hashes

// Rows, streamed. The file is never held in memory.
for await (const row of run.rows("delta")) {
  // new and changed rows since the run before
}

// Keep your own copy current. Picks the full file or the change file for you,
// checks every file against its SHA-256 first, and returns where you now stand.
const result = await client.v2.feeds.sync("vehicle-identity@1", {
  since: lastRunId, // what the previous sync returned; omit the first time
  sinceDeliveryId: lastDeliveryId, // retain the delivery ID when the result has one
  reset: () => store.clear(),
  upsert: (row) => store.upsert(row),
  remove: (key) => store.remove(key),
});
lastRunId = result.runId; // result.mode is "full", "delta" or "unchanged"
lastDeliveryId = result.deliveryId; // save both IDs only after a successful sync

// Answer a VIN.
const index = await run.index();
const row = index.lookup("2T3W1RFV3SC776931"); // the row, or null when the pattern is not in the feed
```

`run.rows(role)`, (中文(简体) ), `run.toJSON(role)` 财务报告和审定财务报表 `run.artifact(role)` 带 `"full"` (默认), `"delta"` 或者说 `"deletes"`。 。 。 . `run.artifact(role)` 实值 `null` 当运行没有此类文件时. CSV, JSON Lines 和 JSON 运行, 普通或gziped, 在浏览器和浏览器中读取相同的方式 节点. 指南 : [汽车狗.app/docs/feeds](https://cardog.app/docs/feeds)。 。 。 .

完整的校验和可以识别内容 。 交货身份证上还注明了合同, 基准和审评背景。 等同的全验收和可以有不同的交付ID. 准确的发送,同步返回 `unchanged` 只当两个保存的ID匹配。 A 类 三角洲必须匹配两个基线ID. 如果上下文不存在或不同, 请同步 需要完全重设 。 年长的制片人的准确记录可以忽略公众 基线交付ID;同步后使用完整文件。 遗产饲料保留 已存在的行为. `currentDeliveryId()` 返回当前准确的ID,或 `null` 用于遗产运行或无当前运行.

这个 [同步执行](https://npmcn.com/package/%40cardog/api/src/v2/feeds.ts) 检查两个身份. 这个 [交付同步测试](https://npmcn.com/package/%40cardog/api/test/unit/feed-delivery-sync.test.ts) 封面重现, 三角洲 错过了交货 还有遗留记录 使用 [MTO 堆栈指南](https://npmcn.com/package/%40cardog/feeds/PR_STACK.md) 以审查完整的制作路径.

## 反应钩

```tsx
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import { CardogClient } from "@cardog/api";
import { createHooks } from "@cardog/api/react";

const queryClient = new QueryClient();
const client = new CardogClient({ apiKey: "your-api-key" });
const { useVinDecode, useMarketOverview, useListingsSearch } = createHooks(client);

function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <VehicleLookup />
    </QueryClientProvider>
  );
}

function VehicleLookup() {
  const { data, isLoading, error } = useVinDecode("1HGCM82633A123456");

  if (isLoading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;

  return (
    <div>
      {data?.make} {data?.model} ({data?.year})
    </div>
  );
}
```

## API 参考

以下各节记录 **遗留 v1 表面** (单位:千美元)`CardogClient`) (中文(简体) ). 新整合 应使用快速启动时显示的 v2 组—— `CardogV2` (或 `new CardogClient().v2`: `entities`, (中文(简体) ), `vin`, (中文(简体) ), `specs`, (中文(简体) ), `listings`, (中文(简体) ), `instruments`, (中文(简体) ), `quotes`, (中文(简体) ), `tape`, (中文(简体) ), `recalls`, (中文(简体) ), `safety`, (中文(简体) ), `feeds`, (中文(简体) ), `platform` ——全文记载于 [车犬.app/docs](https://cardog.app/docs)。 。 。 .

### VIN 解码

```typescript
// Decode a VIN
const vehicle = await client.vin.decode("1HGCM82633A123456");

// Decode from image (base64)
const result = await client.vin.image(base64Image);
```

### 市场分析

```typescript
// Market overview for a specific vehicle
const overview = await client.market.overview("Toyota", "Camry", 2022);

// Price distribution
const pricing = await client.market.pricing("Honda", "Civic", 2021);

// Geographic breakdown
const geography = await client.market.geography("Ford", "F-150", 2023);

// Market trends over time
const trends = await client.market.trends("Tesla", "Model 3", 2022, "month");

// Listing market position
const position = await client.market.position("listing-id");

// Overall market pulse
const pulse = await client.market.pulse({
  priceRangeMin: 20000,
  priceRangeMax: 50000,
});
```

### 车辆清单

```typescript
// Search listings with filters
const results = await client.listings.search({
  makes: ["Toyota", "Honda"],
  models: { Toyota: ["Camry", "Corolla"] },
  year: { min: 2020, max: 2024 },
  price: { min: 15000, max: 40000 },
  odometer: { max: 50000 },
  bodyStyles: ["Sedan", "SUV"],
  fuelTypes: ["Gasoline", "Hybrid"],
});

// Get listing count
const count = await client.listings.count({ makes: ["BMW"] });

// Get facets for filtering UI
const facets = await client.listings.facets({ makes: ["Mercedes-Benz"] });

// Get specific listing
const listing = await client.listings.getById("listing-id");
```

### 安全回顾

```typescript
// Search recalls
const recalls = await client.recalls.search({
  country: "us", // or "ca" for Canada
  makes: ["Toyota"],
  models: ["RAV4"],
  year: { min: 2019, max: 2023 },
});
```

### 研究和光谱

```typescript
// Get vehicle lineup for a make
const lineup = await client.research.lineup("Toyota");

// Get model year details
const modelYear = await client.research.modelYear("Toyota", "Camry", 2023);

// Get vehicle images
const images = await client.research.images("Toyota", "Camry", 2023);

// Get available colors
const colors = await client.research.colors("Honda", "Civic", 2024);
```

### 燃料和充电

```typescript
// Find gas stations
const gasStations = await client.fuel.search({
  lat: 43.6532,
  lng: -79.3832,
  radius: 10,
  fuelType: "REGULAR",
});

// Find EV charging stations
const chargers = await client.charging.search({
  lat: 43.6532,
  lng: -79.3832,
  radius: 25,
  minPower: 50, // kW
});
```

### 地点

```typescript
// Search dealer/seller locations
const dealers = await client.locations.search({
  lat: 43.6532,
  lng: -79.3832,
  radius: 50,
});

// Get seller details
const seller = await client.locations.getById("seller-id");
```

### EPA 效率

```typescript
// Search EPA fuel economy data
const efficiency = await client.efficiency.search({
  make: "Toyota",
  model: "Prius",
  year: 2023,
});
```

### NHTSA 投诉

```typescript
// Search vehicle complaints
const complaints = await client.complaints.search({
  make: "Ford",
  model: "Explorer",
  year: { min: 2020, max: 2023 },
});
```

## 处理错误

每个 v2 失败投出 `APIErrorV2` 装满了错误信封—— `code`, (中文(简体) ), `hint`, (中文(简体) ), `docsUrl`,违法者 `refs`,最接近时 `suggestions`,和外地一级 `details`。 。 。 . 看上面的快速开始 对于平庸的捕捉。 遗留 v1 路径抛出 `APIError` (单位:千美元)`status` 编号 : `code` 编号 : `message` 编号 : `data`) (中文(简体) ).

## 查询密钥

手动反应查询集成 :

```typescript
import { queryKeys } from "@cardog/api";

// Use in custom queries
const { data } = useQuery({
  queryKey: queryKeys.vin.decode("1HGCM82633A123456"),
  queryFn: () => client.vin.decode("1HGCM82633A123456"),
});

// Available key factories
queryKeys.vin.decode(vin)
queryKeys.market.overview(make, model, year)
queryKeys.listings.search(params)
queryKeys.recalls.search(params)
// ... and more
```

## 配置

```typescript
const client = new CardogClient({
  apiKey: "your-api-key",
  baseUrl: "https://api.cardog.app", // Default
});

// Update config at runtime
client.setConfig({
  apiKey: "new-api-key",
});
```

## 定价

使用量是每个呼叫家庭的信用计量,您下一次呼叫的价格是在 上一个标题( e)`X-Credits-Rate`, (中文(简体) ), `X-Credits-Remaining`) (中文(简体) ). 客户保留 最后一组解析 `client.lastCredits`(a 402 表示预算) 因此,从不读取原始标题:

```typescript
await client.v2.vin.getByVin("5YJSA1E28MF420053");
const { rate, remaining, allowance, reset, source } = client.lastCredits!;
// rate: what that call cost · remaining: allowance headroom + pack balance
// (-1 = custom plan) · reset: when the allowance rolls over · source: which
// pool paid ("allowance" | "pack" | "overage"), null when nothing was debited
```

机器可读率卡是免费的终点—— `await client.v2.pricing()` - 和 人类是 [汽车狗.应用/定价](https://cardog.app/pricing)。 。 。 .

## 链接

-   [API 文档](https://cardog.app/docs)
-   [获取 API 密钥](https://cardog.app/account/api)
-   [定价](https://cardog.app/pricing)
-   [更改日志](https://cardog.app/changelog)

## 相关软件包

-   [`@cardog/entities`](https://www.npmjs.com/package/@cardog/entities) - 参考语法:校正、构建和生成脱机参考(Apache-2.0,无密钥)
-   [`@cardog/corgi`](https://www.npmjs.com/package/@cardog/corgi) - 离线VIN解码器(不需要API密钥)
-   [`cardog` 关于 PyPI](https://pypi.org/project/cardog/) - 这个SDK的Python兄弟

## 许可证

麻省理工学院

## 常见问题

### @cardog/api 是什么？

Cardog API的TypeScript客户端——加拿大VIN解码,车辆规格,活上市,市场报价,以及Transport Canada \+ NHTSA回想\.

### 如何安装 @cardog/api？

在项目目录运行 npm install @cardog/api，或使用 pnpm add / yarn add / bun add。

### @cardog/api 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @cardog/api 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @cardog/api 可以商用吗？

@cardog/api 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @cardog/api 的下载量有多少？

根据 npm 官方下载统计，@cardog/api 在 2026/10/09 – 2026/11/07 这 30 天内被下载 2,734 次，日均约 91 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @cardog/api 还在维护吗？

最新版本 3\.4\.0 发布于 2026/11/06（3 天前）；至今共发布 21 个版本，其中过去 12 个月发布了 19 个；首次发布于 2026/03/16。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。