# Karrot / 당근 API (daangn.com) — Korea's neighbourhood second-hand marketplace, the country's biggest local classifieds: search a neighbourhood's listings by keyword, category and price, read a full listing with seller manners score and photos, and resolve Korean neighbourhood ids. Prices in Korean won. No account, no browser.

> Search the second-hand listings of one Korean neighbourhood: listing id, title, full body text, price in won, whether it is still on sale, reserved or sold, the listing's own neighbourhood, the meeting point the seller pinned, posting and bump times, and the photo. Filter by keyword, category, price range and on-sale-only; category, price and on-sale are applied by daangn itself. `region_id` is required — daangn is a neighbourhood market and the site itself has no nationwide search, so there is no way to ask the whole country at once. There is also no sort and no pagination: one call returns the one page daangn serves for that neighbourhood (266-290 rows measured, variable by region). Every answer names its own `match_scope`, so you always know whether the keyword was matched by daangn's search index or against the live neighbourhood feed, and `related_keywords` gives daangn's own Korean suggestions for the term you asked for.
> ReefAPI engine `karrot` · 4 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/karrot/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/karrot/v1/search — 3 credits
Search the second-hand listings of one Korean neighbourhood: listing id, title, full body text, price in won, whether it is still on sale, reserved or sold, the listing's own neighbourhood, the meeting point the seller pinned, posting and bump times, and the photo. Filter by keyword, category, price range and on-sale-only; category, price and on-sale are applied by daangn itself. `region_id` is required — daangn is a neighbourhood market and the site itself has no nationwide search, so there is no way to ask the whole country at once. There is also no sort and no pagination: one call returns the one page daangn serves for that neighbourhood (266-290 rows measured, variable by region). Every answer names its own `match_scope`, so you always know whether the keyword was matched by daangn's search index or against the live neighbourhood feed, and `related_keywords` gives daangn's own Korean suggestions for the term you asked for.

**Parameters:**
- `region_id` (string, required) — Karrot neighbourhood id — daangn is a neighbourhood market and the site itself requires one, so there is no nationwide search. 6035 = 서울 강남구 역삼동. Find ids with the `regions` action, or read the number at the end of an `in=` url on daangn.com.
- `query` (string, optional) — Keyword. Karrot listings are written in Korean, so a Korean keyword matches far more than a latin one (아이폰 = iPhone, 자전거 = bicycle). Every answer names where the keyword was matched in `match_scope`: `site_index` is Karrot's own search, with its own ranking; `region_feed` means Karrot's keyword index was not answering at that moment, so the live neighbourhood feed was read and the keyword matched against each listing's title and body — real listings, from a narrower pool. A multi-word query needs every word to appear on the `region_feed` path.
- `category_id` (integer, optional) — Karrot category id from the `categories` action (1 = 디지털기기 / electronics, 5 = 여성의류 / women's clothing …).
- `price_min` (integer, optional) — Lowest price in Korean won (plain won, not 만: 100000 = ₩100,000). daangn only applies a price filter when a range is given, so passing one end fills the other in for you (0 … 100000000).
- `price_max` (integer, optional) — Highest price in Korean won (plain won, not 만).
- `on_sale_only` (boolean, optional, default false) — Keep only listings that are still on sale (the site's 거래 가능만 보기 toggle) — drops reserved and sold ones.

**Returns:** results[]{listing_id, title, url, description (the seller's own body text), price (won exactly as daangn published it; null when the source does not print a plain number), currency (KRW), status (on_sale|reserved|sold|null), status_code (the source's own word), instant_buy, region_name (the LISTING's own neighbourhood — daangn ranks by distance and does not fence the searched region), category (null: the search surface publishes no category id — use `detail`), meeting_point{lat, lng} (the pin the seller set, null when there is none), created_at, bumped_at, image}, count, total_results, match_scope (site_index = daangn's own keyword search answered, its ranking | region_feed = the keyword index was not serving, so the live neighbourhood feed was read and the keyword matched against each title and body | site_filters = no keyword was asked for), site_index_served, control_total_results (how many rows that region served unfiltered-by-keyword in the SAME call — present on the region_feed path, where it is the live control that makes an empty answer trustworthy), region{region_id, name, full_name}, filters_applied, related_keywords[] (daangn's own related-search suggestions for the keyword, in Korean), filtered_empty_confirmed (true only when a live feed was read in this call and genuinely carries no match), unparsable_rows_dropped, sponsored_rail_count (paid third-party ads daangn shows beside the list; they are NOT mixed into results), currency, has_more (always false — daangn serves one page, no sort and no pagination exist at the source), next_page, keyword_index_attempts

**Example request body:**
```json
{
  "region_id": "6035"
}
```

### POST https://api.reefapi.com/karrot/v1/detail — 1 credit
One Karrot listing by id or URL: full description, price in won, sale status, category, the neighbourhood down to province / city / dong, view, favourite, chat and comment counts, posting and bump times, every photo, the public seller (nickname, profile url, photo and 매너온도 manners score), and the listings daangn recommends beside it.

**Parameters:**
- `listing_id` (string, required) — Listing id — the code at the end of a daangn listing url (www.daangn.com/kr/buy-sell/역삼동-월주차-20만원-k3kcgd4v7ump/) — or the full URL.

**Returns:** listing{listing_id, internal_id, title, url, description, price, currency, status, status_code, is_adult, category{id, name}, region{id, name, province, city, neighbourhood, country_code}, view_count, favorite_count, chat_count, comment_count (the LENGTH of daangn's comment array only — no comment text and no commenter identity is ever returned), properties[]{name, value} (the seller's own declared spec rows, e.g. 사이즈 → "L,66"; an empty list when the seller declared none), created_at, bumped_at, images[], image, seller{id, nickname, url, image, manner_score}, related_listings[]{listing_id, title, url, price, image}}

**Example request body:**
```json
{
  "listing_id": "k3kcgd4v7ump"
}
```

### POST https://api.reefapi.com/karrot/v1/regions — 1 credit
Resolve Korean neighbourhood ids for `search`. Give a known id to get its full name plus every neighbourhood daangn lists as adjacent to it; give nothing to get daangn's own popular-region list to start from. A name filter narrows either list.

**Parameters:**
- `region_id` (string, optional) — A known Karrot neighbourhood id to look up. Its own name and the neighbourhoods daangn lists as adjacent to it come back. Leave it out to get daangn's own popular-region list to start from.
- `query` (string, optional) — Keep only regions whose Korean name (or its province/city part) contains this text.

**Returns:** regions[]{region_id, name, province, city, neighbourhood, depth}, count, seed_region{region_id, name, full_name}, query

**Example request body:**
```json
{
  "region_id": "6035"
}
```

### POST https://api.reefapi.com/karrot/v1/categories — 1 credit
Karrot's own second-hand category list — every id `search`'s `category_id` accepts, with the Korean name daangn shows for it.

**Parameters:** none

**Returns:** categories[]{category_id, name}, count

## 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=karrot
- Human docs page: https://reefapi.com/docs/karrot
- Overview page: https://reefapi.com/karrot-api
- Every ReefAPI API in one file (for your AI): https://reefapi.com/llms-full.txt