/gumtree/listings/search

POST /api/gumtree/listings/search

Price: 20 credits

Search Gumtree ads across every section (For Sale, Motors, Property, Jobs, Pets, Services, Community): for each result returns title, price, location, posting date, promotion flags, seller and images. Supports keyword, category, location and radius plus section-specific filters for vehicles, property and jobs.

How to use it

Search live Gumtree (UK classifieds) ads. Returns ad cards with id, url, title, price (GBP), description, city/region, distance, posted_at, status, category_id, is_featured/is_urgent/is_standout/is_premium, has_video, seller_id, is_pro_seller, favourite_count, attributes and image/images/image_count. Scope with keyword, search_category (slug from gumtree/categories), search_location and distance. Vehicle filters: vehicle_make/vehicle_model/vehicle_body_type/vehicle_fuel_type/vehicle_transmission/vehicle_colour/vehicle_doors/vehicle_seats/vehicle_average_mpg plus min/max registration year, mileage and engine size. Property filters: property_type, min/max bedrooms, all_bills_included, council_tax_included, pets_allowed. Job filters: job_contract_type, job_hours, job_level, job_language, recruiter_type, is_course, min/max salary. For Sale filters: condition, delivery_available.

Parameters

• access-token string required

Request body

• timeout integer — Max scrapping execution timeout (in seconds) (default: 300; min: 20; max: 1500)
• keyword string nullable — Search keyword (examples: "iphone", "sofa"; minLength: 1)
• count integer required — Max number of listings to return (min: 1)
• search_category string nullable — Category slug to scope the search: a top-level section (cars, vans, for-sale, jobs, pets, community, business-services, property-to-rent, property-for-sale) or any subcategory slug returned by the gumtree/categories endpoint (examples: "for-sale", "cars", "phones", "computing-it-jobs"; minLength: 1)
• search_location string nullable — Location slug to scope the search (examples: "london", "manchester", "central-london"; minLength: 1)
• distance string nullable — Search radius in miles around the location (one of: "1", "3", "5", "10", "15", "30", "50", "75", "100", "1000")
• sort string nullable — Result ordering (one of: "relevance", "date", "price_lowest_first", "price_highest_first", "distance")
• seller_type array nullable — Filter by seller type (one of: "trade", "private")
• min_price number nullable — Minimum price in GBP (min: 0)
• max_price number nullable — Maximum price in GBP (min: 0)
• has_photos boolean — Only ads that have pictures (default: false)
• is_urgent boolean — Only ads flagged as urgent (default: false)
• is_featured boolean — Only featured ads (default: false)
• search_in_description boolean — Match the keyword against ad descriptions as well as titles (default: false)
• condition array nullable — Item condition (For Sale categories) (one of: "new", "as_good_as_new", "good", "fair")
• delivery_available boolean — Only ads offering delivery (For Sale categories) (default: false)
• vehicle_make string nullable — Vehicle make (Cars and Vans) (one of: "abarth", "ac", "aixam", "alfa_romeo", "aston_martin", "audi", "austin", "bedford", "bentley", "bmc", "bmw", "byd", "cadillac", "caterham", "chery", "chevrolet", "chrysler", "citroen", "cupra", "dacia", "daewoo", "daf_trucks", "daihatsu", "daimler", "dodge", "ds", "ferrari", "fiat", "ford", "genesis", "great_wall", "honda", "hummer", "hyundai", "ineos", "infiniti", "isuzu", "isuzu_trucks", "iveco", "jaecoo", "jaguar", "jeep", "kgm", "kia", "ktm", "lamborghini", "land_rover", "ldv", "leapmotor", "levc", "lexus", "lotus", "lti", "man", "marcos", "marlin", "maserati", "maxus", "maybach", "mazda", "mclaren", "mercedes_benz", "mg", "mg_motor_uk", "microcar", "mini", "mitsubishi", "mitsubishi_fuso", "morgan", "nissan", "omoda", "opel", "perodua", "peugeot", "piaggio", "polestar", "porsche", "proton", "reliant", "renault", "renault_trucks", "rolls_royce", "rover", "saab", "scania", "seat", "skoda", "smart", "ssangyong", "subaru", "suzuki", "talbot", "tesla", "toyota", "tvr", "vauxhall", "volkswagen", "volvo", "westfield", "other_manufacturer")
• vehicle_model array nullable — Vehicle models, valid together with vehicle_make (examples: ["A3","A4"])
• vehicle_body_type array nullable — Vehicle body type (Cars and Vans) (one of: "car_derived_van", "convertible", "coupe", "estate", "hatchback", "light_4x4_utility", "minibus", "motor_caravan", "mpv", "panel_van", "pick_up", "saloon", "sports", "window_van", "other")
• vehicle_fuel_type array nullable — Vehicle fuel type (Cars and Vans) (one of: "diesel", "electric", "gas", "gas_bi_fuel", "hybrid_electric", "petrol", "petrol_gas", "other")
• vehicle_transmission array nullable — Vehicle transmission (Cars and Vans) (one of: "automatic", "manual", "semi_auto", "other")
• vehicle_colour array nullable — Vehicle colour (Cars and Vans) (one of: "biege", "black", "blue", "bronze", "brown", "cream", "gold", "green", "grey", "maroon", "mauve", "multi_coloured", "orange", "pink", "purple", "red", "silver", "white", "yellow", "other")
• vehicle_doors array nullable — Number of doors (Cars and Vans) (examples: [3,5])
• vehicle_seats array nullable — Number of seats (Cars and Vans) (examples: [5,7])
• vehicle_average_mpg string nullable — Minimum average fuel consumption (Cars and Vans) (one of: "over_30", "over_40", "over_50", "over_60")
• min_vehicle_registration_year integer nullable — Earliest registration year (Cars and Vans) (min: 1900)
• max_vehicle_registration_year integer nullable — Latest registration year (Cars and Vans) (min: 1900)
• min_vehicle_mileage integer nullable — Minimum mileage in miles (Cars and Vans) (min: 0)
• max_vehicle_mileage integer nullable — Maximum mileage in miles (Cars and Vans) (min: 0)
• min_vehicle_engine_size integer nullable — Minimum engine size in cc (Cars and Vans) (min: 0)
• max_vehicle_engine_size integer nullable — Maximum engine size in cc (Cars and Vans) (min: 0)
• property_type array nullable — Property type (Property categories) (one of: "flat", "house", "other")
• min_bedrooms integer nullable — Minimum bedrooms (Property categories) (min: 0)
• max_bedrooms integer nullable — Maximum bedrooms (Property categories) (min: 0)
• all_bills_included boolean — Only rentals with all bills included (Property to rent) (default: false)
• council_tax_included boolean — Only rentals with council tax included (Property to rent) (default: false)
• pets_allowed boolean — Only rentals that allow pets (Property to rent) (default: false)
• job_contract_type array nullable — Contract type (Jobs categories) (one of: "cashinhand", "contract", "freelance", "locum", "permanent", "selfemployed", "subcontractor", "voluntary")
• job_hours array nullable — Working hours (Jobs categories) (one of: "evening", "full_time", "morning", "nights", "part_time", "saturday_job", "term-time", "weekends")
• job_level array nullable — Job level (Jobs categories) (one of: "apprenticeship", "experienced", "graduate", "internship", "management")
• job_language array nullable — Required language (Jobs categories) (one of: "arabic", "filipino", "english", "french", "german", "greek", "hindi", "italian", "polish", "romanian", "spanish", "swedish", "thai", "turkish", "urdu")
• recruiter_type array nullable — Recruiter type (Jobs categories) (one of: "direct", "agency")
• is_course boolean — Only training courses (Jobs categories) (default: false)
• min_salary integer nullable — Minimum yearly salary in GBP (Jobs categories) (min: 0)
• max_salary integer nullable — Maximum yearly salary in GBP (Jobs categories) (min: 0)

Response

• @type string (default: "GumtreeAdCard")
• id string required
• url string required
• price number nullable
• currency string (default: "GBP")
• description string nullable
• city string nullable
• region string nullable
• distance string nullable
• posted_at integer nullable
• status string nullable
• category_id string nullable
• is_featured boolean (default: false)
• is_urgent boolean (default: false)
• is_standout boolean (default: false)
• is_premium boolean (default: false)
• has_video boolean (default: false)
• seller_id string nullable
• is_pro_seller boolean (default: false)
• favourite_count integer nullable
• attributes object (default: {})
  • * string
• image string nullable
• images array (default: [])
• image_count integer nullable

Errors

• 422 — The request body did not validate Check the fields against this schema. A URN with the wrong prefix is the most common cause.
• 408 — The request ran past its time limit Raise `timeout` in the request body, up to the maximum this endpoint documents. Lowering `count` or turning off the `with_*` flags also helps, because less work finishes sooner.
• 412 — The entity was not found, or a precondition failed Retrying will not help: either the entity does not exist, or the input points at a different one.
• 429 — Too many requests: a rate limit or a usage window is exhausted When the response carries an X-Retry-After header, wait that many seconds and retry: the same number is in the body as `detail.retry_after`, and the limit clears once that window passes. The message in the body names the limit that was hit.
• 500 — Something broke on our side Retrying will not help. If it keeps happening, send us the X-Request-ID from the response headers.
• 529 — Rate limit reached, or the endpoint is overloaded Wait at least 30 seconds, then retry.

Response headers

• X-Error — Error message text (present only on error)
• X-Request-ID — Unique request identifier
• X-Execution-Time — Execution time in seconds
• X-Result-Count — How many records the body carries. 0 means an empty result, which is a normal answer and not by itself an error. A non-zero count can come back together with X-Error when the failure happened partway through — read this header and X-Error independently.
• X-Total-Available-Results — How many records exist for this query, when the endpoint can say. On a `dry_run` request this is the answer and the body is empty. It saturates: the endpoint's documented maximum means 'at least that many', any smaller number is exact.
• X-Warning — Present when the request body carried keys this endpoint does not document. They were ignored, so any filter you meant to apply through them did not apply. Check the spelling against this schema and retry.
• X-Retry-After — Seconds to wait before retrying. Present only on 429.