encarapi-com Taxonomy API

openapi: 3.2.0
info:
  title: encarapi Taxonomy API
  version: 1.3.0
  description: 'Real-time Korean used-car data from the full Encar inventory, served as clean JSON. Filter the whole catalog with simple **English** query parameters (or the advanced `q` query syntax). Add `lang=en` to receive every value in English. Discover all valid filter values at `/api/enums`. ## SDKs & AI agents


    - Node.js: `npm install encarapi`

    - Python: `pip install encarapi`

    - AI agents (Claude, ChatGPT, Cursor, VS Code): add the MCP server `https://mcp.encarapi.com/mcp` and sign in with your API key in the browser. Claude Code: `claude mcp add --transport http encarapi https://mcp.encarapi.com/mcp`


    ## Catalog scope


    `/api/catalog` covers standard-sale listings only (Encar''s "일반" sell type). Lease-takeover ("리스") and rental ("렌트") listings are a separate endpoint, `/api/catalog/leasing` - they price by monthly payment rather than a purchase price, so mixing them into `/api/catalog` would distort `Price`. For a brand with e.g. 16,000 total Encar listings, expect roughly 5-10% to be lease/rental. ## Caching


    Recommended cache times:

    - `/api/enums`, the taxonomy CSVs and `/api/nav`: 24 hours (makes, models, badges and filter values barely change)

    - `/api/catalog` listings: 4 to 6 hours

    - `/api/vehicle/{id}` details: 24 hours (a listing''s specs change rarely; it only drops out when sold)


    Serve listings from your own database and refresh periodically rather than calling live on every user click. Fair use applies. ## Live queries vs. a local copy


    There are two supported ways to use this API - pick the one that matches what you are building:


    - **Starter - live queries.** Call `/api/catalog` with the filters your users actually search for and cache each response for the times above. This is the default, and it is what the per-key daily catalog-row cap protects (re-pulling the entire catalog on this plan will eventually hit it). - **Business / Scale - a local copy.** Pull `/api/catalog/export` once for a full baseline (does not count against the daily cap), then keep it current with `/api/catalog/changes?since=` instead of re-dumping the whole catalog. Scale additionally has no daily catalog-row cap. Both are 403 on Starter. ## Duplicate listings


    Korean dealers commonly list the same physical car twice (sometimes more) under different listing IDs for extra visibility. We detect these and flag the extra copies with `IsDuplicate: true` and `DuplicateOf: ` on the catalog item; the original listing is left unflagged. Duplicates are flagged, not removed, so you can decide how to treat them. `/api/catalog` and `/api/catalog/leasing` accept `exclude_duplicates=true` to filter them out server-side. `/api/catalog/changes` stays a complete, lossless event log (no filtering there) - it still carries `IsDuplicate`/`DuplicateOf` on every item, so filter client-side if you keep a local copy of the catalog. ## Data sources - Encar, KB Chachacha and K Car


    The API serves listings from three Korean platforms:


    | Source | Platform | Live listings | Depth |

    |---|---|---|---|

    | `encar` | Encar (encar.com) | 190,000+ | full detail, inspection and insurance reports (default) |

    | `kbc` | KB Chachacha (kbchachacha.com) | 110,000+ | catalog plus public history block |

    | `kcar` | K Car (kcar.com, direct-sale channel) | 5,000+ | full detail incl. VIN and accident history |


    **Plans.** Encar is part of every plan. KB Chachacha and K Car are included in Business and Scale and in the 5-day trial, and are an add-on for Starter. A key without them gets 403 with a hint on `source=kbc`, `kcar` or `all`. **Trial.** The trial includes 100,000 catalog rows and 2,000 detail lookups in total, with at most 1,000 detail lookups per day. Catalog rows are counted over the whole trial across `/api/catalog`, `/api/catalog/leasing` and the items of `/api/catalog/changes`, with at most 100 items per request; detail lookups are `/api/vehicle/{id}`, `/api/inspection/{id}` and `/api/record/{id}` together - the daily budget resets at 00:00 UTC, the totals do not.'
  contact:
    name: encarapi
    url: https://encarapi.com
servers:
- url: https://api.encarapi.com
  description: Production
security:
- ApiKeyHeader: []
- ApiKeyQuery: []
tags:
- name: Taxonomy
  description: Downloadable make/model/badge lists (CSV). Fetch once, cache for a day, and drive your dropdowns from these - no offline mapping, no per-click facet calls.
paths:
  /api/taxonomy/makes.csv:
    get:
      tags:
      - Taxonomy
      summary: All makes (CSV)
      description: 'Every make with active-listing counts as a CSV download (columns: make, make_ko, count). Fetch once, cache for a day, drive your make dropdown from this - no offline mapping. Accepts ?source= (default encar) - pass source=all for a cross-platform list; cached per source. With lang=ru a `make_ru` column follows (brand names stay Latin), with lang=de a `make_de` column.'
      parameters:
      - name: source
        in: query
        schema:
          type: string
          default: encar
        example: all
        description: 'Data source(s): `encar` (default), `kcar`, `kbc`, a comma-separated list (`encar,kbc`), or `all`. Omitted = Encar only, byte-identical to pre-1.1.0 responses. When set, each item carries a `Source` field (plus `Url`, `Transmission`, `Color`, `Options`, `SeatCount` on K Car / KB Chachacha items). Filtering on a field a source does not provide excludes that source''s vehicles (see "Data sources" above).'
      - name: lang
        in: query
        schema:
          type: string
          enum:
          - ru
          - de
        description: ru = an extra `make_ru` column with the Russian name after the last column; de = an extra `make_de` column with the German name. All other columns unchanged.
      responses:
        '200':
          description: CSV file
          content:
            text/csv:
              schema:
                type: string
      operationId: getApiTaxonomyMakesCsv
      x-operation-id-source: derived
  /api/taxonomy/models.csv:
    get:
      tags:
      - Taxonomy
      summary: All models (CSV)
      description: 'Every make + model with counts (columns: make, model, model_ko, count). Cache and drive the model dropdown client-side. Accepts ?source= (default encar); cached per source. With lang=ru a `model_ru` column follows, with lang=de a `model_de` column.'
      parameters:
      - name: source
        in: query
        schema:
          type: string
          default: encar
        example: all
        description: 'Data source(s): `encar` (default), `kcar`, `kbc`, a comma-separated list (`encar,kbc`), or `all`. Omitted = Encar only, byte-identical to pre-1.1.0 responses. When set, each item carries a `Source` field (plus `Url`, `Transmission`, `Color`, `Options`, `SeatCount` on K Car / KB Chachacha items). Filtering on a field a source does not provide excludes that source''s vehicles (see "Data sources" above).'
      - name: lang
        in: query
        schema:
          type: string
          enum:
          - ru
          - de
        description: ru = an extra `model_ru` column with the Russian name after the last column; de = an extra `model_de` column with the German name. All other columns unchanged.
      responses:
        '200':
          description: CSV file
          content:
            text/csv:
              schema:
                type: string
      operationId: getApiTaxonomyModelsCsv
      x-operation-id-source: derived
  /api/taxonomy/badges.csv:
    get:
      tags:
      - Taxonomy
      summary: All badges (CSV)
      description: 'Every make + model + badge with counts (columns: make, model, badge, badge_ko, count). The badge level carries the body-style split (e.g. Coupe vs Sedan vs Cabriolet) - filter on it directly instead of parsing the title string. Accepts ?source= (default encar); cached per source. With lang=ru a `badge_ru` column follows, with lang=de a `badge_de` column.'
      parameters:
      - name: source
        in: query
        schema:
          type: string
          default: encar
        example: all
        description: 'Data source(s): `encar` (default), `kcar`, `kbc`, a comma-separated list (`encar,kbc`), or `all`. Omitted = Encar only, byte-identical to pre-1.1.0 responses. When set, each item carries a `Source` field (plus `Url`, `Transmission`, `Color`, `Options`, `SeatCount` on K Car / KB Chachacha items). Filtering on a field a source does not provide excludes that source''s vehicles (see "Data sources" above).'
      - name: lang
        in: query
        schema:
          type: string
          enum:
          - ru
          - de
        description: ru = an extra `badge_ru` column with the Russian name after the last column; de = an extra `badge_de` column with the German name. All other columns unchanged.
      responses:
        '200':
          description: CSV file
          content:
            text/csv:
              schema:
                type: string
      operationId: getApiTaxonomyBadgesCsv
      x-operation-id-source: derived
  /api/taxonomy/option-packages:
    get:
      tags:
      - Taxonomy
      summary: Option code reference (paid plans)
      description: 'Names for Encar option codes: `standard` (equipment codes) and `packages` (optional packages / `options.choice` codes, which differ by model, trim and year; Korean name and surcharge in 10,000 KRW). Encar detail responses already carry the decoded names for their own car in `optionsDecoded`. With `?lang=ru`, every `standard` entry also carries `nameRu` (`?lang=de`: `nameDe`). Paid plans only, for use within your own application.'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Not available on trials.
      operationId: getApiTaxonomyOptionPackages
      x-operation-id-source: derived
components:
  responses:
    Unauthorized:
      description: Missing or invalid API key.
  securitySchemes:
    ApiKeyHeader:
      type: apiKey
      in: header
      name: x-api-key
      description: Your API key.
    ApiKeyQuery:
      type: apiKey
      in: query
      name: api_key
      description: Your API key (alternative to the header).