encarapi 1.0.0__tar.gz

encarapi-1.0.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+venv/
+.env
+.env.local
+.DS_Store

encarapi-1.0.0/LICENSE

@@ -0,0 +1,25 @@
+MIT License
+
+Copyright (c) 2026 EnCarAPI (encarapi.com)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+Note: This MIT license covers the client library only. Access to the EnCarAPI
+service and its data requires a valid API key and is subject to the terms at
+https://encarapi.com.

encarapi-1.0.0/PKG-INFO

@@ -0,0 +1,152 @@
+Metadata-Version: 2.5
+Name: encarapi
+Version: 1.0.0
+Summary: Official Python client for EnCarAPI: Korean used car data (Encar, KB Chachacha, K Car) and Chinese used car data (Dongchedi, Che168) in one REST API.
+Project-URL: Homepage, https://encarapi.com
+Project-URL: Documentation, https://encarapi.com/documentation
+Project-URL: Source, https://github.com/ThatMojo/encarapi-python
+Project-URL: China data, https://chinacarapi.com
+Author-email: EnCarAPI <support@encarapi.com>
+License: MIT
+License-File: LICENSE
+Keywords: car export,che168,china car api,chinese used car data,dongchedi,encar,encar api,encar.com,k car,kb chachacha,kbchacha,kcar,korea car api,korean car api,korean used car data,vehicle data api
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Requires-Dist: requests>=2.20
+Description-Content-Type: text/markdown
+
+# EnCarAPI: Python client for Korean and Chinese used car data
+
+Official **Python client** for [EnCarAPI](https://encarapi.com), 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, price history, a change feed and full catalog export.
+- **China:** Dongchedi and Che168 in English via [ChinaCarAPI](https://chinacarapi.com)
+  (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](https://encarapi.com)**.
+
+## Install
+
+```bash
+pip install encarapi
+```
+
+Requires Python 3.8+ and `requests`.
+
+## Quick start
+
+```python
+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)
+```
+
+## Keep a local copy in sync (Business / Scale)
+
+```python
+csv_text = client.korea.export_csv()          # 1) baseline
+
+for change in client.korea.iterate_changes(cursor=saved_cursor or 0):   # 2) deltas
+    # change["type"]: "added" | "updated" | "reappeared" | "removed"
+    ...
+save_cursor(client.korea.last_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 |
+| `leasing(**params)` | `GET /api/catalog/leasing` | Lease takeovers and rentals |
+| `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 |
+| `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)` | `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()` | `GET /api/catalog/export` | Full catalog CSV (Business/Scale) |
+| `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), `export_ready`, `sort`, ... |
+| `vehicle(id)` | `GET /api/vehicle/{id}` | Price history, photos, seller, export status |
+| `inspection(id)` | `GET /api/inspection/{id}` | Accident, flood and fire checks, EV battery data |
+| `bulk_vehicles(ids)` | `POST /api/vehicle/bulk` | Up to 500 ids |
+| `changes(**params)` | `GET /api/catalog/changes` | Change feed |
+| `export_csv()` | `GET /api/catalog/export` | Full catalog CSV |
+| `enums()` / `models(make)` | `GET /api/enums`, `/api/models` | Filter values, models per make |
+
+China only? `from encarapi import ChinaCarAPI` (also available as the
+[`chinacarapi`](https://pypi.org/project/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.
+
+```python
+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)
+```
+
+## Links
+
+- Website and pricing: https://encarapi.com
+- Documentation: https://encarapi.com/documentation
+- OpenAPI reference: https://api.encarapi.com/reference
+- China data: https://chinacarapi.com
+- Node.js client: https://github.com/ThatMojo/encarapi-node
+
+EnCarAPI is an independent service and not affiliated with Encar, KB Chachacha, K Car,
+Dongchedi or Che168.
+
+## License
+
+MIT

encarapi-1.0.0/README.md

@@ -0,0 +1,131 @@
+# EnCarAPI: Python client for Korean and Chinese used car data
+
+Official **Python client** for [EnCarAPI](https://encarapi.com), 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, price history, a change feed and full catalog export.
+- **China:** Dongchedi and Che168 in English via [ChinaCarAPI](https://chinacarapi.com)
+  (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](https://encarapi.com)**.
+
+## Install
+
+```bash
+pip install encarapi
+```
+
+Requires Python 3.8+ and `requests`.
+
+## Quick start
+
+```python
+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)
+```
+
+## Keep a local copy in sync (Business / Scale)
+
+```python
+csv_text = client.korea.export_csv()          # 1) baseline
+
+for change in client.korea.iterate_changes(cursor=saved_cursor or 0):   # 2) deltas
+    # change["type"]: "added" | "updated" | "reappeared" | "removed"
+    ...
+save_cursor(client.korea.last_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 |
+| `leasing(**params)` | `GET /api/catalog/leasing` | Lease takeovers and rentals |
+| `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 |
+| `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)` | `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()` | `GET /api/catalog/export` | Full catalog CSV (Business/Scale) |
+| `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), `export_ready`, `sort`, ... |
+| `vehicle(id)` | `GET /api/vehicle/{id}` | Price history, photos, seller, export status |
+| `inspection(id)` | `GET /api/inspection/{id}` | Accident, flood and fire checks, EV battery data |
+| `bulk_vehicles(ids)` | `POST /api/vehicle/bulk` | Up to 500 ids |
+| `changes(**params)` | `GET /api/catalog/changes` | Change feed |
+| `export_csv()` | `GET /api/catalog/export` | Full catalog CSV |
+| `enums()` / `models(make)` | `GET /api/enums`, `/api/models` | Filter values, models per make |
+
+China only? `from encarapi import ChinaCarAPI` (also available as the
+[`chinacarapi`](https://pypi.org/project/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.
+
+```python
+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)
+```
+
+## Links
+
+- Website and pricing: https://encarapi.com
+- Documentation: https://encarapi.com/documentation
+- OpenAPI reference: https://api.encarapi.com/reference
+- China data: https://chinacarapi.com
+- Node.js client: https://github.com/ThatMojo/encarapi-node
+
+EnCarAPI is an independent service and not affiliated with Encar, KB Chachacha, K Car,
+Dongchedi or Che168.
+
+## License
+
+MIT

encarapi-1.0.0/encarapi/__init__.py

@@ -0,0 +1,26 @@
+"""Official Python client for EnCarAPI: Korean used car data (Encar, KB Chachacha,
+K Car) and Chinese used car data (Dongchedi, Che168) in one package.
+
+Get an API key at https://encarapi.com (a key is required).
+"""
+from .client import (
+    ChinaCarAPI,
+    ChinaCarAPIError,
+    ChinaClient,
+    EnCarAPI,
+    EnCarAPIError,
+    KoreaClient,
+    MissingApiKeyError,
+)
+
+__version__ = "1.0.0"
+__all__ = [
+    "EnCarAPI",
+    "ChinaCarAPI",
+    "KoreaClient",
+    "ChinaClient",
+    "EnCarAPIError",
+    "ChinaCarAPIError",
+    "MissingApiKeyError",
+    "__version__",
+]

encarapi-1.0.0/encarapi/client.py

@@ -0,0 +1,348 @@
+"""Official Python client for EnCarAPI: Korean (Encar, KB Chachacha, K Car) and
+Chinese (Dongchedi, Che168) used car data."""
+from __future__ import annotations
+
+import os
+from typing import Any, Dict, Iterable, Iterator, List, Optional
+from urllib.parse import quote
+
+import requests
+
+__all__ = [
+    "EnCarAPI",
+    "ChinaCarAPI",
+    "KoreaClient",
+    "ChinaClient",
+    "EnCarAPIError",
+    "ChinaCarAPIError",
+    "MissingApiKeyError",
+]
+
+KOREA_BASE_URL = "https://api.encarapi.com"
+CHINA_BASE_URL = "https://api.chinacarapi.com"
+DEFAULT_BASE_URL = KOREA_BASE_URL  # 0.x compatibility
+SIGNUP_URL = "https://encarapi.com"
+CHINA_SIGNUP_URL = "https://chinacarapi.com"
+
+
+class EnCarAPIError(Exception):
+    """Raised when the API returns an error. ``status`` and ``body`` hold the response."""
+
+    def __init__(self, message: str, status: Optional[int] = None, body: Optional[str] = None) -> None:
+        super().__init__(message)
+        self.status = status
+        self.body = body
+
+
+ChinaCarAPIError = EnCarAPIError
+
+
+class MissingApiKeyError(EnCarAPIError):
+    """Raised when no API key is provided."""
+
+
+def _enc(value: str) -> str:
+    return quote(str(value), safe="")
+
+
+class _Http:
+    """Shared requests session: x-api-key header, bool/list params, readable errors."""
+
+    def __init__(self, api_key: str, base_url: str, signup_url: str, product: str, timeout: float) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.signup_url = signup_url
+        self.product = product
+        self.timeout = timeout
+        self.session = requests.Session()
+        self.session.headers.update({"x-api-key": api_key, "Accept": "application/json"})
+
+    @staticmethod
+    def _clean(params: Optional[Dict[str, Any]]) -> Optional[Dict[str, Any]]:
+        if not params:
+            return None
+        out: Dict[str, Any] = {}
+        for k, v in params.items():
+            if v is None:
+                continue
+            if isinstance(v, bool):
+                v = "true" if v else "false"
+            elif isinstance(v, (list, tuple, set)):
+                v = ",".join(str(x) for x in v)
+            out[k] = v
+        return out
+
+    def request(self, method: str, path: str, params: Optional[Dict[str, Any]] = None, json: Any = None, text: bool = False) -> Any:
+        resp = self.session.request(
+            method, f"{self.base_url}{path}", params=self._clean(params), json=json, timeout=self.timeout,
+            headers={"Accept": "text/csv"} if text else None,
+        )
+        if resp.status_code in (401, 403):
+            raise EnCarAPIError(
+                f"{self.product} rejected the request ({resp.status_code}). Check your key or plan at "
+                f"{self.signup_url}. Body: {resp.text[:300]}",
+                resp.status_code, resp.text,
+            )
+        if not resp.ok:
+            raise EnCarAPIError(f"{self.product} error {resp.status_code}: {resp.text[:300]}", resp.status_code, resp.text)
+        if text:
+            return resp.text
+        try:
+            return resp.json()
+        except ValueError:
+            return resp.text
+
+
+class KoreaClient:
+    """Korean used car data: Encar (default), KB Chachacha (``source="kbc"``) and
+    K Car (``source="kcar"``); ``source="all"`` is the deduplicated union.
+    Endpoints marked Business/Scale return 403 with an upgrade hint on smaller plans."""
+
+    def __init__(self, api_key: str, *, base_url: str = KOREA_BASE_URL, timeout: float = 30.0) -> None:
+        self._http = _Http(api_key, base_url, SIGNUP_URL, "EnCarAPI", timeout)
+        self.last_cursor: Optional[int] = None
+
+    def _get(self, path: str, params: Optional[Dict[str, Any]] = None, text: bool = False) -> Any:
+        return self._http.request("GET", path, params, text=text)
+
+    def _post(self, path: str, json: Any = None) -> Any:
+        return self._http.request("POST", path, json=json)
+
+    # -- search ------------------------------------------------------------
+    def catalog(self, **params: Any) -> Any:
+        """Search & list vehicles with flat English filters, e.g.
+        ``catalog(manufacturer="BMW", max_mileage=50000, frame_clean=True, lang="en")``."""
+        return self._get("/api/catalog", params)
+
+    def leasing(self, **params: Any) -> Any:
+        """Lease-takeover and rental listings (same filters as catalog)."""
+        return self._get("/api/catalog/leasing", params)
+
+    def nav(self, **params: Any) -> Any:
+        """Filter facets with counts (the navigation tree)."""
+        return self._get("/api/nav", params)
+
+    def enums(self, **params: Any) -> Any:
+        """Valid values for the flat filter parameters."""
+        return self._get("/api/enums", params)
+
+    def model_search(self, search: str, **params: Any) -> Any:
+        """Model autocomplete across brands."""
+        return self._get("/api/model-search", {**params, "search": search})
+
+    def iterate_catalog(self, **params: Any) -> Iterator[Dict[str, Any]]:
+        """Yields every listing across all pages: ``for car in korea.iterate_catalog(manufacturer="Kia"): ...``"""
+        limit = params.pop("limit", 100)
+        page = params.pop("page", 1)
+        while True:
+            res = self.catalog(**params, limit=limit, page=page)
+            items = res.get("SearchResults") or []
+            yield from items
+            if len(items) < limit:
+                return
+            page += 1
+
+    # -- one vehicle ---------------------------------------------------------
+    def vehicle(self, vehicle_id: str, **params: Any) -> Any:
+        """Full vehicle detail. Ids: Encar id, ``kbc:<id>`` or ``kcar:<id>``."""
+        return self._get(f"/api/vehicle/{_enc(vehicle_id)}", params)
+
+    def inspection(self, vehicle_id: str) -> Any:
+        """Official inspection report."""
+        return self._get(f"/api/inspection/{_enc(vehicle_id)}")
+
+    def record(self, vehicle_id: str) -> Any:
+        """Insurance accident & ownership record."""
+        return self._get(f"/api/record/{_enc(vehicle_id)}")
+
+    def refresh(self, vehicle_id: str) -> Any:
+        """Request a fresh copy of one listing (daily quota per plan)."""
+        return self._post(f"/api/vehicle/{_enc(vehicle_id)}/refresh")
+
+    def price_check(self, vehicle_id: str) -> Any:
+        """Price check (beta, Scale): below / in line with / above the market."""
+        return self._get(f"/api/price-check/{_enc(vehicle_id)}")
+
+    def inspection_versions(self, vehicle_id: str) -> Any:
+        """Inspection report versions (Business/Scale)."""
+        return self._get(f"/api/inspection/{_enc(vehicle_id)}/versions")
+
+    def record_versions(self, vehicle_id: str) -> Any:
+        """Insurance record versions (Business/Scale)."""
+        return self._get(f"/api/record/{_enc(vehicle_id)}/versions")
+
+    # -- bulk & sync (Business/Scale) ---------------------------------------
+    def bulk_vehicles(self, ids: Iterable[str]) -> Any:
+        """Up to 500 vehicle details in one call."""
+        return self._post("/api/vehicle/bulk", {"ids": list(ids)})
+
+    def bulk_inspections(self, ids: Iterable[str]) -> Any:
+        """Up to 500 inspection reports in one call."""
+        return self._post("/api/inspection/bulk", {"ids": list(ids)})
+
+    def bulk_records(self, ids: Iterable[str]) -> Any:
+        """Up to 500 insurance records in one call."""
+        return self._post("/api/record/bulk", {"ids": list(ids)})
+
+    def changes(self, **params: Any) -> Any:
+        """Incremental change feed: ``cursor`` from the previous call, or ``since`` right after an export."""
+        return self._get("/api/catalog/changes", params)
+
+    def iterate_changes(self, **params: Any) -> Iterator[Dict[str, Any]]:
+        """Follows the change feed until drained and yields each change once as
+        ``{"type": "added" | "updated" | "reappeared" | "removed", **item}``.
+        Afterwards ``korea.last_cursor`` is the cursor to resume from."""
+        query = dict(params)
+        while True:
+            res = self.changes(**query)
+            for kind in ("added", "updated", "reappeared", "removed"):
+                for item in res.get(kind) or []:
+                    yield {"type": kind, **item}
+            if res.get("nextCursor") is not None:
+                self.last_cursor = res["nextCursor"]
+            if not (res.get("hasMore") or res.get("truncated")) or res.get("nextCursor") is None:
+                return
+            query = {k: v for k, v in params.items() if k != "since"}
+            query["cursor"] = res["nextCursor"]
+
+    def export_csv(self, **params: Any) -> str:
+        """Full catalog as CSV text."""
+        return self._get("/api/catalog/export", params, text=True)
+
+    # -- reference data -------------------------------------------------------
+    def makes_csv(self, **params: Any) -> str:
+        """All makes as CSV."""
+        return self._get("/api/taxonomy/makes.csv", params, text=True)
+
+    def models_csv(self, **params: Any) -> str:
+        """All models as CSV."""
+        return self._get("/api/taxonomy/models.csv", params, text=True)
+
+    def badges_csv(self, **params: Any) -> str:
+        """All badges (trims) as CSV."""
+        return self._get("/api/taxonomy/badges.csv", params, text=True)
+
+
+class ChinaClient:
+    """Chinese used car data (Dongchedi and Che168) in English. Works with a
+    ChinaCarAPI key or an EnCarAPI key that has the China add-on."""
+
+    def __init__(self, api_key: str, *, base_url: str = CHINA_BASE_URL, timeout: float = 30.0) -> None:
+        self._http = _Http(api_key, base_url, CHINA_SIGNUP_URL, "ChinaCarAPI", timeout)
+
+    def catalog(self, **params: Any) -> Any:
+        """Search listings. Filters: source, make, model, year_min/max, price_min/max (CNY),
+        mileage_max, city, fuel, has_report, export_ready, sort, page, limit, lang ('zh' = original)."""
+        return self._http.request("GET", "/api/catalog", params)
+
+    def vehicle(self, vehicle_id: str, **params: Any) -> Any:
+        """Full record: price history, photos, seller, export status, alsoListedOn."""
+        return self._http.request("GET", f"/api/vehicle/{_enc(vehicle_id)}", params)
+
+    def inspection(self, vehicle_id: str, **params: Any) -> Any:
+        """Inspection report: accident, flood and fire checks, battery data for EVs."""
+        return self._http.request("GET", f"/api/inspection/{_enc(vehicle_id)}", params)
+
+    def bulk_vehicles(self, ids: Iterable[str], **params: Any) -> Any:
+        """Up to 500 full records in one call (Business/Scale)."""
+        return self._http.request("POST", "/api/vehicle/bulk", params, json={"ids": list(ids)})
+
+    # 0.x name used by the standalone chinacarapi client
+    bulk = bulk_vehicles
+
+    def changes(self, **params: Any) -> Any:
+        """Change feed: ``since`` once, then ``cursor=nextCursor`` (Business/Scale)."""
+        return self._http.request("GET", "/api/catalog/changes", params)
+
+    def export_csv(self, **params: Any) -> str:
+        """Full catalog as CSV text (Business/Scale)."""
+        return self._http.request("GET", "/api/catalog/export", params, text=True)
+
+    def enums(self, **params: Any) -> Any:
+        """Filter values with counts: makes, fuels, cities, sources, sorts."""
+        return self._http.request("GET", "/api/enums", params)
+
+    def models(self, make: str) -> Any:
+        """Models of one make (id or English name) with counts."""
+        return self._http.request("GET", "/api/models", {"make": make})
+
+
+class EnCarAPI:
+    """One client for both markets.
+
+        from encarapi import EnCarAPI
+
+        client = EnCarAPI("YOUR_API_KEY")          # or set ENCARAPI_KEY
+        kr = client.korea.catalog(manufacturer="Hyundai", lang="en", count=True)
+        cn = client.china.catalog(make="BYD", limit=25)
+
+    An API key is **required**: https://encarapi.com (Korea) or https://chinacarapi.com (China).
+    EnCarAPI keys with the China add-on work for both. Pass ``china_key`` (or set
+    CHINACARAPI_KEY) to use a separate ChinaCarAPI key.
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        china_key: Optional[str] = None,
+        base_url: str = KOREA_BASE_URL,
+        china_base_url: str = CHINA_BASE_URL,
+        timeout: float = 30.0,
+    ) -> None:
+        api_key = api_key or os.environ.get("ENCARAPI_KEY")
+        china_key = china_key or os.environ.get("CHINACARAPI_KEY") or api_key
+        if not api_key and not china_key:
+            raise MissingApiKeyError(
+                "An API key is required. Pass it as EnCarAPI('YOUR_KEY') or set ENCARAPI_KEY "
+                f"(Korea) / CHINACARAPI_KEY (China). Get a key at {SIGNUP_URL}"
+            )
+        self._api_key = api_key
+        self._china_key = china_key
+        self._base_url = base_url
+        self._china_base_url = china_base_url
+        self._timeout = timeout
+        self._korea: Optional[KoreaClient] = None
+        self._china: Optional[ChinaClient] = None
+
+    @property
+    def korea(self) -> KoreaClient:
+        """Korean data: Encar (default), KB Chachacha (``kbc``), K Car (``kcar``)."""
+        if self._korea is None:
+            if not self._api_key:
+                raise MissingApiKeyError(f"An EnCarAPI key is required for Korean data. Get one at {SIGNUP_URL}")
+            self._korea = KoreaClient(self._api_key, base_url=self._base_url, timeout=self._timeout)
+        return self._korea
+
+    @property
+    def china(self) -> ChinaClient:
+        """Chinese data: Dongchedi and Che168."""
+        if self._china is None:
+            self._china = ChinaClient(self._china_key, base_url=self._china_base_url, timeout=self._timeout)  # type: ignore[arg-type]
+        return self._china
+
+    # 0.x shortcuts (Korean catalog)
+    def catalog(self, **params: Any) -> Any:
+        return self.korea.catalog(**params)
+
+    def nav(self, **params: Any) -> Any:
+        return self.korea.nav(**params)
+
+    def vehicle(self, vehicle_id: str, **params: Any) -> Any:
+        return self.korea.vehicle(vehicle_id, **params)
+
+
+class ChinaCarAPI(ChinaClient):
+    """China-only client (also published as the ``chinacarapi`` package).
+
+        from encarapi import ChinaCarAPI
+        client = ChinaCarAPI("YOUR_KEY")   # or set CHINACARAPI_KEY
+    """
+
+    def __init__(self, api_key: Optional[str] = None, *, base_url: str = CHINA_BASE_URL, timeout: float = 30.0) -> None:
+        api_key = api_key or os.environ.get("CHINACARAPI_KEY")
+        if not api_key:
+            raise MissingApiKeyError(
+                "A ChinaCarAPI key is required. Pass it as ChinaCarAPI('YOUR_KEY') or set CHINACARAPI_KEY. "
+                f"Get a key at {CHINA_SIGNUP_URL}"
+            )
+        super().__init__(api_key, base_url=base_url, timeout=timeout)

encarapi-1.0.0/examples/quickstart.py

@@ -0,0 +1,19 @@
+"""EnCarAPI Python quickstart. Get a key at https://encarapi.com"""
+import os
+
+from encarapi import EnCarAPI
+
+client = EnCarAPI(os.environ["ENCARAPI_KEY"])  # required
+
+# Korean catalog (Encar by default), English values, with total count
+kr = client.korea.catalog(manufacturer="Hyundai", lang="en", limit=5, count=True)
+print("Korea:", kr.get("Count"), "matches")
+
+# All three Korean marketplaces, deduplicated (plan-dependent, see encarapi.com/#pricing)
+# everything = client.korea.catalog(source="all", limit=5, count=True)
+
+# Full detail for one vehicle (Encar id, "kbc:<id>" or "kcar:<id>")
+# car = client.korea.vehicle("12345678")
+
+# Chinese listings (ChinaCarAPI key or EnCarAPI key with the China add-on)
+# cn = client.china.catalog(make="BYD", limit=5)

encarapi-1.0.0/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "encarapi"
+version = "1.0.0"
+description = "Official Python client for EnCarAPI: Korean used car data (Encar, KB Chachacha, K Car) and Chinese used car data (Dongchedi, Che168) in one REST API."
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+authors = [{ name = "EnCarAPI", email = "support@encarapi.com" }]
+keywords = [
+    "encar",
+    "encar api",
+    "encar.com",
+    "kbchacha",
+    "kb chachacha",
+    "kcar",
+    "k car",
+    "korean car api",
+    "korea car api",
+    "korean used car data",
+    "china car api",
+    "chinese used car data",
+    "che168",
+    "dongchedi",
+    "car export",
+    "vehicle data api",
+]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = ["requests>=2.20"]
+
+[project.urls]
+Homepage = "https://encarapi.com"
+Documentation = "https://encarapi.com/documentation"
+Source = "https://github.com/ThatMojo/encarapi-python"
+"China data" = "https://chinacarapi.com"
+
+[tool.hatch.build.targets.wheel]
+packages = ["encarapi"]

encarapi-1.0.0/tests/test_offline.py

@@ -0,0 +1,115 @@
+"""Offline tests: key gating, request shape and iterators via a fake session.
+Run: python -m unittest discover tests"""
+import json
+import os
+import unittest
+from unittest import mock
+
+from encarapi import ChinaCarAPI, EnCarAPI, EnCarAPIError, MissingApiKeyError
+
+
+class FakeResponse:
+    def __init__(self, status, payload):
+        self.status_code = status
+        self.ok = status < 400
+        self.text = payload if isinstance(payload, str) else json.dumps(payload)
+
+    def json(self):
+        return json.loads(self.text)
+
+
+class FakeSession:
+    def __init__(self, responses):
+        self.responses = list(responses)
+        self.calls = []
+        self.headers = {}
+
+    def request(self, method, url, params=None, json=None, timeout=None, headers=None):
+        self.calls.append({"method": method, "url": url, "params": params, "json": json, "headers": headers})
+        status, payload = self.responses.pop(0) if len(self.responses) > 1 else self.responses[0]
+        return FakeResponse(status, payload)
+
+
+def patch_session(client_http, responses):
+    fake = FakeSession(responses)
+    fake.headers.update(client_http.session.headers)
+    client_http.session = fake
+    return fake
+
+
+class OfflineTests(unittest.TestCase):
+    def setUp(self):
+        self.env = mock.patch.dict(os.environ, {}, clear=False)
+        self.env.start()
+        os.environ.pop("ENCARAPI_KEY", None)
+        os.environ.pop("CHINACARAPI_KEY", None)
+
+    def tearDown(self):
+        self.env.stop()
+
+    def test_key_required(self):
+        with self.assertRaises(MissingApiKeyError) as ctx:
+            EnCarAPI()
+        self.assertIn("encarapi.com", str(ctx.exception))
+        with self.assertRaises(MissingApiKeyError) as ctx:
+            ChinaCarAPI()
+        self.assertIn("chinacarapi.com", str(ctx.exception))
+
+    def test_korea_catalog_params(self):
+        client = EnCarAPI("kr_key", china_key="cn_key")
+        fake = patch_session(client.korea._http, [(200, {"Count": 1, "SearchResults": [{"Id": "1"}]})])
+        res = client.korea.catalog(manufacturer="BMW", frame_clean=True, options=["a", "b"], page=None)
+        self.assertEqual(res["Count"], 1)
+        call = fake.calls[-1]
+        self.assertEqual(call["url"], "https://api.encarapi.com/api/catalog")
+        self.assertEqual(call["params"], {"manufacturer": "BMW", "frame_clean": "true", "options": "a,b"})
+        self.assertEqual(fake.headers["x-api-key"], "kr_key")
+
+    def test_prefixed_id_and_bulk(self):
+        client = EnCarAPI("kr_key")
+        fake = patch_session(client.korea._http, [(200, {})])
+        client.korea.vehicle("kbc:123")
+        self.assertTrue(fake.calls[-1]["url"].endswith("/api/vehicle/kbc%3A123"))
+        client.korea.bulk_vehicles(["1", "2"])
+        self.assertEqual(fake.calls[-1]["method"], "POST")
+        self.assertEqual(fake.calls[-1]["json"], {"ids": ["1", "2"]})
+
+    def test_china_uses_china_key_and_host(self):
+        client = EnCarAPI("kr_key", china_key="cn_key")
+        fake = patch_session(client.china._http, [(200, {"total": 0, "results": []})])
+        client.china.catalog(make="BYD")
+        self.assertTrue(fake.calls[-1]["url"].startswith("https://api.chinacarapi.com/"))
+        self.assertEqual(fake.headers["x-api-key"], "cn_key")
+
+    def test_iterate_changes(self):
+        client = EnCarAPI("kr_key")
+        fake = patch_session(client.korea._http, [
+            (200, {"nextCursor": 10, "hasMore": True, "added": [{"Id": "a"}], "removed": [{"Id": "b"}]}),
+            (200, {"nextCursor": 12, "hasMore": False, "updated": [{"Id": "c"}]}),
+        ])
+        events = list(client.korea.iterate_changes(since="2026-10-01T00:00:00Z"))
+        self.assertEqual([f'{e["type"]}:{e["Id"]}' for e in events], ["added:a", "removed:b", "updated:c"])
+        self.assertEqual(fake.calls[1]["params"], {"cursor": 10})
+        self.assertEqual(client.korea.last_cursor, 12)
+
+    def test_iterate_catalog_stops_on_short_page(self):
+        client = EnCarAPI("kr_key")
+        patch_session(client.korea._http, [(200, {"SearchResults": [{"Id": "1"}]})])
+        self.assertEqual(len(list(client.korea.iterate_catalog(limit=5))), 1)
+
+    def test_403_carries_body(self):
+        client = EnCarAPI("kr_key")
+        patch_session(client.korea._http, [(403, {"error": "Upgrade to Business"})])
+        with self.assertRaises(EnCarAPIError) as ctx:
+            client.korea.changes(cursor=0)
+        self.assertEqual(ctx.exception.status, 403)
+        self.assertIn("Upgrade to Business", ctx.exception.body)
+
+    def test_legacy_shortcuts(self):
+        client = EnCarAPI("kr_key")
+        patch_session(client.korea._http, [(200, {"Count": 3, "SearchResults": []})])
+        self.assertEqual(client.catalog()["Count"], 3)
+
+
+if __name__ == "__main__":
+    unittest.main()