文档

基础URL

所有API请求都发送到以下基础URL：

https://api.encarapi.com

例如，获取车辆列表：

GET https://api.encarapi.com/api/catalog?manufacturer=bmw&fuel=diesel&lang=en&count=true

身份验证

使用API密钥验证您的请求。通过查询参数或Authorization头传递。

# Send your API key in the x-api-key header (recommended):
curl -H "x-api-key: YOUR_API_KEY" \
  "https://api.encarapi.com/api/catalog?manufacturer=bmw&fuel=diesel&lang=en&count=true"

# The api_key query parameter also works:
GET https://api.encarapi.com/api/catalog?manufacturer=bmw&fuel=diesel&lang=en&count=true&api_key=YOUR_API_KEY

5 天试用

5 天内体验 API，覆盖全部三个交易平台（Encar、KB Chachacha、K Car），包括变更同步（最近 7 天）、批量查询（每天 1,000 个 id）和归档预览（每天 100 个已下架车源）。目录数据总计 100,000 行，详情查询总计 2,000 次（每天最多 1,000 次）。参考数据下载（CSV）包含在付费方案中。完整目录导出从 Business 方案起提供。试用结束后，您的订阅将以 Starter 方案（每月 €149）自动续订 - 可在第 5 天前随时取消。

俄语值 (lang=ru)

所有接受 lang=en 的端点也接受 lang=ru：显示值以俄语返回，其余内容 (ID、代码、价格、数字、字段名) 保持不变。没有俄语标签的值会回退为英语。俄语标签可能会逐步完善，因此请用 ID 和代码而不是标签来关联数据。

• 翻译范围：燃料、变速箱、驱动方式、车身颜色和内饰颜色、车身级别、销售类型、地区和城市名称、配置名称以及配置版本名称中的通用词 (Diesel -> дизель, 7-Seater -> 7 мест)。车型代数：Carnival 4 Gen -> Carnival 4 поколение。品牌、车型和版本名称保持拉丁字母，与俄罗斯汽车网站一致。
• 筛选参数也接受俄语值：fuel=дизель, color=белый, region=Сеул, city=Сувон, drivetrain=полный, sell_type=лизинг。英语值继续有效。
• /api/enums?lang=ru 为每个值添加 nameRu，并列出 drivetrain 和 sell_type 的值。/api/nav?lang=ru 返回俄语 DisplayValue；Value 仍是用于筛选的英语代码。参考 CSV 加上 lang=ru 后，会在最后一列之后多出一列俄语名称。
• /api/vehicle/{id}?lang=ru 和 bulk 端点以俄语返回 Encar 的 spec 值、category 名称和 optionsDecoded 名称，KB Chachacha 车源与目录中一致。
• /api/catalog/export?lang=ru 是同一个文件，只是标签列为俄语；列顺序和其他所有列不变。
• 不翻译：检测报告、保险记录、Encar 诊断、Encar 车辆历史、K Car 详情数据、Encar 选装包 (车源中的自由文本)，以及卡车和挖掘机端点 (使用 lang=ru 时以英语返回)。

# Russian values, filtered with Russian values
curl -H "x-api-key: YOUR_API_KEY" \
  "https://api.encarapi.com/api/catalog?fuel=дизель&city=Сувон&lang=ru&count=true"

# Filter values with their Russian labels (nameRu)
curl -H "x-api-key: YOUR_API_KEY" \
  "https://api.encarapi.com/api/enums?lang=ru"

德语值 (lang=de)

lang=de 与 lang=ru 的用法相同：显示值以德语返回，其余内容 (ID、代码、价格、数字、字段名) 保持不变。没有德语标签的值会回退为英语。

• 翻译范围：燃料、变速箱、驱动方式、颜色、车身级别、销售类型、配置名称，以及我们德语表中的车型和版本名称 (C-Class -> C-Klasse, 5-Series -> 5er, Carnival 4 Gen -> Carnival 4. Generation, 7-Seater -> 7-Sitzer, Sedan -> Limousine)。地区使用英文名称，城市名称保持英文。
• 筛选参数也接受德语值：fuel=Benzin, color=Weiß, transmission=Automatik, drivetrain=Allrad, sell_type=Leasingübernahme, model_group=C-Klasse。德语车型名称可能合并改款前后车型：Carnival 4. Generation 同时包含 Carnival 4 Gen 和 The New Carnival 4 Gen。
• 列表、详情、bulk 和导出与 lang=ru 相同：/api/enums 和 /api/taxonomy/option-packages 中的 nameDe，/api/nav 中的德语 DisplayValue，参考 CSV 中的 *_de 列，导出文件为 catalog_export_de.csv。不翻译的内容与 lang=ru 相同。

# German values, filtered with German values
curl -H "x-api-key: YOUR_API_KEY" \
  "https://api.encarapi.com/api/catalog?manufacturer=Mercedes-Benz&model_group=C-Klasse&fuel=Benzin&lang=de&count=true"

三大平台，一个API

本API提供韩国三大二手车平台的实时车源。所有端点默认返回 Encar，因此现有集成无需改动即可继续使用。另外两个平台通过 source 参数按需启用。

选择数据来源

source 可用于 /api/catalog、/api/nav、/api/enums、/api/model-search、/api/catalog/export、/api/catalog/changes 以及分类数据CSV。

# All three marketplaces, English values
curl -H "x-api-key: YOUR_API_KEY" \
  "https://api.encarapi.com/api/catalog?source=all&manufacturer=bmw&fuel=diesel&lang=en&count=true"

# K Car only
curl -H "x-api-key: YOUR_API_KEY" \
  "https://api.encarapi.com/api/catalog?source=kcar&manufacturer=hyundai&lang=en"

# One KB Chachacha vehicle
curl -H "x-api-key: YOUR_API_KEY" \
  "https://api.encarapi.com/api/vehicle/kbc:12345678?lang=en"

设置 source 后，每个条目都带有 Source 字段。Encar 的 id 仍为纯数字。KB Chachacha 和 K Car 的 id 带有前缀 (kbc:..., kcar:...) - 请原样传给 /api/vehicle/{id}。使用 lang=en 时，三个平台的车型和配置版本名称均以英文返回。

经销商经常将同一辆车同时发布在 Encar 和 KB Chachacha 上。KB Chachacha 车源通过韩国车牌号与在售的 Encar 车源匹配；如果 KB Chachacha 未公布车牌，则按首次登记年月、里程和价格匹配。匹配结果每天重新计算多次，即每次 Encar 和 KB Chachacha 目录遍历之后。无论是否设置 source（包括只设置 source=kbc），/api/catalog、/api/catalog/export 及其他目录接口都不会返回已匹配的 KB Chachacha 车源，因此同一辆车绝不会出现两次；包含 Encar 时，它以 Encar 车源的形式返回。

在 /api/catalog/changes?source=kbc 和 /api/vehicle/kbc:{id} 中，这些车源带有 IsDuplicate: true 和 DuplicateOf（Encar 车源 ID，数字字符串）；与 Encar 条目相同，这两个字段仅在为 true 时出现。设置或取消该标记时，变更推送会记录一条 updated 事件，其 changedFields 包含 duplicate。要让本地副本与 /api/catalog 保持一致，请删除带 IsDuplicate: true 到达的 KB Chachacha 条目，并在收到不带该字段的更新时重新添加。

变更推送每次调用只接受一个来源 (encar、kbc 或 kcar)，并为每个来源维护独立的游标。

各平台覆盖范围

并非每个平台都公开所有字段。

• KB Chachacha 部分车源公开座位数。
• KB Chachacha 详情 = 目录条目加上公开历史信息块 (事故标记、全损、泡水、营运用途、抵押、车架和钣金件诊断)。 每个 KB Chachacha 条目还包含 InsuranceClaims：车源页面上显示的保险事故记录次数。详情还包含 InspectionReportUrl 和 InspectionReportType：即 KB Chachacha 为该车展示的检测单（link = 检测机构网站上的报告，scan = 车源页面上仅有扫描图片，null = 尚未知）。InspectionAvailable 为 true 时，GET /api/inspection/kbc:{id} 会将该检测单以结构化数据返回，格式与 Encar 检测报告相同（master、outers、inners、images），并附带 source 信息块；在附有检测单的 KB Chachacha 车源中，约五分之二可以这样获取。
• K Car 没有单独的报告文档；事故次数、保险赔付和过户记录包含在车辆详情中。

按某个平台不提供的字段进行筛选时，该平台的车辆会被排除在结果之外。示例：frame_clean=true 搭配 source=all 只返回 Encar 和 K Car 的车源。

API端点

所有可用于访问韩国车辆数据的端点。

下拉列表数据（CSV）

将品牌、车型和徽标列表以 CSV 格式下载并缓存，然后据此构建你的下拉列表 - 无需每次点击调用分面接口，也无需离线映射。每个文件都包含一个数量列，徽标文件还包含车身样式的细分（Coupe／Sedan／Cabrio）。

常见问题