# Gumtree UK Classifieds API scraper — search listings & adverts, browse the full category tree, read category/location filters, get rich advert detail, similar listings and keyword suggestions from gumtree.com (cars, property, jobs, for-sale, pets and more). Bare datacenter, no account, seller PII redacted.

> Search Gumtree UK adverts and return paginated listing cards — title, price, location, posted date, images, seller type and attributes. Filter by keyword, area/postcode, category slug, price range, search radius and seller type; sort by newest, price or distance. Fetches up to 50 pages (~1,500 adverts) per call with automatic de-duplication, or pass a full Gumtree search URL.
> ReefAPI engine `gumtree` · 6 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/gumtree/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 or blocked calls are free.
- **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, `Authorization: Bearer <key>`) and your assistant can call these actions directly.

## Endpoints

### POST /gumtree/v1/search — 1 credit
Search Gumtree UK adverts and return paginated listing cards — title, price, location, posted date, images, seller type and attributes. Filter by keyword, area/postcode, category slug, price range, search radius and seller type; sort by newest, price or distance. Fetches up to 50 pages (~1,500 adverts) per call with automatic de-duplication, or pass a full Gumtree search URL.

**Parameters:**
- `query` (string, optional) — Keyword to search for. Give at least one of query / location / category / url.
- `location` (string, optional) — Town / area / postcode to search in (e.g. london, manchester, SW1A). Resolve area names with the filters action.
- `category` (string, optional) — Category slug from the categories action (e.g. cars-vans-motorbikes, for-sale, flats-houses, jobs, pets, business-services, community, or a sub-slug like for-sale/baby-kids-stuff). Optional.
- `url` (string, optional) — A full Gumtree search URL to run as-is (advanced — overrides the other search params).
- `sort` (enum, optional, default "date") — Result ordering. [one of: date, price_lowest_first, price_highest_first, distance, relevance]
- `min_price` (number, optional) — Minimum price filter (in GBP).
- `max_price` (number, optional) — Maximum price filter (in GBP).
- `distance` (integer, optional) — Search radius in miles around `location` (1, 3, 5, 10, 15, 25, 50, 75…). Needs location.
- `seller_type` (enum, optional) — Restrict to trade or private sellers. [one of: trade, private]
- `featured_only` (boolean, optional, default false) — Only return featured (promoted) adverts.
- `with_photos` (boolean, optional, default false) — Only return adverts that include at least one photo.
- `max_pages` (integer, optional, default 1) — How many result pages to fetch + de-dup in one call (1–50, ~30 ads/page; larger values are capped at 50).
- `market` (enum, optional, default "uk") — Which Gumtree marketplace. UK (gumtree.com) is live. Australia (gumtree.com.au) is geo-fenced to Australian connections and not yet available. [one of: uk, au]
- `include_pii` (boolean, optional, default false) — Keep phone/email contact details that sellers paste into free text (redacted by default; the public display name is always kept).

**Returns:** items[]{id, title, price, price_amount, price_currency, url, location, image, images[], posted_date, seller_type, attributes[]} + count + result_count + total_pages + pages_fetched + stop_reason (~30 ads/page; Gumtree serves at most ~50 pages ≈ 1,500 ads per query — narrow with location/category/price to harvest deeper)

**Example request body:**
```json
{
  "market": "uk",
  "category": "cars-vans-motorbikes",
  "location": "london",
  "max_pages": 1
}
```

### POST /gumtree/v1/listing_detail — 1 credit
Full advert detail by listing `url` OR numeric `id`: title, full description, price, all photos, every attribute (mileage, year, bedrooms, condition…), map coordinates, location/postcode, category breadcrumbs and the public seller profile (display name, rating, total adverts, ads per category, member-since).

**Parameters:**
- `url` (string, optional) — Full advert URL from a search result. Provide url OR id.
- `id` (string, optional) — Advert ID — the digits at the end of an advert URL. Alternative to url.
- `market` (enum, optional, default "uk") — Which Gumtree marketplace. UK (gumtree.com) is live. Australia (gumtree.com.au) is geo-fenced to Australian connections and not yet available. [one of: uk, au]
- `include_pii` (boolean, optional, default false) — Keep phone/email contact details that sellers paste into free text (redacted by default; the public display name is always kept).

**Returns:** listing{id, title, price, price_amount, price_currency, url, description, location, area, postcode, latitude, longitude, attributes[], images[], category, breadcrumbs[], seller{name, rating, total_ads, …}, similar_count}

### POST /gumtree/v1/similar — 1 credit
Related / similar adverts for a given listing (by `url` or `id`) — Gumtree's own 'you might also like' recommendations as clean listing cards.

**Parameters:**
- `url` (string, optional) — Full advert URL. Provide url OR id.
- `id` (string, optional) — Advert ID. Alternative to url.
- `market` (enum, optional, default "uk") — Which Gumtree marketplace. UK (gumtree.com) is live. Australia (gumtree.com.au) is geo-fenced to Australian connections and not yet available. [one of: uk, au]
- `include_pii` (boolean, optional, default false) — Keep phone/email contact details that sellers paste into free text (redacted by default; the public display name is always kept).

**Returns:** items[] (related listing cards), source_id, count

### POST /gumtree/v1/categories — 1 credit
Gumtree's full browse tree — the top-level categories (Motors, For Sale, Property, Jobs, Pets, Services, Community) and their sub-categories with slugs and paths. Use the slugs as the `category` parameter of search / filters.

**Parameters:**
- `market` (enum, optional, default "uk") — Which Gumtree marketplace. UK (gumtree.com) is live. Australia (gumtree.com.au) is geo-fenced to Australian connections and not yet available. [one of: uk, au]

**Returns:** categories[]{name, slug, path, subcategories[]{name, slug, path}}, count

**Example request body:**
```json
{
  "market": "uk"
}
```

### POST /gumtree/v1/filters — 1 credit
Available filters & facets for a category and/or location: selectable sub-categories (with live advert counts), area / postcode facets (with counts), sort options, search-radius options and the price filter. Lets a caller discover valid category slugs, location values and result sizes before searching.

**Parameters:**
- `category` (string, optional) — Category slug from the categories action (e.g. cars-vans-motorbikes, for-sale, flats-houses, jobs, pets, business-services, community, or a sub-slug like for-sale/baby-kids-stuff). Optional.
- `location` (string, optional) — Town / area / postcode to search in (e.g. london, manchester, SW1A). Resolve area names with the filters action.
- `query` (string, optional) — Keyword to search for. Give at least one of query / location / category / url.
- `market` (enum, optional, default "uk") — Which Gumtree marketplace. UK (gumtree.com) is live. Australia (gumtree.com.au) is geo-fenced to Australian connections and not yet available. [one of: uk, au]

**Returns:** subcategories[]{label, slug, count}, locations[]{label, value, count}, sort_options[], distance_options[], price_filter, result_count

**Example request body:**
```json
{
  "market": "uk",
  "category": "cars-vans-motorbikes",
  "location": "london"
}
```

### POST /gumtree/v1/suggestions — 1 credit
Keyword suggestions & spelling corrections for a search term — Gumtree's 'did you mean' / related-keyword surface, useful for query expansion and autocomplete-style discovery.

**Parameters:**
- `query` (string, optional) — Keyword to search for. Give at least one of query / location / category / url.
- `location` (string, optional) — Town / area / postcode to search in (e.g. london, manchester, SW1A). Resolve area names with the filters action.
- `category` (string, optional) — Category slug from the categories action (e.g. cars-vans-motorbikes, for-sale, flats-houses, jobs, pets, business-services, community, or a sub-slug like for-sale/baby-kids-stuff). Optional.
- `market` (enum, optional, default "uk") — Which Gumtree marketplace. UK (gumtree.com) is live. Australia (gumtree.com.au) is geo-fenced to Australian connections and not yet available. [one of: uk, au]

**Returns:** suggestions[]{name, category_slug}, keyword_correction, query

**Example request body:**
```json
{
  "market": "uk",
  "query": "sofa"
}
```

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