# Jmty (ジモティー) API scraper — search Japan's largest general classifieds board across all eleven of its ad spaces: second-hand goods for sale AND for free, used cars, rental and for-sale property, full-time and part-time jobs, classes, pet rehoming, local services, community help, events and member recruitment. Filter by keyword, the three-level category tree, the three-level location tree (prefecture → city/ward → train station), a yen price band, giveaway-only and online-payment-only. Full ad detail returns the whole description, every photo, the per-category attribute block the source publishes for that kind of ad, coordinates, and the poster's public profile with their good/normal/bad review counts, verification badges and other live ads. A price of 0 yen is a real giveaway, not a missing value, and the groups that print no money at all return null instead of a fake price. No account, logged-out public pages only.

> Search one of jmty's eleven ad spaces. `group` is required — it picks the marketplace, and every other filter narrows inside it: keyword, prefecture, category slug, numeric genre id, city/ward id, train-station id, a yen price band, giveaways only, online-payment only. Returns the source's own total (`total_results`) and its own printed window, 50 ads per page, up to its own page-1000 ceiling. Promoted ads the source injects above the window come back in a separate `promoted[]` array, and the staffing-agency tiles it injects from a partner site every eighth row are dropped and counted in `dropped_partner_tiles` — they are not jmty ads and their 'price' is an hourly wage.
> ReefAPI engine `jmty` · 5 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/jmty/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/jmty/v1/search — 3 credits
Search one of jmty's eleven ad spaces. `group` is required — it picks the marketplace, and every other filter narrows inside it: keyword, prefecture, category slug, numeric genre id, city/ward id, train-station id, a yen price band, giveaways only, online-payment only. Returns the source's own total (`total_results`) and its own printed window, 50 ads per page, up to its own page-1000 ceiling. Promoted ads the source injects above the window come back in a separate `promoted[]` array, and the staffing-agency tiles it injects from a partner site every eighth row are dropped and counted in `dropped_partner_tiles` — they are not jmty ads and their 'price' is an hourly wage.

**Parameters:**
- `group` (enum, required) — Which of jmty's eleven ad spaces to search. They are separate marketplaces with their own categories and their own meaning for the headline line: `sale` prints an item price where 0 yen means the item is being given away, `est` prints MONTHLY RENT, `job`/`rec` print a salary or wage, and `eve`, `les`, `pet`, `ser`, `com` print no money at all. [one of: sale, car, est, eve, job, les, pet, rec, ser, coop, com]
- `keyword` (string, optional) — Free-text keyword, matched against the ad title and body. Japanese or Latin script both work. Measured: /all/sale 32 059 946 → keyword=iPhone 156 223.
- `prefecture` (string, optional, default "all") — Romanised prefecture slug (`tokyo`, `osaka`, `hokkaido`, …) or `all` for the whole country. The 47 slugs are returned by the `locations` action. Measured: /all/sale 32 059 946 ads → /tokyo/sale 5 837 989.
- `category` (string, optional) — Category slug inside the group, e.g. `fur` (furniture) or `mob` (phones) in `sale`. Slugs and their Japanese names come from the `categories` action. Required if you send `city_id` or `station_id` — the source answers 404 for a city filter on a bare group path.
- `genre_id` (integer, optional) — Numeric genre id — the third taxonomy level, from the `categories` action (e.g. 1245 = chairs inside `sale`/`fur`). Measured: sale/fur 1 702 508 ads → genre 1245 491 337.
- `city_id` (integer, optional) — Numeric city/ward id from the `locations` action (e.g. 276 = Adachi-ku). Needs `category` too. Measured: /tokyo/sale-fur 1 702 508 → city 276 52 986. Cannot be combined with `station_id` — the source's URL carries only one.
- `city_slug` (string, optional) — Optional romanised city name that goes into the source's own URL next to `city_id`. The source ignores its content (a-276-adachi and a-276-zzz both return 52 986 rows) but the segment must exist, so the engine supplies a placeholder when you leave this out.
- `station_id` (integer, optional) — Numeric train-station id, the finest location level. Needs `category` too and cannot be combined with `city_id`. Measured: /tokyo/sale-fur 1 702 508 → station 2200115 2 418.
- `price_min` (integer, optional) — Lowest price in whole yen. Only the six groups that publish money react to it. Measured: /all/sale 32 059 946 → min=1000&max=2000 5 561 372; keyword=iPhone 156 223 → +min=50000 13 966.
- `price_max` (integer, optional) — Highest price in whole yen. Only the six groups that publish money react to it. Measured: /all/sale 32 059 946 → min=1000&max=2000 5 561 372; keyword=iPhone 156 223 → +min=50000 13 966.
- `free_only` (boolean, optional) — `true` returns only giveaways — the source's own max=0 band, 6 909 490 of the 32 059 946 ads in `sale` as measured on 2026-10-02. `false` returns only priced ads (25 150 456). The two add up to the unfiltered total exactly, which is why a 0 price here is a real free ad and never a missing price.
- `online_payment` (boolean, optional) — Restrict to ads that accept the site's online payment / shipping flow. Measured: /tokyo/sale 5 837 989 → true 386 312.
- `page` (integer, optional, default 1) — 1-based page, 50 ads per page. The source's own last page is 1000 and page 1001 is a real 404, so at most 50,000 ads are reachable per filter set however large the total is — narrow with prefecture, category or keyword to reach the rest.

**Returns:** total_results (the source's own figure), source_window (its printed '1-50 of N' line), page, page_size (50), page_count, page_ceiling (1000), reachable_rows (50 000), returned, promoted_count, dropped_partner_tiles, has_more, category_group(+_name), prefecture, category, genre_id, keyword, filters, source_url, and listings[] / promoted[] with listing_id, url, title, headline (the source's own printed line, whatever it means in that group), price_jpy, price_display, price_kind (free | fixed | not_priced), price_basis (item | monthly_rent | hourly_wage | daily_wage | monthly_wage | annual_wage | reward), prefecture(+_name), city_name, station_name, category, genre_id, genre_name, description_excerpt, created_label, updated_label, favorite_count, image_thumbnail, keyword_tags[], promoted and highlighted.

**Example request body:**
```json
{
  "group": "sale",
  "max_results": 20
}
```

### POST https://api.reefapi.com/jmty/v1/listing — 2 credits
Full detail of one ad. Send `url` (what `search` returns) or `listing_id` together with `group` and `category` — an ad key alone cannot be resolved because the source's ad path carries the group. Returns the complete description, every photo, the attribute block the source publishes for that kind of ad (mileage/model year/frame number for a car, rent/layout/floor/age for a flat, pay/company/working hours for a job, sex/age/vaccination for a pet), coordinates, view and inquiry counts, and the poster's public profile. An ad that has been closed or deleted is an ANSWER, not an error: it comes back with `status` set to closed or deleted. An unknown key returns NOT_FOUND.

**Parameters:**
- `url` (string, optional) — A full jmty ad address, exactly as `search` returns it in `url` (`https://jmty.jp/chiba/sale-toy/article-19xjcc`). The simplest way to reach one ad, and the one that always resolves.
- `listing_id` (string, optional) — The ad key from a jmty URL (`19xjcc`, or `job_wg_9367564` for a partner-fed job ad). On its own it cannot be resolved: the source's ad path also needs the category group and a category, so send `group` + `category` with it, or send `url` instead.
- `group` (enum, optional) — Which of jmty's eleven ad spaces to search. They are separate marketplaces with their own categories and their own meaning for the headline line: `sale` prints an item price where 0 yen means the item is being given away, `est` prints MONTHLY RENT, `job`/`rec` print a salary or wage, and `eve`, `les`, `pet`, `ser`, `com` print no money at all. [one of: sale, car, est, eve, job, les, pet, rec, ser, coop, com]
- `category` (string, optional) — Category slug inside the group, e.g. `fur` (furniture) or `mob` (phones) in `sale`. Slugs and their Japanese names come from the `categories` action. Required if you send `city_id` or `station_id` — the source answers 404 for a city filter on a bare group path.

**Returns:** listing_id, internal_id, url, title, description, category_group(+_name), category(+_name), genre_id, genre_name, genre_parent_name, prefecture(+_name), city_id, city_name, station_name, area_name, latitude, longitude, created_at, updated_at, favorite_count, inquiry_count, comment_count, phone (as the source publishes it, usually null), is_business_poster, promoted, highlighted, partner_listing, status (open | closed | deleted), status_message, headline, price_jpy, price_display, price_kind, price_basis, attributes[] (the source's own per-category fields), images[], image_thumbnails[], image_count, breadcrumbs[], source_surface, seller{} (seller_id, name, profile_url, sex, listings_count, profile_text, profile_image, reviews_good/normal/bad, rating, sms_verified, id_verified, documents_verified, is_business, antique_dealer_licensed, real_estate_licensed, recent_reviews[]) and seller_other_listings[] with its count.

**Example request body:**
```json
{
  "url": "https://jmty.jp/chiba/sale-toy/article-19xjcc"
}
```

### POST https://api.reefapi.com/jmty/v1/seller — 2 credits
One poster's public profile page: nickname, which verification badges they hold, their good/normal/bad review counts, when they registered, the area they live in, their stated occupation, and the ads of theirs the page lists. Takes the `seller.seller_id` that `listing` returns. The site publishes no separate seller-listing feed, so `listings[]` here is what that one page shows, not the poster's whole history — `listings_sampled` says how many that was.

**Parameters:**
- `seller_id` (string, required) — The poster's profile id, as `listing` returns it in `seller.seller_id` (a 24-character hex id).

**Returns:** seller_id, name, profile_url, sex, registered_at, residence, occupation, certifications, id_verified, has_antique_dealer_badge, reviews_good/normal/bad, listings_sampled and listings[] with listing_id, url and title.

**Example request body:**
```json
{
  "seller_id": "5d54cbe3cf263722da5706a9"
}
```

### POST https://api.reefapi.com/jmty/v1/categories — 2 credits
The live category tree for one ad space, read from the source's own search form: category slugs with their Japanese names, and under each one the numeric genre ids `search` accepts. Also returns the table of all eleven ad spaces with a flag saying whether that space publishes money at all — which is the one thing you need before reading a `headline`.

**Parameters:**
- `group` (enum, required) — Which of jmty's eleven ad spaces to search. They are separate marketplaces with their own categories and their own meaning for the headline line: `sale` prints an item price where 0 yen means the item is being given away, `est` prints MONTHLY RENT, `job`/`rec` print a salary or wage, and `eve`, `les`, `pet`, `ser`, `com` print no money at all. [one of: sale, car, est, eve, job, les, pet, rec, ser, coop, com]

**Returns:** category_group, category_group_name, category_group_label, category_count, genre_count, categories[] (category, name, genres[] with genre_id and name) and groups[] (category_group, name, label, publishes_price).

**Example request body:**
```json
{
  "group": "sale"
}
```

### POST https://api.reefapi.com/jmty/v1/locations — 2 credits
The live location tree: all 47 prefectures with their romanised slug and the numeric city/ward ids underneath them, as the source's own search form publishes them. These are the values `search` takes for `prefecture` and `city_id`.

**Parameters:** none

**Returns:** prefecture_count, city_count and prefectures[] with prefecture (slug), name, city_count and cities[] (city_id, name).

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