Skip to main content

EnCarAPI: Python client for Korean and Chinese used car data

Official Python client for EnCarAPI, the REST Encar API and Korean Car API. One package for:

  • Korea: Encar.com, KB Chachacha (source="kbc") and K Car (source="kcar"), with photos, specs, options, inspection reports, accident and ownership records, condition reports, Encar diagnoses, price history, a change feed and full catalog export.
  • China: Dongchedi and Che168 in English via ChinaCarAPI (separate key or the China add-on for EnCarAPI keys).

Built for car exporters, dealers and marketplaces that need reliable used car data without scraping, proxies or geo-blocks.

An API key is required. The data is a paid service. Get a key (5-day trial) at encarapi.com.

Install

pip install encarapi

Requires Python 3.8+ and requests.

Quick start

from encarapi import EnCarAPI

client = EnCarAPI("YOUR_API_KEY")  # or set ENCARAPI_KEY

# Search Korean listings with flat English filters
cars = client.korea.catalog(
    manufacturer="Hyundai",
    max_mileage=60000,
    frame_clean=True,   # accident-free chassis only
    lang="en",
    count=True,
)
print(cars["Count"], cars["SearchResults"][0])

# Full detail, inspection report and insurance record for one car
detail = client.korea.vehicle("12345678")
inspection = client.korea.inspection("12345678")
record = client.korea.record("12345678")

# KB Chachacha and K Car listings, or all three marketplaces deduplicated
kbc = client.korea.catalog(source="kbc", limit=20)
everything = client.korea.catalog(source="all", count=True)

# Chinese listings (Dongchedi + Che168)
byd = client.china.catalog(make="BYD", export_ready=True, limit=25)

Russian and German values

Every Korea call that takes lang="en" also takes lang="ru" or lang="de": fuel, transmission, colors, body class, sell type, regions and options come in Russian or German (with "de" also model and trim names, e.g. C-Klasse, 5er). Ids, codes and numbers stay the same, and the filters accept these values too.

ru = client.korea.catalog(fuel="дизель", lang="ru", limit=10)
de = client.korea.catalog(model_group="C-Klasse", fuel="Benzin", lang="de", limit=10)
enums_de = client.korea.enums(lang="de")  # nameDe per value

China calls take lang="zh" (original Chinese values) or lang="ru": Russian values for the fixed fields (fuel, transmission, drivetrain, colours, seller type, condition, vehicle class), city names and equipment names on catalog, vehicle, vehicle_by_url, bulk_vehicles and specs. Make, model and trim names stay Latin. enums(lang="ru") adds nameRu to fuels and cities, export_csv(lang="ru") / export_to_file(path, lang="ru") return the label columns in Russian.

cn = client.china.catalog(make="BYD", lang="ru", limit=10)

Encar diagnosis

Encar's own body diagnosis (엔카진단, Encar listings only, about three in four active ones): the 8 outer panels with resultCode NORMAL or REPLACEMENT, plus CHECKER_COMMENT (the inspector's verdict, which also states the frame result) and OUTER_PANEL_COMMENT (Korean free text, resultCode None).

diag = client.korea.diagnosis("41192872")
replaced = [i["name"] for i in diag["items"] if i["resultCode"] == "REPLACEMENT"]
# e.g. ["HOOD", "FRONT_FENDER_RIGHT"]

# The same block is in every Encar vehicle detail (None = Encar has no diagnosis for the car)
report = client.korea.vehicle("41192872")["diagnosisReport"]

Without a diagnosis, diagnosis() raises EnCarAPIError with status 404; its JSON body has diagnosisAvailable: false (Encar has no diagnosis for the listing) or detailPending: true (the listing's detail is not collected yet, retry later). bulk_diagnoses(ids) takes up to 500 ids and lists such ids under noDiagnosis / pending. A new or changed diagnosis does not create an event in the change feed. The response shapes are available as TypedDicts for type hints: DiagnosisItem, DiagnosisReport, DiagnosisResponse, DiagnosisBulkResponse.

Keep a local copy in sync (Business / Scale)

Three steps: export to a file, start the change feed at the export's timestamp, then keep the cursor.

# 1) Baseline: stream the full catalog to a file (not held in memory)
export = client.korea.export_to_file("catalog.csv")   # {"path", "bytes", "generated_at"}
import_csv(export["path"])                             # your import: upsert by listing_id

# 2) First sync: start the change feed at the export's generated_at
#    (X-Encarapi-Generated-At, not the time of your download)
for change in client.korea.iterate_changes(since=export["generated_at"]):
    # change["type"]: "added" | "updated" | "reappeared" | "removed"; apply idempotently
    ...
save_cursor(client.korea.last_cursor)

# 3) Every later sync: continue from the saved cursor
for change in client.korea.iterate_changes(cursor=load_cursor()):
    ...
save_cursor(client.korea.last_cursor)

generated_at lies a few minutes before the file's data snapshot, so the first feed page can repeat a few events that are already in the file: apply them as upserts. Use the same source / sell_type for the export and the feed (e.g. export_to_file("kbc.csv", source="kbc"), then iterate_changes(source="kbc", since=...)). export_csv() still returns the CSV as one string, but without the timestamp; for large catalogs use export_to_file(). Trucks and excavators work the same way with export_trucks_to_file() / export_equipment_to_file() and source="truck" / "equipment" on the feed. The file is written to <path>.part first and renamed when complete, so an aborted download never leaves a truncated file under the final name.

The China API works the same way (client.china, header x-generated-at); its events are {"id", "source", "vehicleId", "type": "new" | "price" | "removed" | "relisted", "oldPrice", "newPrice", "at"}:

export = client.china.export_to_file("china-catalog.csv")
for change in client.china.iterate_changes(since=export["generated_at"]):
    # change["type"]: "new" | "price" | "removed" | "relisted"
    ...
save_cursor(client.china.last_cursor)   # later: iterate_changes(cursor=load_cursor())

Korea API (client.korea)

Method Endpoint Notes
catalog(**params) GET /api/catalog Search & list. source: encar (default), kbc, kcar, all
iterate_catalog(**params) GET /api/catalog Generator over all pages
iterate_catalog_by_id(**params) GET /api/catalog?sort=id Complete, stable traversal (keyset cursor, nothing repeated or skipped)
leasing(**params) GET /api/catalog/leasing Lease takeovers and rentals
iterate_leasing_by_id(**params) GET /api/catalog/leasing?sort=id Complete, stable traversal of lease/rental listings
vehicle_by_vin(vin) GET /api/vehicle/by-vin/{vin} All listings of one VIN incl. removed ones (Business/Scale)
trucks(**params) GET /api/catalog/trucks Trucks, buses and special vehicles (Business/Scale)
truck(id) GET /api/catalog/trucks/{id} One truck with detail, inspection report, cargo box, VIN and plate
truck_enums() GET /api/catalog/trucks/enums Truck filter values with counts
trucks_csv() GET /api/catalog/trucks/export Full truck inventory CSV (Business/Scale)
export_trucks_to_file(path, **params) GET /api/catalog/trucks/export Same, streamed to a file: {"path", "bytes", "generated_at"}
iterate_trucks_by_id(**params) GET /api/catalog/trucks?sort=id Complete, stable traversal of the truck catalog
equipment(**params) GET /api/catalog/equipment Used excavators (Business/Scale)
equipment_enums() GET /api/catalog/equipment/enums Equipment filter values with counts
equipment_csv() GET /api/catalog/equipment/export Full equipment inventory CSV (Business/Scale)
export_equipment_to_file(path, **params) GET /api/catalog/equipment/export Same, streamed to a file: {"path", "bytes", "generated_at"}
iterate_equipment_by_id(**params) GET /api/catalog/equipment?sort=id Complete, stable traversal of the equipment catalog
nav(**params) GET /api/nav Filter facets with counts
enums(**params) GET /api/enums Valid values for the flat filters
model_search(search, **params) GET /api/model-search Model autocomplete
vehicle(id) GET /api/vehicle/{id} Ids: Encar id, kbc:<id>, kcar:<id>
inspection(id) GET /api/inspection/{id} Official inspection report
record(id) GET /api/record/{id} Accident & ownership record
diagnosis(id) GET /api/diagnosis/{id} Encar diagnosis (엔카진단): outer panels replaced or not, inspector verdict; Encar ids only
refresh(id) POST /api/vehicle/{id}/refresh On-demand refresh (daily quota)
price_check(id) GET /api/price-check/{id} Market estimate (beta, Scale)
bulk_vehicles(ids) / bulk_inspections(ids) / bulk_records(ids) / bulk_diagnoses(ids) POST /api/.../bulk Up to 500 ids (Business/Scale)
inspection_versions(id) / record_versions(id) GET /api/.../versions Report history (Business/Scale)
changes(**params) / iterate_changes(**params) GET /api/catalog/changes Incremental sync (Business/Scale)
export_csv(**params) GET /api/catalog/export Full catalog CSV (Business/Scale); sell_type="lease,rental" for lease/rental
export_to_file(path, **params) GET /api/catalog/export Same export streamed to a file: {"path", "bytes", "generated_at"} (start of the change feed)
makes_csv() / models_csv() / badges_csv() GET /api/taxonomy/*.csv Reference data

China API (client.china)

Method Endpoint Notes
catalog(**params) GET /api/catalog make, price_min/max (CNY), power_min/max (hp), export_ready, sort, lang (zh, ru), ...
iterate_catalog(**params) GET /api/catalog Generator over all pages (up to the 10,000-result depth limit)
vehicle(id) GET /api/vehicle/{id} Price history, photos, seller, export status
vehicle_by_url(url) GET /api/vehicle/by-url Same record by Che168/Dongchedi listing link (desktop, mobile or app)
inspection(id) GET /api/inspection/{id} Accident, flood and fire checks, EV battery data
specs(trim_id, **params) GET /api/specs/{trimId} Autohome trim sheet of a Che168 car: cc, kW, hp, torque, emission standard, weights, EV battery
bulk_vehicles(ids) POST /api/vehicle/bulk Up to 500 ids
changes(**params) / iterate_changes(**params) GET /api/catalog/changes Change feed (Business/Scale)
export_csv(**params) GET /api/catalog/export Full catalog CSV; lang="ru" for Russian label columns
export_to_file(path, **params) GET /api/catalog/export Same export streamed to a file: {"path", "bytes", "generated_at"} (start of the change feed)
enums(**params) / models(make) GET /api/enums, /api/models Filter values (lang="ru" adds nameRu), models per make

China only? from encarapi import ChinaCarAPI (also available as the chinacarapi package).

Errors

Every failed request raises EnCarAPIError with status and the raw body. A 403 on a plan-gated endpoint includes an upgrade hint from the API.

from encarapi import EnCarAPIError

try:
    client.korea.changes(cursor=0)
except EnCarAPIError as e:
    if e.status == 403:
        print("Plan does not include this endpoint:", e.body)

EnCarAPI is an independent service and not affiliated with Encar, KB Chachacha, K Car, Dongchedi or Che168.

License

MIT

Metadata

Release files for encarapi 1.8.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for encarapi 1.8.0
File Size Uploaded Provenance Actions
encarapi-1.8.0.tar.gz 43.0 kB Without provenance Details for encarapi-1.8.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for encarapi 1.8.0
File Interpreter ABI Platform Actions
encarapi-1.8.0-py3-none-any.whl Python 3 none any Details for encarapi-1.8.0-py3-none-any.whl

Total release size: 57.9 kB

Release files / encarapi-1.8.0.tar.gz

Download URL encarapi-1.8.0.tar.gz
Size 43.0 kB
Tags Source
SHA-256 checksum
How to use checksums
f2b2a4ead55e4cea50be7d69b4cbbeee624d1c11595a89b5040f58921a1d6897
BLAKE2b-256 checksum
How to use checksums
c742800287934a8c2aa4908657566a2b5730e19e4967643fd0c796ee33e4aac2
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.10.4 {"installer":{"name":"uv","version":"0.10.4","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Release files / encarapi-1.8.0-py3-none-any.whl

Download URL encarapi-1.8.0-py3-none-any.whl
Size 14.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
925c8b885e4262f0ce778c87854c046e00c2c7f3a6ed4c9318991faa6c12d8a0
BLAKE2b-256 checksum
How to use checksums
2d85bc79dda28910697572c4b326e6a1de8cec50d49ee3f1594b5c4047a6f567
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.10.4 {"installer":{"name":"uv","version":"0.10.4","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Security for encarapi 1.8.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page