encarapi-com Equipment API

openapi: 3.2.0
info:
  title: encarapi Equipment 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: Equipment
  description: 'Business/Scale (and trials). Used excavators from 굴삭기나라 (direct-nara.co.kr), Korea''s dedicated construction-equipment marketplace: crawler and wheeled excavators, with maker, model, year, operating hours, weight class, region and price. Not an Encar source - Encar does not list construction machinery. Export-control rules for construction machinery (e.g. Korea''s restrictions on exports to Russia, including via third countries) are the buyer''s and exporter''s responsibility.'
paths:
  /api/catalog/equipment:
    get:
      tags:
      - Equipment
      summary: Used excavators (construction equipment) - Business/Scale
      description: 'Excavator listings from 굴삭기나라 (refreshed twice a day). Items: `Id`, `Title` (seller''s free text), `Maker` / `MakerEnglish`, `Model`, `Year`, `Month`, `Hours` (operating hours, about half of the listings), `SubType` (`crawler`, `wheel`), `WeightClass` / `WeightClassLabel`, `Region`, `City`, `RegionRaw`, `Price` (10,000 KRW) / `PriceKRW` (null when the price is on request), `DealType` (`sell`, `buy` = wanted ad, `rent`), `NumberRegistered`, `Sold`, `ListedDate`, `Views`, `Description` (phone numbers removed), `Photos` (links to the source), `Url`, `Source` ("equipment"). No seller names or phone numbers. By default only offers (`deal_type=sell`). Valid values: /api/catalog/equipment/enums. Sync: /api/catalog/changes?source=equipment; full file: /api/catalog/equipment/export.'
      parameters:
      - name: maker
        in: query
        schema:
          type: string
        example: Doosan (Develon)
        description: Maker (English or Korean), comma = OR.
      - name: model
        in: query
        schema:
          type: string
        example: DX55
        description: Substring of model or title.
      - name: sub_type
        in: query
        schema:
          type: string
        example: crawler
        description: crawler or wheel, comma = OR.
      - name: weight_class
        in: query
        schema:
          type: string
        example: EXC_CR_LE_6_5
        description: Weight class code(s), see /api/catalog/equipment/enums (e.g. EXC_CR_LE_6_5 = 02 class 5-6 t crawler, EXC_TIRE_LE_17 = 06W 12-16 t wheeled).
      - name: min_year
        in: query
        schema:
          type: integer
        example: 2015
      - name: max_year
        in: query
        schema:
          type: integer
      - name: max_hours
        in: query
        schema:
          type: integer
        example: 5000
        description: Maximum operating hours (listings without hours drop out).
      - name: min_hours
        in: query
        schema:
          type: integer
      - 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: has_price
        in: query
        schema:
          type: boolean
        description: true = only listings with a price.
      - name: deal_type
        in: query
        schema:
          type: string
          default: sell
        description: sell (default), buy (wanted ads), rent, a comma list, or all.
      - name: region
        in: query
        schema:
          type: string
        example: gyeonggi
        description: Region codes, comma = OR.
      - name: sort
        in: query
        schema:
          type: string
          enum:
          - newest
          - price_asc
          - price_desc
          - hours_asc
          - year_desc
          - year_asc
          - id
          default: newest
        description: Sort order; `id` with `after` for complete traversals.
      - 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
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
        '400':
          description: Unknown filter value.
        '403':
          description: Plan does not include equipment. Upgrade to Business or Scale.
      operationId: getApiCatalogEquipment
      x-operation-id-source: derived
  /api/catalog/equipment/enums:
    get:
      tags:
      - Equipment
      summary: Equipment filter values with counts
      description: '`maker`, `sub_type`, `weight_class` (with label), `deal_type` and `region`, each with live counts.'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
      operationId: getApiCatalogEquipmentEnums
      x-operation-id-source: derived
  /api/catalog/equipment/export:
    get:
      tags:
      - Equipment
      summary: Full equipment inventory (CSV) - Business/Scale
      description: 'All active listings as one CSV (refreshed every 6 hours): listing_id, category, title, maker, model, year, month, hours, sub_type, weight_class, weight_class_label, region, city, region_raw, price_krw, deal_type, number_registered, sold, listed_date, photo_count, first_seen_at, last_seen_at, url. Continue with /api/catalog/changes?source=equipment&since=.'
      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: getApiCatalogEquipmentExport
      x-operation-id-source: derived
components:
  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).