encarapi-com Trucks API

openapi: 3.2.0
info:
  title: encarapi Trucks 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: Trucks
  description: 'Business/Scale (and trials). Encar''s truck, bus and special-vehicle marketplace (화물·특장·버스): cargo trucks (Porter, Bongo, Mighty, Xcient ...), wing bodies, dump and construction trucks, cranes, tankers, buses, campers and more. Own endpoint with body type, tonnage and registration-use filters; the car catalog is unchanged.'
paths:
  /api/catalog/trucks:
    get:
      tags:
      - Trucks
      summary: Trucks, buses and special vehicles - Business/Scale
      description: 'Encar truck listings (refreshed twice a day). Every item: `Id`, `Manufacturer`, `Model`, `Badge`, `Form` / `FormEnglish` (body type code), `FormDetail`, `Capacity` (e.g. "1톤") / `CapacityTons`, `Use` / `UseEnglish` (`private`, `commercial`, `other`), `FuelType`, `Transmission`, `Color` (each with an English twin), `Year` (YYYYMM), `FormYear`, `Mileage` (km), `Price` (10,000 KRW), `Region`, `Photos`, `Url`, `Source` ("truck"). `?lang=en` returns English values (so do `lang=ru` and `lang=de`: trucks have no Russian or German labels). Valid filter values with counts: /api/catalog/trucks/enums. Incremental sync: /api/catalog/changes?source=truck; full file: /api/catalog/trucks/export.'
      parameters:
      - name: form
        in: query
        schema:
          type: string
        example: cargo,wing_body
        description: 'Body type, comma = OR: cargo, wing_body, bus, dump_construction, crane, tank, camper, waste_transport, live_fish, tow_transport, tractor, trailer.'
      - name: manufacturer
        in: query
        schema:
          type: string
        example: Hyundai
        description: Brand (English or Korean), comma = OR.
      - name: model
        in: query
        schema:
          type: string
        example: 포터
        description: Model, substring match on the Korean model name (e.g. 포터, 봉고, 마이티).
      - name: min_tons
        in: query
        schema:
          type: number
        example: 1
        description: Minimum payload in tons (from Capacity).
      - name: max_tons
        in: query
        schema:
          type: number
        example: 5
        description: Maximum payload in tons.
      - name: use
        in: query
        schema:
          type: string
        example: private
        description: 'Registration use: private (자가용), commercial (영업용, yellow plate), other.'
      - name: fuel
        in: query
        schema:
          type: string
        example: diesel
        description: Fuel code, comma = OR (values in /api/catalog/trucks/enums).
      - name: transmission
        in: query
        schema:
          type: string
        example: manual
        description: Transmission code, comma = OR.
      - name: color
        in: query
        schema:
          type: string
        example: white
        description: Color code, comma = OR.
      - name: min_price
        in: query
        schema:
          type: integer
        description: Minimum price in 10,000 KRW.
      - name: max_price
        in: query
        schema:
          type: integer
        description: Maximum price in 10,000 KRW.
      - name: min_year
        in: query
        schema:
          type: integer
        example: 2018
        description: From year (YYYY or YYYYMM).
      - name: max_year
        in: query
        schema:
          type: integer
        description: To year (YYYY or YYYYMM).
      - name: min_mileage
        in: query
        schema:
          type: integer
        description: Minimum mileage in km.
      - name: max_mileage
        in: query
        schema:
          type: integer
        description: Maximum mileage in km.
      - name: region
        in: query
        schema:
          type: string
        example: gyeonggi
        description: Region codes, comma = OR (see "Region and city").
      - name: sort
        in: query
        schema:
          type: string
          enum:
          - newest
          - price_asc
          - price_desc
          - mileage_asc
          - mileage_desc
          - year_desc
          - year_asc
          - id
          default: newest
        description: Sort order. `newest` (default) = most recently changed first; any change moves a listing to the top, so offset paging over a changing catalog can repeat or skip listings at page boundaries. For a complete traversal use `sort=id` (immutable listing id ascending) with `after` = the previous response's `nextAfter` until `hasMore` is false; listings added during the traversal are covered by /api/catalog/changes.
      - name: after
        in: query
        schema:
          type: string
        example: '41234567'
        description: 'Keyset cursor for `sort=id`: pass the `nextAfter` value of the previous response to get the next page (ignores page/offset). Use this for complete traversals - see `sort`.'
      - name: page
        in: query
        description: Page number (1-based).
        schema:
          type: integer
          default: 1
        example: 1
      - name: limit
        in: query
        description: Results per page (1-1000).
        schema:
          type: integer
          default: 20
        example: 25
      - name: count
        in: query
        description: Include the total match count.
        schema:
          type: boolean
        example: true
      - name: lang
        in: query
        schema:
          type: string
          enum:
          - en
          - ru
          - de
        description: lang=en returns English values; lang=ru and lang=de return English values too (no Russian or German labels for trucks).
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
        '400':
          description: Unknown filter value.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Plan does not include trucks. Upgrade to Business or Scale.
      operationId: getApiCatalogTrucks
      x-operation-id-source: derived
  /api/catalog/trucks/{id}:
    get:
      tags:
      - Trucks
      summary: One truck with detail and inspection report - Business/Scale
      description: 'Everything from the list item plus the detail page and the official inspection report (성능점검) where one exists: `Vin`, `VehicleNo` (plate number), `Displacement` (cc), `HorsePower`, `CargoBox` (`lengthMm`, `widthMm`, `heightMm`), `Axle`, all `Photos`, `Options`, `Detail` (full detail payload, seller contact data removed), `Inspection` (null when the truck has none), `Status` / `RemovedAt`, `DetailFetchedAt`. Details are collected within a few days of a listing appearing; until then the response carries `DetailNote`.'
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        example: '42504495'
        description: Truck listing id from /api/catalog/trucks.
      - name: lang
        in: query
        schema:
          type: string
          enum:
          - en
          - ru
          - de
        description: lang=en returns English values for the list fields; lang=ru and lang=de return English values too (no Russian or German labels for trucks).
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
        '403':
          description: Business or Scale only.
        '404':
          description: No truck with this id.
      operationId: getApiCatalogTrucksById
      x-operation-id-source: derived
  /api/catalog/trucks/enums:
    get:
      tags:
      - Trucks
      summary: Truck filter values with counts
      description: 'Every valid value per truck filter with live counts: `form`, `use`, `fuel`, `transmission`, `color`, `manufacturer` (each `{value, ko, count}`), `capacity_tons` and `region`.'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
        '403':
          description: Plan does not include trucks.
      operationId: getApiCatalogTrucksEnums
      x-operation-id-source: derived
  /api/catalog/trucks/export:
    get:
      tags:
      - Trucks
      summary: Full truck inventory (CSV) - Business/Scale
      description: 'All active truck listings as one CSV (refreshed every 6 hours): listing_id, manufacturer, model, badge, form, form_detail, capacity, capacity_tons, use, fuel, transmission, color, year_month, form_year, mileage_km, price_krw_10k, region, first_seen_at, last_seen_at, url, then the detail columns vin, vehicle_no, displacement_cc, horse_power, cargo_length_mm, cargo_width_mm, cargo_height_mm, axle, has_inspection (empty until a listing''s detail is collected). Keep the `X-Encarapi-Generated-At` header and continue with /api/catalog/changes?source=truck&since=. Add `compress=true` for a compressed download.'
      parameters:
      - name: compress
        in: query
        schema:
          type: boolean
        description: true = compressed download (gzip / brotli).
      responses:
        '200':
          description: CSV file
          content:
            text/csv:
              schema:
                type: string
        '403':
          description: Business or Scale only.
      operationId: getApiCatalogTrucksExport
      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).