encar-api-client 0.1.0__py3-none-any.whl

encar_api/__init__.py

@@ -0,0 +1,72 @@
+"""Encar API client for Python: South Korean used-car listings from Encar as JSON.
+
+A thin layer over the apiauto.space client (``apiauto``) with the market preset::
+
+    import encar_api
+
+    with encar_api.Client() as client:  # the key comes from APIAUTO_KEY
+        for car in client.cars(brand="Hyundai", year_min=2020, limit=20)["items"]:
+            print(car["id"], car["title"], car["price"]["amount"])
+
+From the apiauto.space team. Not affiliated with Encar or SK Encar.
+"""
+
+from apiauto import (
+    ApiautoError,
+    APIConnectionError,
+    AuthenticationError,
+    BadRequestError,
+    Car,
+    CarFilters,
+    CarsPage,
+    Change,
+    ChangesPage,
+    ChangeType,
+    Market,
+    NotFoundError,
+    PermissionDeniedError,
+    Price,
+    QuotaExceededError,
+    RateLimitError,
+    ReferenceItem,
+    ServerError,
+    ServiceUnavailableError,
+    Usage,
+)
+
+from ._client import MARKET, SHARED_MARKET, SOURCE, AsyncClient, Client, car_id
+from ._version import __version__
+from .types import EncarRaw, FxQuote, raw
+
+__all__ = [
+    "MARKET",
+    "SHARED_MARKET",
+    "SOURCE",
+    "APIConnectionError",
+    "ApiautoError",
+    "AsyncClient",
+    "AuthenticationError",
+    "BadRequestError",
+    "Car",
+    "CarFilters",
+    "CarsPage",
+    "Change",
+    "ChangeType",
+    "ChangesPage",
+    "Client",
+    "EncarRaw",
+    "FxQuote",
+    "Market",
+    "NotFoundError",
+    "PermissionDeniedError",
+    "Price",
+    "QuotaExceededError",
+    "RateLimitError",
+    "ReferenceItem",
+    "ServerError",
+    "ServiceUnavailableError",
+    "Usage",
+    "__version__",
+    "car_id",
+    "raw",
+]

encar_api/_client.py

@@ -0,0 +1,285 @@
+"""Encar clients: the apiauto clients with the market preset to ``kr``."""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator, Iterator, Sequence
+from datetime import datetime
+from decimal import Decimal
+from types import TracebackType
+from typing import TYPE_CHECKING, Any, Literal
+
+import apiauto
+from apiauto import (
+    Car,
+    CarsPage,
+    Change,
+    ChangesPage,
+    ChangeType,
+    Dictionaries,
+    Market,
+    ReferenceItem,
+    Usage,
+)
+
+if TYPE_CHECKING:
+    import httpx
+    from apiauto import CarFilters
+    from typing_extensions import Self, Unpack
+
+MARKET: Literal["kr"] = "kr"
+"""The apiauto.space market of Encar."""
+SOURCE: Literal["encar"] = "encar"
+"""The ``source`` of every record this package returns."""
+SHARED_MARKET = False
+"""``True`` when the market also holds another source and records are filtered on the client."""
+
+
+def car_id(listing: str | int) -> str:
+    """The full record id for a Encar listing number: ``42793038`` -> ``encar:42793038``.
+
+    An id that already has the ``encar:`` prefix is returned as is; another
+    source's prefix raises ``ValueError``.
+    """
+    text = str(listing).strip()
+    if not text:
+        raise ValueError("listing must not be empty")
+    prefix, sep, number = text.partition(":")
+    if not sep:
+        return f"{SOURCE}:{text}"
+    if prefix != SOURCE or not number:
+        raise ValueError(f"not a Encar id: {text!r}")
+    return text
+
+
+def _ours(car: Car) -> bool:
+    return car.get("source") == SOURCE
+
+
+def _our_change(change: Change) -> bool:
+    return change["car_id"].startswith(SOURCE + ":")
+
+
+def _core_options(base_url: str | None) -> dict[str, Any]:
+    return {} if base_url is None else {"base_url": base_url}
+
+
+def _own_market(markets: list[Market]) -> Market:
+    for market in markets:
+        if market["market"] == MARKET:
+            return market
+    raise apiauto.ApiautoError(f"the API did not list the {MARKET} market")
+
+
+class Client:
+    """Encar client of the apiauto.space API, synchronous.
+
+    Args:
+        api_key: Your key; defaults to the ``APIAUTO_KEY`` environment variable.
+        base_url: The API root; ``https://api.apiauto.space/v1`` when omitted.
+        timeout: Seconds to wait for a response.
+        max_retries: Retries after 429, 5xx or a network error.
+        http_client: Your own ``httpx.Client``; the client does not close it.
+
+    Use it as a context manager or call :meth:`close`::
+
+        with encar_api.Client() as client:
+            page = client.cars(brand="Hyundai", limit=20)
+
+    The general client is available as :attr:`core` for anything this one does not wrap.
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str | None = None,
+        timeout: float = 30.0,
+        max_retries: int = 2,
+        http_client: httpx.Client | None = None,
+    ) -> None:
+        self.core = apiauto.Client(
+            api_key,
+            timeout=timeout,
+            max_retries=max_retries,
+            http_client=http_client,
+            **_core_options(base_url),
+        )
+
+    def close(self) -> None:
+        """Close the HTTP connections (unless the ``http_client`` was yours)."""
+        self.core.close()
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        self.close()
+
+    def cars(self, **filters: Unpack[CarFilters]) -> CarsPage:
+        """One page of Encar cars: ``GET /cars?market=kr``.
+
+        Takes the filters of :meth:`apiauto.Client.cars`: ``brand``, ``model``, ``year_min``,
+        ``year_max``, ``price_min``, ``price_max`` (in KRW), ``mileage_max``, ``sort``,
+        ``limit``, ``cursor`` and more. Every car returned counts against the quota.
+        """
+        page = self.core.cars(MARKET, **filters)
+        return page
+
+    def iter_cars(self, *, max_items: int | None = None, **filters: Unpack[CarFilters]) -> Iterator[Car]:
+        """Every Encar car matching the filters, following ``next_cursor``.
+
+        Args:
+            max_items: Stop after this many cars.
+            **filters: The filters of :meth:`cars`; ``limit`` sets the page size.
+        """
+        yield from self.core.iter_cars(MARKET, max_items=max_items, **filters)
+
+    def car(self, listing: str | int) -> Car:
+        """One car by listing number (``42793038``) or record id (``encar:42793038``).
+
+        Cars taken off sale stay available for 14 days with ``is_active=False``.
+        """
+        return self.core.car(car_id(listing))
+
+    def changes(
+        self,
+        since: datetime | str,
+        *,
+        type: ChangeType | Sequence[ChangeType] | None = None,  # noqa: A002
+        min_pct: float | Decimal | None = None,
+        limit: int | None = None,
+        cursor: str | None = None,
+    ) -> ChangesPage:
+        """One page of the change feed: new cars, cars taken off sale and price changes since a moment."""
+        page = self.core.changes(MARKET, since, type=type, min_pct=min_pct, limit=limit, cursor=cursor)
+        return page
+
+    def iter_changes(
+        self,
+        since: datetime | str,
+        *,
+        type: ChangeType | Sequence[ChangeType] | None = None,  # noqa: A002
+        min_pct: float | Decimal | None = None,
+        limit: int | None = None,
+        max_items: int | None = None,
+    ) -> Iterator[Change]:
+        """Every event of the change feed since a moment, following ``next_cursor``."""
+        yield from self.core.iter_changes(
+            MARKET, since, type=type, min_pct=min_pct, limit=limit, max_items=max_items
+        )
+
+    def brands(self) -> list[ReferenceItem]:
+        """Makes of the kr market with car counts, most frequent first. Free."""
+        return self.core.brands(MARKET)
+
+    def models(self, brand: str) -> list[ReferenceItem]:
+        """Models of a make with car counts. Free."""
+        return self.core.models(MARKET, brand)
+
+    def dictionaries(self) -> Dictionaries:
+        """Canonical values of ``fuel``, ``transmission``, ``body_type`` and more. Free."""
+        return self.core.dictionaries()
+
+    def status(self) -> Market:
+        """The kr market: plan access, data age and the number of active cars. Free."""
+        return _own_market(self.core.markets())
+
+    def usage(self) -> Usage:
+        """The plan, its term and how much of the quota is spent. Free."""
+        return self.core.usage()
+
+
+class AsyncClient:
+    """Encar client of the apiauto.space API for asyncio; the methods of :class:`Client`.
+
+    ::
+
+        async with encar_api.AsyncClient() as client:
+            page = await client.cars(brand="Hyundai", limit=20)
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str | None = None,
+        timeout: float = 30.0,
+        max_retries: int = 2,
+        http_client: httpx.AsyncClient | None = None,
+    ) -> None:
+        self.core = apiauto.AsyncClient(
+            api_key,
+            timeout=timeout,
+            max_retries=max_retries,
+            http_client=http_client,
+            **_core_options(base_url),
+        )
+
+    async def close(self) -> None:
+        """Close the HTTP connections (unless the ``http_client`` was yours)."""
+        await self.core.close()
+
+    async def __aenter__(self) -> Self:
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        await self.close()
+
+    async def cars(self, **filters: Unpack[CarFilters]) -> CarsPage:
+        """One page of Encar cars; see :meth:`Client.cars`."""
+        page = await self.core.cars(MARKET, **filters)
+        return page
+
+    async def iter_cars(
+        self, *, max_items: int | None = None, **filters: Unpack[CarFilters]
+    ) -> AsyncIterator[Car]:
+        """Every Encar car matching the filters; see :meth:`Client.iter_cars`."""
+        async for car in self.core.iter_cars(MARKET, max_items=max_items, **filters):
+            yield car
+
+    async def car(self, listing: str | int) -> Car:
+        """One car by listing number or record id; see :meth:`Client.car`."""
+        return await self.core.car(car_id(listing))
+
+    async def changes(
+        self,
+        since: datetime | str,
+        *,
+        type: ChangeType | Sequence[ChangeType] | None = None,  # noqa: A002
+        min_pct: float | Decimal | None = None,
+        limit: int | None = None,
+        cursor: str | None = None,
+    ) -> ChangesPage:
+        """One page of the change feed; see :meth:`Client.changes`."""
+        page = await self.core.changes(MARKET, since, type=type, min_pct=min_pct, limit=limit, cursor=cursor)
+        return page
+
+    async def brands(self) -> list[ReferenceItem]:
+        """Makes of the kr market with car counts. Free."""
+        return await self.core.brands(MARKET)
+
+    async def models(self, brand: str) -> list[ReferenceItem]:
+        """Models of a make with car counts. Free."""
+        return await self.core.models(MARKET, brand)
+
+    async def dictionaries(self) -> Dictionaries:
+        """Canonical values of ``fuel``, ``transmission``, ``body_type`` and more. Free."""
+        return await self.core.dictionaries()
+
+    async def status(self) -> Market:
+        """The kr market: plan access, data age and the number of active cars. Free."""
+        return _own_market(await self.core.markets())
+
+    async def usage(self) -> Usage:
+        """The plan, its term and how much of the quota is spent. Free."""
+        return await self.core.usage()

encar_api/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

encar_api/types.py

@@ -0,0 +1,55 @@
+"""Types of the Encar-only fields of a record.
+
+Every record has the same common keys in every market (see :class:`apiauto.Car`);
+the fields only Encar has are in ``car["raw"]``. :func:`raw` returns them typed::
+
+    from encar_api import raw
+
+    extra = raw(car)
+    print(extra.get("source_values"))
+"""
+
+from __future__ import annotations
+
+from typing import TypedDict, cast
+
+from apiauto import Car
+
+__all__ = ["EncarRaw", "FxQuote", "raw"]
+
+
+class FxQuote(TypedDict):
+    """The ECB daily rate behind ``price_usd``."""
+
+    currency: str
+    usd_per_unit: str
+    """Decimal string: US dollars for one unit of ``currency``."""
+    date: str
+    source: str
+
+
+class EncarRaw(TypedDict, total=False):
+    """Encar-only fields of a record (``car["raw"]``). Keys can be missing; read them with ``.get``."""
+
+    badge: str | None
+    """Encar's badge (trim) in Korean, as the listing shows it."""
+    badge_detail: str | None
+    office_city: str | None
+    """The dealer's province in Korean, for example ``경기``."""
+    sell_type: str | None
+    """``normal``, ``lease`` or ``rental``: lease and rental listings show a monthly payment, not a price."""
+    has_vin: bool
+    form_year: str | None
+    """The model-year code, ``YYYYMM``."""
+    body_class: str | None
+    condition: list[str]
+    trust: list[str]
+    service_mark: list[str]
+    source_values: dict[str, str | None]
+    """Encar's own Korean spellings of make, model, trim, fuel and region."""
+    fx: FxQuote | None
+
+
+def raw(car: Car) -> EncarRaw:
+    """The Encar-only fields of a record, typed as :class:`EncarRaw`."""
+    return cast(EncarRaw, car.get("raw") or {})

encar_api_client-0.1.0.dist-info/METADATA

@@ -0,0 +1,168 @@
+Metadata-Version: 2.5
+Name: encar-api-client
+Version: 0.1.0
+Summary: Encar API client for Python: South Korean used-car listings from Encar as JSON, from the apiauto.space team
+Project-URL: Homepage, https://apiauto.space/en/encar-api/
+Project-URL: Documentation, https://apiauto.space/en/docs/
+Project-URL: Repository, https://github.com/apiauto-space/encar-api
+Project-URL: Issues, https://github.com/apiauto-space/encar-api/issues
+Project-URL: Changelog, https://github.com/apiauto-space/encar-api/blob/main/python/CHANGELOG.md
+Project-URL: Get a demo key, https://t.me/apiautospace_bot?start=demo
+Author: apiauto.space
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api client,car listings,encar,encar api,encar.com,korea used cars,korean cars,used cars,vehicle data
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: apiauto-space<0.2,>=0.1.1
+Description-Content-Type: text/markdown
+
+# encar-api-client — Encar API client for Python
+
+[![PyPI version](https://img.shields.io/pypi/v/encar-api-client.svg)](https://pypi.org/project/encar-api-client/)
+[![Python versions](https://img.shields.io/pypi/pyversions/encar-api-client.svg)](https://pypi.org/project/encar-api-client/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/apiauto-space/encar-api/blob/main/LICENSE)
+
+`encar-api-client` gives you South Korean used-car listings from Encar as clean JSON through the [apiauto.space](https://apiauto.space/en/encar-api/)
+REST API, without writing or maintaining a scraper. Search by make, model, year, price and mileage, page
+through the whole catalog, fetch one listing by its number and follow a feed of new cars, cars taken off sale
+and price changes.
+
+It is a thin layer over the general [`apiauto-space`](https://pypi.org/project/apiauto-space/) client with
+the market preset to `kr`, plus types for the Encar-only fields. It comes from the apiauto.space team;
+the project is not affiliated with Encar or SK Encar.
+
+- Sync `Client` and `AsyncClient`, retries on 429 and 5xx, one exception class per API error
+- `car("42793038")` takes the Encar listing number as well as the record id
+- `EncarRaw` types for the Encar-only fields in `car["raw"]`
+- Python 3.10+, `py.typed`, checked with `mypy --strict`
+
+## Install
+
+```bash
+pip install encar-api-client
+```
+
+The module you import is `encar_api`.
+
+## Get a key
+
+Open the Telegram bot [@apiautospace_bot](https://t.me/apiautospace_bot?start=demo) and take a free demo
+key: one day, 100 data requests, up to 20 cars per request. Paid plans are on the
+[pricing page](https://apiauto.space/en/#pricing).
+
+Save the key in the `APIAUTO_KEY` environment variable — the client reads it from there:
+
+```bash
+export APIAUTO_KEY="your-key"
+```
+
+Keep the key on your server: the API does not accept browser requests.
+
+## Quick start
+
+```python
+import encar_api
+
+with encar_api.Client() as client:  # reads APIAUTO_KEY
+    page = client.cars(brand="Hyundai", year_min=2020, limit=20)
+    for car in page["items"]:
+        print(car["id"], car["title"], car["price"]["amount"], car["price"]["currency"])
+
+    one = client.car("42793038")  # a listing number or "encar:42793038"
+    print(one["listing_url"], one["photos"][:1])
+```
+
+A record looks like this (shortened; real values from the catalog):
+
+```json
+{
+  "id": "encar:42793038",
+  "market": "kr",
+  "source": "encar",
+  "source_id": "42793038",
+  "title": "2021 BMW 1 Series (F40) 118d M Sport",
+  "brand": "BMW",
+  "model": "1 Series (F40)",
+  "year": 2021,
+  "mileage_km": 122866,
+  "fuel": "diesel",
+  "transmission": null,
+  "body_type": null,
+  "price": {
+    "amount": "17990000.00",
+    "currency": "KRW"
+  },
+  "price_usd": "13265.53",
+  "location": {
+    "country": "KR",
+    "region": "Gyeonggi",
+    "city": null
+  },
+  "listing_url": "https://fem.encar.com/cars/detail/42793038",
+  "is_active": true,
+  "first_seen_at": "2026-09-23T11:36:05.145090Z",
+  "photos": [
+    "https://api.apiauto.space/img/encar:42793038/1.jpg?exp=...&sig=..."
+  ],
+  "raw": {
+    "badge": "118d M 스포츠",
+    "sell_type": "normal",
+    "office_city": "경기",
+    "form_year": "202110"
+  }
+}
+```
+
+Every record has the same keys as in the other apiauto.space markets; a value the source does not provide is
+`None`. Prices are decimal strings in KRW, `price_usd` is converted at the ECB daily rate.
+
+## Methods
+
+| Method | What it does | Quota |
+|---|---|---|
+| `cars(**filters)` | One page of Encar cars: `brand`, `model`, `year_min`, `year_max`, `price_min`, `price_max`, `mileage_max`, `fuel`, `body_type`, `sort`, `limit`, `cursor` | Cars returned |
+| `iter_cars(max_items=None, **filters)` | Every matching car, page after page | Cars returned |
+| `car(listing)` | One car by listing number or id, including cars taken off sale in the last 14 days | 1 record |
+| `changes(since, type=None)` / `iter_changes(...)` | Feed of `added`, `disappeared`, `price_drop`, `price_up` events | Events returned |
+| `brands()` / `models(brand)` | Makes and models with car counts | Free |
+| `status()` | Plan access, data age and the number of active cars of the market | Free |
+| `usage()` | Your plan, its term and the quota spent | Free |
+
+The general client is at `client.core` for anything else. Errors are the `apiauto` exceptions, re-exported
+here: `QuotaExceededError`, `RateLimitError`, `NotFoundError`, `AuthenticationError` and the rest.
+
+## Encar-only fields
+
+```python
+from encar_api import raw
+
+extra = raw(car)  # typed as EncarRaw
+print(extra.get("source_values"))
+```
+
+`EncarRaw` lists the keys with comments; every key is optional, so read them with `.get`.
+
+## Links
+
+- [Encar API on apiauto.space](https://apiauto.space/en/encar-api/) and the [API documentation](https://apiauto.space/en/docs/)
+- [`apiauto-space`](https://pypi.org/project/apiauto-space/): the general client for all markets
+- Clients for the other sources: [`che168-api`](https://pypi.org/project/che168-api/), [`copart-api`](https://pypi.org/project/copart-api/), [`iaai-api`](https://pypi.org/project/iaai-api/)
+- [Examples in curl, Python, JavaScript and PHP](https://github.com/apiauto-space/encar-api-examples)
+- The JavaScript version of this client: [`encar-api-client` on npm](https://www.npmjs.com/package/encar-api-client)
+
+## License
+
+MIT. Encar is a trademark of its owner; it is named here only to say which listings the client returns.

encar_api_client-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+encar_api/__init__.py,sha256=tyI37lquTRYnHrAWk1rkhwDJ_aj9jE_Wwp9wV0dhicg,1601
+encar_api/_client.py,sha256=WWCZPlWwv9n3yL0Dpr32Qb2R6oLe7kO1q6PqfZOLs1k,9683
+encar_api/_version.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+encar_api/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+encar_api/types.py,sha256=6eP78oKJFzLlBTaq-eozDNkAZF005uIvyHi01ASd0us,1643
+encar_api_client-0.1.0.dist-info/METADATA,sha256=LKnreEOfmNdrUkZbhm9UR00hqTRpqnqEH-CZHDDBKjA,6996
+encar_api_client-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+encar_api_client-0.1.0.dist-info/licenses/LICENSE,sha256=Y2nBbdQFY450rUAs9rX-L1yEwSx3HF9qivxUwxCu_kI,1070
+encar_api_client-0.1.0.dist-info/RECORD,,

encar_api_client-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

encar_api_client-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 apiauto.space
+
+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.