# Carsome — certified used cars in Malaysia, Indonesia and Thailand

> Search Carsome's certified used-car stock in one country (my, id, th) by keyword, make, model, body type, location, gearbox, colour, price, monthly instalment, mileage and year, with ten sort orders. Returns the source's own total, facet counts and full rows with VIN, plate, every price (cash, credit, campaign, ex-VAT, monthly) and the showroom.
> ReefAPI engine `carsome` · 4 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/carsome/v1/<action>` with a JSON body.
- **Auth:** header `x-api-key: <YOUR_REEFAPI_KEY>` — create one free (1,000 credits, no card): https://reefapi.com/signup
- **Response (every call):** `{ ok: boolean, data: ..., meta: { record_count, credits, ... }, error: { code, message } }` — branch on `ok`. Failed calls are free except verified SHEIN NOT_FOUND on product/detail and price (4 credits).
- **One key + one shared credit pool** across every ReefAPI API. Per-call credits are listed on each endpoint below.
- **Use it from an AI agent (MCP):** connect `https://api.reefapi.com/mcp` (remote streamable-http). Send the key as `Authorization: Bearer <key>`, or put it in the URL (`?key=<key>`) when the client has no header field, as ChatGPT does.

## Endpoints

### POST https://api.reefapi.com/carsome/v1/search — 2 credits
Search Carsome's certified used-car stock in one country (my, id, th) by keyword, make, model, body type, location, gearbox, colour, price, monthly instalment, mileage and year, with ten sort orders. Returns the source's own total, facet counts and full rows with VIN, plate, every price (cash, credit, campaign, ex-VAT, monthly) and the showroom.

**Parameters:**
- `country` (enum, required) — Which Carsome market: `my` = Malaysia (carsome.my, MYR), `id` = Indonesia (carsome.id, IDR), `th` = Thailand (carsome.co.th, THB). [one of: my, id, th]
- `query` (string, optional) — Free-text keyword matched by Carsome's own search (make, model, variant or a car number). Measured: `myvi` cuts Malaysia from 3,647 to 495 cars.
- `make_id` (array, optional) — One or more make ids from the `makes` action (Perodua = 157 in Malaysia). Ids are per country.
- `model_id` (array, optional) — One or more model ids from the `makes` action (Myvi = 1656 in Malaysia).
- `body_type` (enum, optional) — Body type. Several may be passed comma-separated. [one of: sedan, hatchback, mpv, suv, truck, coupe, van, wagon, convertible]
- `location` (string, optional) — Location id(s) from the `filters` action: states in Malaysia (`selangor`), cities in Indonesia (`jakarta-selatan`), districts in Thailand (`bang-khae`). An unknown id returns 0 cars.
- `transmission` (enum, optional) — Gearbox. [one of: manual, automatic]
- `color` (enum, optional) — Exterior colour (pink and light_blue exist in Thailand only). [one of: black, white, gray, silver, red, blue, brown, gold, green, orange, beige, purple, bronze, other, pink, light_blue]
- `price_min` (number, optional) — Lowest price, in local currency. Carsome filters on its own headline number `price_basis`: the credit price in Indonesia, the campaign price in Malaysia, the VAT-inclusive price in Thailand.
- `price_max` (number, optional) — Highest price (same basis as `price_min`).
- `monthly_min` (number, optional) — Lowest monthly instalment, local currency.
- `monthly_max` (number, optional) — Highest monthly instalment, local currency.
- `mileage_min` (integer, optional) — Lowest odometer reading, km.
- `mileage_max` (integer, optional) — Highest odometer reading, km.
- `year_min` (integer, optional) — Oldest model year.
- `year_max` (integer, optional) — Newest model year.
- `sort` (enum, optional, default "recommended") — Order. `newest` is by listing date; price sorts use `price_basis`. [one of: recommended, newest, price_asc, price_desc, mileage_asc, mileage_desc, year_desc, year_asc, monthly_asc, monthly_desc]
- `page` (integer, optional, default 1) — Page number. A page past `last_page` returns 0 rows (the source does not repeat its last page).
- `page_size` (integer, optional, default 20) — Rows per page, 1-50.

**Returns:** `{rows[], summary{total_results, page, page_size, last_page, has_more, filters_applied, facets}}`. Each row: car_no (the id `detail` takes), url, title, make/model/variant with ids, year, mileage_km, engine_litres, transmission, fuel, color (local label) + color_en, seats, vin, license_plate, status, availability, listed_on, listing_programme (CARSOME Certified / Value / Value Plus), store {name, city, state, lat, lon}, seller {type, dealer_id, account_name}, campaigns, labels, highlights, photos_count, and the price set: currency, price_cash, price_credit, price_before_campaign, campaign_discount, credit_discount, price_basis, monthly_installment, vat_amount, price_cash_excl_vat, monthly_installment_excl_vat, loan {down_payment_rate, tenure_years, interest_rate, provider}.

**Example request body:**
```json
{
  "country": "my",
  "make_id": [
    157
  ],
  "body_type": "suv",
  "sort": "price_asc",
  "page_size": 20
}
```

### POST https://api.reefapi.com/carsome/v1/detail — 2 credits
The full record of one car by its `car_no` (or its listing URL): everything a search row has plus body type, registration date and type, road-tax / insurance / warranty expiry, booking fee, exterior and interior photo galleries, the showroom's address, phone and hours, and Carsome's inspection report with every checkpoint and its findings.

**Parameters:**
- `car_no` (string, required) — Carsome car number from a search row (`car_no`), e.g. C7KZ700. Case-insensitive. Requires `country`, unless `url` is given instead.
- `country` (enum, optional) — Market of the car: my, id or th. Required with `car_no`. [one of: my, id, th]
- `url` (string, optional) — Alternative to car_no + country: the listing URL, e.g. https://www.carsome.my/buy-car/perodua/aruz/2022-perodua-aruz-av-1.5/c7kz700.

**Returns:** One car object (all search-row fields) plus body_type, body_type_label, seat_label, registration_date, registration_type, road_tax_expiry, insurance_expiry, warranty_expiry, principal_warranty_flag, service_book_flag, spare_key_flag, sale_status, booking_fee, description, photos_exterior[], photos_interior[], spin_360_url, store {address, phone, business_hours, map_url} and inspection {summary{points, passed, issues, na, not_reported}, sections[]{name, groups[]{name, points[]{name, key, status, findings[], remark, recondition}}}}.

**Example request body:**
```json
{
  "car_no": "C7KZ700"
}
```

### POST https://api.reefapi.com/carsome/v1/makes — 1 credit
Every make Carsome has in stock in one country right now, with its models and the numeric ids that `search` takes.

**Parameters:**
- `country` (enum, required) — Which Carsome market: `my` = Malaysia (carsome.my, MYR), `id` = Indonesia (carsome.id, IDR), `th` = Thailand (carsome.co.th, THB). [one of: my, id, th]

**Returns:** `rows[]` of {make_id, name, logo, popular, models[]{model_id, name}}.

**Example request body:**
```json
{
  "country": "th"
}
```

### POST https://api.reefapi.com/carsome/v1/filters — 1 credit
The country's live filter vocabulary: location ids (states, cities or districts), body types, colours, gearboxes, sort orders and the current price, monthly, year and mileage bounds of the stock, plus running campaigns.

**Parameters:**
- `country` (enum, required) — Which Carsome market: `my` = Malaysia (carsome.my, MYR), `id` = Indonesia (carsome.id, IDR), `th` = Thailand (carsome.co.th, THB). [one of: my, id, th]

**Returns:** `{locations[]{location, label}, body_types[], colors[], transmissions[], sorts[], price_bounds, monthly_bounds, year_bounds, mileage_bounds, campaigns[]}`.

**Example request body:**
```json
{
  "country": "my"
}
```

## At scale
- **Volume:** 5M+ requests a day, measured at 60 requests a second across the fleet with no
  central bottleneck. Per-key limits are raised for high-volume accounts; volume pricing on request.
- **Missing a source:** tell us a site we do not cover and it becomes an engine. A customer asked
  for bestprice.gr on 21 Sep 2026 and it was in the catalog on 22 Sep.
- **Support:** 2 minute median time from a question in the live chat to the first answer. Setup
  help included, no support tier to buy.
- **One key, one credit pool** across every API. No per-site plans, no separate subscriptions.

## More
- Try it live, no code: https://reefapi.com/playground?engine=carsome
- Human docs page: https://reefapi.com/docs/carsome
- Overview page: https://reefapi.com/carsome-api
- Every ReefAPI API in one file (for your AI): https://reefapi.com/llms-full.txt