> **For coding agents and LLMs:** This is one Social Fetch marketing page (markdown export). For API orientation start with [`/llms.txt`](https://www.socialfetch.dev/llms.txt); for auth and crawl rules use [`/agents.txt`](https://www.socialfetch.dev/agents.txt); for every operation use [`/llms-endpoints.txt`](https://www.socialfetch.dev/llms-endpoints.txt).

## This page

- **On-site (HTML):** <https://www.socialfetch.dev/platforms/gumtree>
- **Markdown (.mdx) URL:** <https://www.socialfetch.dev/platforms/gumtree.mdx>

---

# Gumtree API. Listings, sellers and search.

Search UK classifieds the way the site does, read any public listing with its photos and attributes, look up the seller behind it, and walk the category and location trees. JSON in, JSON out.

- UK classifieds
- Listings and sellers
- Category filters

Social Fetch exposes eleven routes under `/v1/gumtree` for Gumtree UK. `GET /v1/gumtree/search` takes a `query`, a `category` slug such as `cars` or `bicycles`, a `location` (a place slug such as `london`, a postcode district such as `M1`, or a full postcode), a `distance` in miles, `minPrice`, `maxPrice` and `sort`, and returns up to about 33 listings a page with `totalResults`, related searches and match counts per category. Follow `page.nextCursor` for the next page, up to the 50 pages the site serves.

`GET /v1/gumtree/listings/{listingId}` returns one listing with its full `description`, `price`, `images`, `videoUrls`, every attribute (condition, brand, mileage, bedrooms and so on), the town, area and postcode district, its category path, the `seller` (name, private or trade, rating, posting since) and any reviews it shows. `.../similar` returns the similar listings the page shows. The listing id is the number at the end of a listing URL, and the full URL is accepted too.

`GET /v1/gumtree/sellers/{sellerId}` returns a seller's profile, rating breakdown, reviews and feedback tags, and `.../listings` pages through their live listings. Discovery routes cover search suggestions, trending searches by area, the category tree, the filters of a category, location autocomplete and the location tree. Every response uses the `{ data, meta }` envelope; lookups set `data.lookupStatus` to `found` or `not_found`.

## What you can get

- Search with keyword, category, place, radius, price range and five sort orders, with stable paging that never repeats a listing.
- Full listings: description, price, photos, video, every attribute, location to the postcode district, category path and seller.
- Seller profiles with rating breakdown, reviews, feedback tags, listing counts by category and live listings.
- Similar listings for any listing, as the listing page shows them.
- Search suggestions as the search box offers them, and the searches trending across the UK or in one area.
- Category and location trees, location autocomplete for places and postcodes, and the filters, sort orders and radius options of any category.

## Gumtree endpoints

| Endpoint | Request | Credits | Docs |
| --- | --- | --- | --- |
| Search listings | GET /v1/gumtree/search | 1 credit Failed requests are free Found, empty and not-found answers are all charged | [docs](https://www.socialfetch.dev/docs/api/v1/gumtree/search/get) |
| Listing | GET /v1/gumtree/listings/{listingId} | 1 credit Failed requests are free Found, empty and not-found answers are all charged | [docs](https://www.socialfetch.dev/docs/api/v1/gumtree/listings/listingid/get) |
| Similar listings | GET /v1/gumtree/listings/{listingId}/similar | 1 credit Failed requests are free Found, empty and not-found answers are all charged | [docs](https://www.socialfetch.dev/docs/api/v1/gumtree/listings/listingid/similar/get) |
| Seller | GET /v1/gumtree/sellers/{sellerId} | 1 credit Failed requests are free Found, empty and not-found answers are all charged | [docs](https://www.socialfetch.dev/docs/api/v1/gumtree/sellers/sellerid/get) |
| Seller listings | GET /v1/gumtree/sellers/{sellerId}/listings | 1 credit Failed requests are free Found, empty and not-found answers are all charged | [docs](https://www.socialfetch.dev/docs/api/v1/gumtree/sellers/sellerid/listings/get) |
| Search suggestions | GET /v1/gumtree/search/suggestions | 1 credit Failed requests are free Found, empty and not-found answers are all charged | [docs](https://www.socialfetch.dev/docs/api/v1/gumtree/search/suggestions/get) |
| Trending searches | GET /v1/gumtree/trending | 1 credit Failed requests are free Found, empty and not-found answers are all charged | [docs](https://www.socialfetch.dev/docs/api/v1/gumtree/trending/get) |
| Categories | GET /v1/gumtree/categories | 1 credit Failed requests are free Found, empty and not-found answers are all charged | [docs](https://www.socialfetch.dev/docs/api/v1/gumtree/categories/get) |
| Category filters | GET /v1/gumtree/filters | 1 credit Failed requests are free Found, empty and not-found answers are all charged | [docs](https://www.socialfetch.dev/docs/api/v1/gumtree/filters/get) |
| Search locations | GET /v1/gumtree/locations | 1 credit Failed requests are free Found, empty and not-found answers are all charged | [docs](https://www.socialfetch.dev/docs/api/v1/gumtree/locations/get) |
| Location areas | GET /v1/gumtree/locations/children | 1 credit Failed requests are free Found, empty and not-found answers are all charged | [docs](https://www.socialfetch.dev/docs/api/v1/gumtree/locations/children/get) |

## How to start

1. **Create an API key.** Sign up at Social Fetch and copy a key (`sfk_…`). New accounts get 100 free credits, enough to try search, a listing and a seller.
2. **Search or look up.** `GET /v1/gumtree/search?query=road%20bike&location=london&distance=10` returns a page of listings. Take a listing's `id` to `GET /v1/gumtree/listings/{listingId}` and its `seller.sellerId` to `GET /v1/gumtree/sellers/{sellerId}`. Send `x-api-key` on every request.
3. **Branch and page.** Check `data.lookupStatus` before you store a row, follow `page.nextCursor` with the same filters, and bill from `meta.creditsCharged`.

## Pricing

Every Gumtree route costs 1 credit per completed request, found, empty or not found. Each page of search results or seller listings is its own request. Failed requests are free. Credits never expire on pay-as-you-go packs, and `meta.creditsCharged` on every response is the billing source of truth.

## Compared with the official API

Gumtree has no public API for listings or sellers. Social Fetch gives you one JSON shape under `/v1/gumtree`: typed prices in pounds, ISO timestamps, attributes as key, label, value and unit, `not_found` for expired or removed listings, and cursors that keep paging stable. Personal contact details stay out: no phone numbers or emails, and locations go no finer than the postcode district.

## FAQ

### Is there a Gumtree API for listings and search?

Yes. Social Fetch has eleven Gumtree UK routes under /v1/gumtree: search, a listing, similar listings, a seller, a seller's listings, search suggestions, trending searches, categories, category filters, location search and location areas. Authenticate with your Social Fetch API key in x-api-key.

### How do I find a listing id?

It is the number at the end of a listing URL, for example 1495075116 in gumtree.com/p/plumbing-services/.../1495075116. Pass the number or the whole URL. Search results carry the id of every listing they return.

### Which search filters are supported?

query, category (a slug such as cars, bicycles or property-to-rent), location (a place slug, a postcode district or a full postcode), distance in miles (1, 3, 5, 10, 15, 30, 50, 75, 100 or 1000), minPrice and maxPrice in whole pounds, and sort (relevance, date, price_lowest_first, price_highest_first or distance). GET /v1/gumtree/filters lists every filter a category offers with its options.

### Does the API return seller phone numbers or emails?

No. Gumtree keeps phone numbers behind a login and relays messages without showing an email, so neither is returned. A listing carries the seller name it shows (a first name or a business name), whether the seller is private or trade, their rating, how long they have posted and the seller id for the seller routes.

### How precise is a listing's location?

Listings return the town and area the page shows, for example Keith, Moray, the postcode district such as AB55, and a Gumtree location id. Map coordinates are returned only when the seller lets the listing show a map. A full postcode is never returned.

### How does paging work?

Search and seller listings return page.hasMore and page.nextCursor. Pass the cursor back with the same filters to get the next page; a cursor used with other filters is refused with a 400. Search serves up to 50 pages, and a listing shown on one page is never repeated on the next.

### What happens when a listing has expired?

The response is HTTP 200 with data.lookupStatus not_found and data.listing null. Gumtree answers the same way for a listing that never existed, so the two cannot be told apart. The lookup is still charged, like any completed request.

### How is Gumtree data billed?

Each completed request costs 1 credit, found, empty or not found, and each page of a list is a separate request. Check meta.creditsCharged on every response. Failed requests are free.

### Can I use the Gumtree routes from MCP or Ask?

Yes. Every Gumtree route is a typed MCP tool and is reachable through Ask (POST /v1/ask) in plain English. Use the typed routes for production jobs, where the parameters and response shape are fixed.

## Related

- [Gumtree Search API](https://www.socialfetch.dev/platforms/gumtree/search): Listings by keyword, category, place, radius and price (`GET /v1/gumtree/search`).
- [Gumtree Listing API](https://www.socialfetch.dev/platforms/gumtree/listings-listingid): One listing with photos, attributes and seller (`GET /v1/gumtree/listings/{listingId}`).
- [Gumtree Seller API](https://www.socialfetch.dev/platforms/gumtree/sellers-sellerid): A seller's profile, rating and reviews (`GET /v1/gumtree/sellers/{sellerId}`).
- [Gumtree Filters API](https://www.socialfetch.dev/platforms/gumtree/filters): The filters, sort orders and radius options of a category (`GET /v1/gumtree/filters`).
- [Gumtree Trending Searches API](https://www.socialfetch.dev/platforms/gumtree/trending): What people search for across the UK or in one area (`GET /v1/gumtree/trending`).
- [Gumtree Locations API](https://www.socialfetch.dev/platforms/gumtree/locations): Places and postcodes with their ids and centres (`GET /v1/gumtree/locations`).
