Search Listings
curl --request GET \
--url https://scrapebadger.com/v1/gumtree/search \
--header 'X-API-Key: <x-api-key>'import requests
url = "https://scrapebadger.com/v1/gumtree/search"
headers = {"X-API-Key": "<x-api-key>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {'X-API-Key': '<x-api-key>'}};
fetch('https://scrapebadger.com/v1/gumtree/search', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://scrapebadger.com/v1/gumtree/search",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"X-API-Key: <x-api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://scrapebadger.com/v1/gumtree/search"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("X-API-Key", "<x-api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://scrapebadger.com/v1/gumtree/search")
.header("X-API-Key", "<x-api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://scrapebadger.com/v1/gumtree/search")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["X-API-Key"] = '<x-api-key>'
response = http.request(request)
puts response.read_body{
"market": "<string>",
"query": "<string>",
"category": "<string>",
"category_name": "<string>",
"category_id": {},
"location": "<string>",
"location_name": "<string>",
"distance": 123,
"sort": "<string>",
"page": 123,
"total_pages": 123,
"total_results": 123,
"result_count": 123,
"currency": "<string>",
"url": "<string>",
"category_facets": [
{}
],
"listings": [
{
"id": "<string>",
"short_id": "<string>",
"title": "<string>",
"url": "<string>",
"description": "<string>",
"price": 123,
"price_text": "<string>",
"price_frequency": "<string>",
"price_type": "<string>",
"currency": "<string>",
"location": "<string>",
"location_id": "<string>",
"postcode": "<string>",
"latitude": 123,
"longitude": 123,
"distance_text": "<string>",
"distance_miles": 123,
"category_id": {},
"category_name": "<string>",
"category_ids": [
{}
],
"image_url": "<string>",
"image_urls": [
"<string>"
],
"image_count": 123,
"posted_text": "<string>",
"posted_utc": 123,
"posted_at": "<string>",
"status": "<string>",
"seller_type": "<string>",
"seller_id": "<string>",
"seller_name": "<string>",
"account_id": "<string>",
"is_pro_seller": true,
"is_featured": true,
"is_urgent": true,
"is_bumped_up": true,
"is_standout": true,
"is_premium": true,
"has_video": true,
"supports_shipping": true,
"favourite_count": 123,
"seller_skills": [
"<string>"
],
"attributes": [
{}
]
}
]
}Search
Search Listings
Search Gumtree classified ads in the UK, Australia or South Africa by keyword, category, location and radius, price band, seller type and category-specific filters.
GET
/
v1
/
gumtree
/
search
Search Listings
curl --request GET \
--url https://scrapebadger.com/v1/gumtree/search \
--header 'X-API-Key: <x-api-key>'import requests
url = "https://scrapebadger.com/v1/gumtree/search"
headers = {"X-API-Key": "<x-api-key>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {'X-API-Key': '<x-api-key>'}};
fetch('https://scrapebadger.com/v1/gumtree/search', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://scrapebadger.com/v1/gumtree/search",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"X-API-Key: <x-api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://scrapebadger.com/v1/gumtree/search"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("X-API-Key", "<x-api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://scrapebadger.com/v1/gumtree/search")
.header("X-API-Key", "<x-api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://scrapebadger.com/v1/gumtree/search")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["X-API-Key"] = '<x-api-key>'
response = http.request(request)
puts response.read_body{
"market": "<string>",
"query": "<string>",
"category": "<string>",
"category_name": "<string>",
"category_id": {},
"location": "<string>",
"location_name": "<string>",
"distance": 123,
"sort": "<string>",
"page": 123,
"total_pages": 123,
"total_results": 123,
"result_count": 123,
"currency": "<string>",
"url": "<string>",
"category_facets": [
{}
],
"listings": [
{
"id": "<string>",
"short_id": "<string>",
"title": "<string>",
"url": "<string>",
"description": "<string>",
"price": 123,
"price_text": "<string>",
"price_frequency": "<string>",
"price_type": "<string>",
"currency": "<string>",
"location": "<string>",
"location_id": "<string>",
"postcode": "<string>",
"latitude": 123,
"longitude": 123,
"distance_text": "<string>",
"distance_miles": 123,
"category_id": {},
"category_name": "<string>",
"category_ids": [
{}
],
"image_url": "<string>",
"image_urls": [
"<string>"
],
"image_count": 123,
"posted_text": "<string>",
"posted_utc": 123,
"posted_at": "<string>",
"status": "<string>",
"seller_type": "<string>",
"seller_id": "<string>",
"seller_name": "<string>",
"account_id": "<string>",
"is_pro_seller": true,
"is_featured": true,
"is_urgent": true,
"is_bumped_up": true,
"is_standout": true,
"is_premium": true,
"has_video": true,
"supports_shipping": true,
"favourite_count": 123,
"seller_skills": [
"<string>"
],
"attributes": [
{}
]
}
]
}Search Gumtree listings across every vertical — For Sale, Motors, Property,
Jobs, Services, Pets and Community — on
A parameter a market does not support is a
Range filters (
Toyotas in Gauteng, newest first
(
A listing card from an Australian cars search (
On
gumtree.com (UK), gumtree.com.au
(Australia) or gumtree.co.za (South Africa). Returns 25 (UK) or 24 (AU)
listings per page plus any pinned featured ads, up to 50 pages, or 20 (ZA) per
page across the first 375 matches.
Credits: 5
Authorization
Query Parameters
Which Gumtree:
uk (gumtree.com, GBP), au (gumtree.com.au, AUD) or za
(gumtree.co.za, ZAR). Separate sites — category, location and listing ids
from one market mean nothing in another.uk: category slug, e.g.cars,for-sale,property-to-rent,jobs,pets,bicycles.au: numeric category id, e.g.18320(cars),18560(bicycles).za: category ref, e.g.p6dnh(Cars & Bakkies),l4dq6(Vehicles).
/categories for the same
market. An unknown id or ref is a 400.Omit to search the whole country.
uk: location slug (london,manchester), town name or full UK postcode (SW1A 1AA).au: numeric location id, e.g.3003435(Sydney Region).za: location ref, e.g.dkp8y(Gauteng),pfw8k(Cape Town).
/locations/autocomplete.
An unknown location is a 400 — the sites would otherwise silently search
the whole country.Radius around
location, greater than 0 and up to 1000: miles (uk) or
km (au, needs a location). Not supported for za.Result ordering. One of
relevance, date, price_asc, price_desc,
distance. distance needs uk, or au with a location.private or trade. trade covers dealers, letting agents and recruiters.
uk and za only — on au pass it as a filter instead (e.g.
cars.forsaleby_s:ownr).Category-specific filters as comma-separated
key:value pairs. Range filters
take min_<key>:<value> / max_<key>:<value>. Keys differ per market —
discover them, with their values, from
/search/filters for the
same market and category:uk:vehicle_make:bmw,vehicle_fuel_type:petrol,min_vehicle_mileage:10000. Repeat a key to select several values (vehicle_make:bmw,vehicle_make:audi).au:cars.carmake_s:toyota,min_cars.caryear_i:2015,priceType:NEGOTIABLE.za:make:toyota,model:hilux,fuelType:diesel,max_mileageKm:100000,min_year:2015— on Cars & Bakkies:make,model,bodyType,driveType,transmission,fuelType,colour, and the rangesyearandmileageKm. Values are case-insensitive (toyota=TOYOTA). One value per key. A key gumtree.co.za does not know is a400; a value it does not know matches nothing.
Result page,
1–50 (za: results past the 375th are not reachable; such
a page comes back empty).Response
Sub-categories of the result set with counts —
id, name, slug, count.
Feed a slug (uk) or id (au, za — a ref like p6dnh there) back in
as category to drill down.Listing cards.
Show ListingSummary
Show ListingSummary
Listing id — use it for
/listings/{listing_id}. za: the listing ref, e.g. ls26bvmcpnsqmz7l9jz.Example
curl "https://scrapebadger.com/v1/gumtree/search?category=cars" \
-H "X-API-Key: YOUR_API_KEY"
const res = await fetch(
"https://scrapebadger.com/v1/gumtree/search?" +
new URLSearchParams({ category: "cars" }),
{ headers: { "X-API-Key": process.env.SCRAPEBADGER_API_KEY } },
);
const data = await res.json();
import requests
res = requests.get(
"https://scrapebadger.com/v1/gumtree/search",
headers={"X-API-Key": "YOUR_API_KEY"},
params={"category": "cars"},
)
data = res.json()
Response
{
"market": "uk",
"query": null,
"category": "cars",
"category_name": "Cars",
"category_id": 9311,
"location": "uk",
"location_name": "United Kingdom",
"distance": null,
"sort": "relevance",
"page": 1,
"total_pages": 50,
"total_results": 139812,
"result_count": 30,
"currency": "GBP",
"listings": [
{
"id": "1802409381",
"title": "Ford, RANGER, Pick Up, 2024, Automatic, 1996 (cc)",
"url": "https://www.gumtree.com/p/ford/ford-ranger-pick-up-2024-automatic-1996-cc-/1802409381",
"description": "2024 Ford Ranger Automatic – NO VAT – Only 11,400 Miles\n\nVery clean, low-mileage example of a 2024 Ford Ranger with just 11,400 miles from new...",
"price": 29000.0,
"price_text": "£29,000.00",
"price_frequency": null,
"currency": "GBP",
"location": "Penkridge, Staffordshire",
"location_id": "11002225",
"postcode": "ST195DU",
"latitude": 52.7257,
"longitude": -2.10523,
"category_id": 10306,
"category_name": "Ford",
"category_ids": [2551, 9311, 10306],
"image_url": "https://img.gumtree.com/ePR8PyKf84wPHx7_RYmEag/c77d793ecce84e13a9_a54724b51d3e/86",
"image_count": 17,
"posted_text": "4 days ago",
"posted_utc": 1791395043.988,
"posted_at": "2026-10-07T17:44:03.988000Z",
"status": "LIVE",
"seller_type": "Private",
"seller_id": "96740710",
"is_pro_seller": false,
"is_featured": true,
"is_urgent": true,
"is_bumped_up": false,
"is_standout": false,
"favourite_count": 1,
"attributes": [
{ "key": "vehicle_make", "label": "Make", "value": "Ford", "unit": null },
{ "key": "vehicle_model", "label": "Model", "value": "RANGER", "unit": null },
{ "key": "vehicle_registration_year", "label": "Year", "value": "2024", "unit": null },
{ "key": "vehicle_mileage", "label": "Mileage", "value": "11400", "unit": "miles" },
{ "key": "vehicle_fuel_type", "label": "Fuel type", "value": "Diesel", "unit": null },
{ "key": "vehicle_engine_power", "label": "Engine Power", "value": "205", "unit": "bhp" },
{ "key": "vehicle_not_writeoff", "label": "Not written-off", "value": "true", "unit": null },
{ "key": "vehicle_previous_keepers", "label": "Previous Keepers", "value": "4", "unit": null }
]
}
],
"category_facets": [],
"url": "https://www.gumtree.com/search?search_category=cars&search_location=uk"
}
Search behaviour
UK price filters need a category. gumtree.com ignores
min_price /
max_price when category is all, so that combination is a 400 — pick a
category (for-sale, cars, bicycles …) to filter by price.Gumtree pins paid featured ads (
is_featured: true) above the chosen
sort order — up to 5 in the UK and up to 6 in Australia. Skip them if you
need a strict date or price ordering.A result set holds at most 50 pages (
za: the first 375 matches, 19
pages), whatever total_results reports. To
collect more, narrow the search — by sub-category (category_facets),
location and distance, price band, or
filters. A page past the
end comes back with no listings and is not billed.Market support
| Parameter | uk | au | za |
|---|---|---|---|
category / location | slug / slug or postcode | numeric id | ref (p6dnh / dkp8y) |
distance | miles | km (needs location) | — |
seller_type | ✓ | as a filter | ✓ |
urgent_only, with_photos | ✓ | — | — |
sort=distance | ✓ | with location | — |
| Listings per page | 25 + featured | 24 + up to 6 featured | 20 (first 375 matches) |
400, not silently ignored.
Postcode radius
Pass a full UK postcode aslocation with a distance in miles:
curl "https://scrapebadger.com/v1/gumtree/search?query=sofa&category=for-sale&location=SW1A%201AA&distance=2" \
-H "X-API-Key: YOUR_API_KEY"
Category filters
curl "https://scrapebadger.com/v1/gumtree/search?category=cars&filters=vehicle_make:bmw,vehicle_fuel_type:petrol,min_vehicle_mileage:10000" \
-H "X-API-Key: YOUR_API_KEY"
type: enum_range) take min_ / max_ + the filter key, e.g.
min_vehicle_mileage:10000,max_vehicle_mileage:50000. List every key and value
for a category with
/search/filters.
South Africa
Petrol Toyotas in Gauteng between R50,000 and R300,000, cheapest first (p6dnh = Cars & Bakkies, dkp8y = Gauteng) — 241 results on 2026-10-13:
curl "https://scrapebadger.com/v1/gumtree/search?market=za&category=p6dnh&location=dkp8y&filters=make:toyota,fuelType:petrol&min_price=50000&max_price=300000&sort=price_asc" \
-H "X-API-Key: YOUR_API_KEY"
market=za&category=p6dnh&location=dkp8y&filters=make:toyota&sort=date),
abridged:
{
"market": "za",
"category": "p6dnh",
"category_name": "Cars & Bakkies",
"category_id": "p6dnh",
"location": "dkp8y",
"location_name": "Gauteng",
"sort": "date",
"page": 1,
"total_pages": 19,
"total_results": 429,
"result_count": 20,
"currency": "ZAR",
"listings": [
{
"id": "ls26bvmcpnsqmz7l9jz",
"title": "Toyota Yaris",
"url": "https://www.gumtree.co.za/listing/ls26bvmcpnsqmz7l9jz",
"description": "2018 Toyota Yaris 1.5XS CVT Automatic 85000km FSH with Toyota (service books including all...",
"price": 190000.0,
"price_text": "R190,000",
"price_type": "ASKING_PRICE",
"currency": "ZAR",
"location": "Weltevreden Park",
"location_id": "mxm68",
"category_id": "p6dnh",
"category_ids": ["kyzkk", "l4dq6", "p6dnh"],
"image_count": 1,
"posted_at": "2026-10-13T17:34:24.365000Z",
"seller_id": "s16zcgy0ntjnvg2",
"seller_name": "Thanuj",
"attributes": [
{ "key": "mileageKm", "label": "Kilometres", "value": "85000", "unit": null },
{ "key": "transmission", "label": "Transmission", "value": "Automatic", "unit": null },
{ "key": "fuelType", "label": "Fuel Type", "value": "Petrol", "unit": null }
]
}
],
"url": "https://www.gumtree.co.za/search"
}
total_results is the full count, but gumtree.co.za only pages through the
first 375 matches: total_pages is at most 19.
Australia
Mountain bikes in the Sydney Region (18560 = Bicycles, 3003435 = Sydney
Region), within 25 km:
curl "https://scrapebadger.com/v1/gumtree/search?market=au&query=mountain%20bike&category=18560&location=3003435&distance=25" \
-H "X-API-Key: YOUR_API_KEY"
market=au&category=18320),
abridged:
{
"id": "1344981847",
"title": "2018 Holden Commodore RS ZB",
"url": "https://www.gumtree.com.au/web/listing/cars-vans-utes/1344981847",
"price": 16990.0,
"price_text": "$16,990",
"price_type": "FIXED",
"currency": "AUD",
"location": "Wanneroo Area, WA",
"category_id": 18320,
"seller_type": "Dealer used",
"is_featured": false,
"attributes": [
{ "key": "carmileageinkms", "label": null, "value": "89168 km", "unit": null },
{ "key": "cartransmission", "label": null, "value": "Auto", "unit": null }
]
}
au, sell-by and price type are filters: filters=cars.forsaleby_s:ownr
for private sellers, priceType:NEGOTIABLE for negotiable prices.
Errors
| Status | Meaning |
|---|---|
400 | Malformed filters value; an unknown category or location id; a parameter the market does not support (see the table above); a za filter key gumtree.co.za does not know, or an old numeric za id; or min_price / max_price with category=all on uk. |
422 | Invalid parameter (e.g. page above 50), or Gumtree blocked the request. Not billed. |
503 | Gumtree’s origin or transport is temporarily unavailable. Not billed. Wait for the Retry-After interval (currently 60 seconds) before retrying. |

