4Sale API & Scraper
4Sale (q84sale.com) is where Kuwait buys and sells almost everything, and this API reads it as JSON.
🤖 Using an AI assistant? Copy this link into ChatGPT / Claude / Cursor — it reads every endpoint and parameter instantly and tells you if this API fits your use case.
`search` takes a free-text query across all 14 verticals; `category_listings` walks one category end to end, newest-first or by price; `listing` returns one advert in full. Every row carries the id, the canonical URL, the title, the price in Kuwaiti dinars, the publish and bump times, the images, the district and the category. Because Kuwaiti sellers write in Arabic, each listing arrives twice: the seller's own words and 4Sale's translation, each labelled with the language it is actually in. Car, property and phone listings also carry the structured attributes 4Sale collects - year, mileage, colour, transmission, body type - and `category_attributes` is the dictionary that turns those into names and values for a whole category at once. Arabic queries find more than Latin ones: measured on 2026-10-06, the Arabic spelling of "Land Cruiser" returned 1,825 listings while `camry` returned 1,475 and `iphone` 1,432.
What a 4Sale field actually contains
Six fields that read the opposite of how they look. Every row was measured against live 4Sale responses on 2026-10-06.
| Field | What it holds |
|---|---|
| description | The seller's own words, in the language they wrote them (usually Arabic). description_translated is 4Sale's translation. description_ar and description_en are the same two strings sorted by the script they are actually written in - never by a label. |
| price | A whole number of Kuwaiti dinars, or null. Null means the seller published no price at all, which is normal on services, jobs and pet adverts: 240 of 305 sampled rows carried a price. A price is never reported as 0. |
| published_at vs bumped_at | published_at is when the advert first went up; bumped_at is the last time the seller refreshed it to the top. Sorting by newest uses the bump. |
| attributes_raw vs attributes | attributes_raw is 4Sale's own [{attribute_id, value}] where a value can be an option id (year 2019 arrives as 997). The listing endpoint returns them already decoded as attributes[]; category_attributes gives you the dictionary to decode a whole feed yourself. |
| listings vs paid_placements | listings holds the organic results. Promoted, pinned and 'golden pin' adverts 4Sale puts above them are returned separately in paid_placements, so a market count is never inflated by advertising. |
| seller_name / seller_phone | 4Sale publishes a phone number on every advert. We withhold the seller's name and number by default and set pii_withheld: true; ask for them explicitly to receive them. seller_id and seller_is_business are always returned. |
Deliberate gaps, measured: 4Sale publishes no coordinates and no seller rating, there is no public 'all adverts by this seller' endpoint, and a category feed ignores a free-text query - use search for keywords. total_pages is the real last page; asking past it returns zero rows rather than repeating the last one.
Real request and response JSON
Captured from the indexed primary action, search, on .
{
"method": "POST",
"url": "https://api.reefapi.com/q84sale/v1/search",
"headers": {
"x-api-key": "$REEF_KEY",
"content-type": "application/json"
},
"body": {
"query": "camry",
"limit": 20,
"lang": "en"
}
}{
"ok": true,
"meta": {
"api": "q84sale",
"endpoint": "search",
"mode": "live",
"latency_ms": 498.4,
"record_count": 20,
"bytes": 28645,
"cache_hit": false,
"charged_credits": 1,
"version": "1.0.0",
"request_id": "6e73a76a31fd4716",
"queue_ms": 1.8,
"fetched_at": "2026-10-06T14:47:18.494Z"
},
"data": {
"query": "camry",
"category_id": null,
"sort": "relevance",
"total_listings": 1476,
"total_pages": 74,
"page": 1,
"limit": 20,
"has_more": true,
"listings": [
{
"id": 21211757,
"url": "https://www.q84sale.com/en/listing/toyota-camry-21211757rohDh",
"slug": "toyota-camry-21211757rohDh",
"title": "Toyota Camry",
"title_is_arabic": false,
"description": "Toyota Camry",
"description_translated": "تويوتا كامري",
"description_ar": "تويوتا كامري",
"description_en": "Toyota Camry",
"price": 9300,
"currency": "KWD",
"category_id": 781,
"category_name_en": null,
"category_name_ar": null,
"district_ids": [
-1
],
"district_name": "Kuwait",
"region_id": 1,
"published_at": "2026-09-27T12:41:16+03:00",
"bumped_at": "2026-09-27T12:41:16+03:00",
"expires_at": null,
"image": "https://media.q84sale.com/images/user_adv/resize1000/1790512867510044528.png",
"thumbnail": "https://media.q84sale.com/images/user_adv/resize300/1790512867510044528.png",
"thumbnails": [
"https://media.q84sale.com/images/user_adv/resize300/1790512867510044528.png",
"https://media.q84sale.com/images/user_adv/resize300/1790512868467541011.png"
],
"images_count": 7,
"has_video": null,
"is_premium": false,
"is_chat_enabled": null,
"status": "normal",
"seller_id": null,
"seller_is_business": true,
"seller_logo": "https://media.q84sale.com/images/profile_images/Y1CKzDoDvLfE.png",
"seller_name": null,
"seller_phone": "96524962500",
"seller_phones": [
"96524962500",
"96511000033"
],
"pii_withheld": false,
"attributes_raw": [
{
"attribute_id": "[trimmed-depth]",
"value": "[trimmed-depth]"
},
{
"attribute_id": "[trimmed-depth]",
"value": "[trimmed-depth]"
},
{
"attribute_id": "[trimmed-depth]",
"value": "[trimmed-depth]"
}
]
},
{
"id": 20747974,
"url": "https://www.q84sale.com/en/listing/toyota-camry-toyota-camry-2022-20747974Z9ZFy",
"slug": "toyota-camry-toyota-camry-2022-20747974Z9ZFy",
"title": "TOYOTA CAMRY Toyota CAMRY 2022",
"title_is_arabic": false,
"description": "Sponsorship Al-Sayer for 3 years\n\nApproved by Al-Sayer\n\nExternal accessories:\nEntry without the key\nElectrical mirrors\nSensors for the rear parking\n\nInterior accessories:\nRadio / CD\nBluetooth\nTouch screen\nEnhanced guidance system\nAir conditioning\nElectrical windows\nCentral lock remotely\nControl from the steering wheel",
"description_translated": "كفالة الساير لمدة 3 سنوات\n\nمعتمدة من الساير\n\nالاكسسوارات الخارجية:\nالدخول بدون المفتاح\nمرايا كهربائية\nمجسات للركن الخلفي\n\nالاكسسوارات الداخلية:\nراديو/سي دي\nبلوتوث\nشاشة لمس\nنظام التوجيه المعزز\nمكيف هواء\nنوافذ كهربائية\nقفل مركزي عن بعد\nالتحكم من عجلة القيادة",
"description_ar": "كفالة الساير لمدة 3 سنوات\n\nمعتمدة من الساير\n\nالاكسسوارات الخارجية:\nالدخول بدون المفتاح\nمرايا كهربائية\nمجسات للركن الخلفي\n\nالاكسسوارات الداخلية:\nراديو/سي دي\nبلوتوث\nشاشة لمس\nنظام التوجيه المعزز\nمكيف هواء\nنوافذ كهربائية\nقفل مركزي عن بعد\nالتحكم من عجلة القيادة",
"description_en": "Sponsorship Al-Sayer for 3 years\n\nApproved by Al-Sayer\n\nExternal accessories:\nEntry without the key\nElectrical mirrors\nSensors for the rear parking\n\nInterior accessories:\nRadio / CD\nBluetooth\nTouch screen\nEnhanced guidance system\nAir conditioning\nElectrical windows\nCentral lock remotely\nControl from the steering wheel",
"price": 5799,
"currency": "KWD",
"category_id": 1984,
"category_name_en": null,
"category_name_ar": null,
"district_ids": [
-1
],
"district_name": "Kuwait",
"region_id": 1,
"published_at": "2026-04-07T00:03:18+03:00",
"bumped_at": "2026-04-07T00:03:18+03:00",
"expires_at": null,
"image": "https://media.q84sale.com/images/user_adv/resize1000/17755201831036578317.jpg",
"thumbnail": "https://media.q84sale.com/images/user_adv/resize300/17755201831036578317.jpg",
"thumbnails": [
"https://media.q84sale.com/images/user_adv/resize300/17755201831036578317.jpg",
"https://media.q84sale.com/images/user_adv/resize300/1775520184902899526.jpg"
],
"images_count": 16,
"has_video": null,
"is_premium": false,
"is_chat_enabled": null,
"status": "normal",
"seller_id": null,
"seller_is_business": true,
"seller_logo": "https://media.q84sale.com/images/profile_images/1741272526320082254.png",
"seller_name": null,
"seller_phone": "96522052425",
"seller_phones": [
"96522052425",
"96511010257"
],
"pii_withheld": false,
"attributes_raw": [
{
"attribute_id": "[trimmed-depth]",
"value": "[trimmed-depth]"
},
{
"attribute_id": "[trimmed-depth]",
"value": "[trimmed-depth]"
}
]
},
{
"id": 21161040,
"url": "https://www.q84sale.com/en/listing/2011-camry",
"slug": "2011-camry",
"title": "2011 camry",
"title_is_arabic": false,
"description": "2011 camry",
"description_translated": "كامري 2011",
"description_ar": "كامري 2011",
"description_en": "2011 camry",
"price": 800,
"currency": "KWD",
"category_id": 1984,
"category_name_en": null,
"category_name_ar": null,
"district_ids": [
4
],
"district_name": "Kuwait City",
"region_id": 1,
"published_at": "2026-09-10T11:13:18+03:00",
"bumped_at": "2026-09-10T11:13:18+03:00",
"expires_at": null,
"image": "https://media.q84sale.com/images/user_adv/resize1000/1789038761208569520.jpg",
"thumbnail": "https://media.q84sale.com/images/user_adv/resize300/1789038761208569520.jpg",
"thumbnails": [
"https://media.q84sale.com/images/user_adv/resize300/1789038761208569520.jpg",
"https://media.q84sale.com/images/user_adv/resize300/1789038766128517146.jpg"
],
"images_count": 7,
"has_video": null,
"is_premium": false,
"is_chat_enabled": true,
"status": "normal",
"seller_id": null,
"seller_is_business": false,
"seller_logo": null,
"seller_name": null,
"seller_phone": "96555018046",
"seller_phones": [
"96555018046",
"96500000000"
],
"pii_withheld": false,
"attributes_raw": null
}
],
"paid_placements": [],
"pii_included": true
}
}What the 4Sale API does
| Action | Description | Concrete use case | Key params |
|---|---|---|---|
| search | Keyword search across every 4Sale vertical — cars, property, electronics, furniture, animals, jobs and services — with the price, images, district, category and both language versions of each listing. This is the only 4Sale surface that honours a free-text query. | Price-intelligence teams call search to get keyword search across every 4Sale vertical. | query, category_id, sort, page, limit, ... |
| category_listings | Browse one 4Sale category end to end, newest-first or by price — the whole Kuwaiti used-car, flat-to-rent or iPhone market as a paged feed. Returns the same listing shape as `search` plus the category names 4Sale attaches here. | Classifieds aggregators call category_listings to get browse one 4Sale category end to end, newest-first or by price. | category_id, sort, page, limit, lang, ... |
| listing | One listing in full: the seller's own text and its translation, price, the complete image set, the category breadcrumb, the view count, the publish and bump times, and the category attributes (Year, Mileage, Colour, Brand …) decoded into names and values. | Resale and arbitrage tools call listing to get one listing in full. | id, url, include_attributes, lang, include_pii |
| category_attributes | The filter attributes 4Sale defines for one category, with every drop-down option — the dictionary that turns `attributes_raw` on a listing row into real values, and the list of filters the site itself offers on that category. | Lead-generation teams call category_attributes to get the filter attributes 4Sale defines for one category, with every drop-down option. | category_id, filterable_only, lang |
| category_path | A category's ancestor chain in both languages — leaf first up to one of 4Sale's 14 verticals. Use it to label a listing's category_id, or to walk from a model (Cayenne) up to its make and vertical. | Price-intelligence teams call category_path to get a category's ancestor chain in both languages. | category_id, lang |
| suggest | 4Sale's own search autocomplete: the keywords it recognises for what you typed and, for each, the category id and the predefined filters it maps that keyword onto. The cheapest way to turn a word into a category id. | Classifieds aggregators call suggest to get 4Sale's own search autocomplete. | query, lang |
| districts | Kuwait's geography as 4Sale publishes it: the six governorates, or the areas inside one of them. These are the ids that appear as `district_ids` on every listing. | Resale and arbitrage tools call districts to get kuwait's geography as 4Sale publishes it. | district_id, lang |
| trending | The search terms 4Sale is promoting as trending right now, in Arabic and English — a live read on what Kuwait is shopping for. | Lead-generation teams call trending to get the search terms 4Sale is promoting as trending right now, in Arabic and English. | lang |
Call search from your stack
curl -X POST https://api.reefapi.com/q84sale/v1/search \
-H "x-api-key: $REEF_KEY" \
-H "content-type: application/json" \
-d '{"query":"camry","limit":20,"lang":"en"}'import requests
r = requests.post(
"https://api.reefapi.com/q84sale/v1/search",
headers={"x-api-key": REEF_KEY},
json={
"query": "camry",
"limit": 20,
"lang": "en"
},
)
print(r.json()["data"])const res = await fetch("https://api.reefapi.com/q84sale/v1/search", {
method: "POST",
headers: {
"x-api-key": process.env.REEF_KEY,
"content-type": "application/json",
},
body: JSON.stringify({
"query": "camry",
"limit": 20,
"lang": "en"
}),
});
const { ok, data, meta, error } = await res.json();Ask your MCP-connected assistant: call reefapi.q84sale.search with {"query":"camry","limit":20,"lang":"en"}.Who uses this API and why
- Track the Kuwaiti used-car market daily: walk category 2897 newest-first and keep id, price, year, mileage and colour from the decoded attributes.
- Build a Kuwait rental-price index by paging property-for-rent (808) and grouping the KWD prices by district id.
- Watch resale prices for one phone model: search the Arabic and Latin spellings, then follow each id to its listing for the full description and image set.
- Feed a Gulf lead-generation pipeline with fresh adverts in one category, requesting seller contact only for the rows you actually act on.
- Measure what Kuwait is shopping for week by week from trending, and size each term with the total_listings that search reports for it.
Questions developers ask before integrating
Do I need an account or a Kuwaiti IP to use the 4Sale API?
No. Every endpoint is read without an account, a login or a cookie, and the API handles access for you - you call reefapi.com from anywhere.
Should I search in Arabic or English?
Arabic finds more, because that is what Kuwaiti sellers type. Measured on 2026-10-06: the Arabic spelling of Land Cruiser returned 1,825 listings, `camry` 1,475 and `iphone` 1,432. Latin brand names still work because sellers mix them into Arabic titles. An unknown term honestly returns zero rows instead of a padded page.
Why is price null on some 4Sale listings?
Because the seller published none. 4Sale omits the price entirely on ask-for-price adverts, which is common in services, jobs and pets. Across 305 sampled rows 240 carried a price; in used cars, phones and spare parts it was 10 out of 10. We return null rather than 0 so you can tell 'no price' from 'free'.
What are the 14 verticals and how do I browse one?
Automotive, Property, Electronics, Contracting, Services, Camping, Sports, Animals, Family, Gifts, Furniture, Jobs, Education and Others. Pass the vertical slug or any category id to category_listings - for example category_id 2897 for used cars (12,611 live adverts on 2026-10-06), 808 for property to rent (2,721), 99 for mobile phones (515).
How do I get from a keyword to a category id?
Call suggest with the word. 4Sale answers with the keywords it recognises and the category it maps each one to, plus the filters it would pre-apply - `camry` resolves to the Used Cars category with the Toyota Camry filters attached. category_path then walks any id up to its vertical in both languages.
Can I get the seller's phone number?
4Sale publishes one on every advert, and the API returns it when you explicitly ask for personal data. By default the seller's name and number are withheld and the response says pii_withheld: true, so nothing personal reaches your logs by accident.
How deep can I page through 4Sale results?
As deep as 4Sale itself goes. total_pages is the real last page: a 1,433-hit query at 5 rows per page reported 287 pages, page 287 returned the last 3 rows and page 288 returned none. The last page is never silently repeated, so a crawl terminates.
What does 4Sale not publish?
No map coordinates, no seller rating, no view count outside the listing endpoint, and no public endpoint for every advert by one seller. Those come back as null or are simply absent rather than guessed.
What is the 4Sale API?
4Sale API is a ReefAPI endpoint group for kuwait's biggest classifieds: cars, property, phones, furniture, jobs and services in kwd, arabic and english. It returns live JSON through POST requests under /q84sale/v1.
Is the 4Sale API free to try?
Yes. ReefAPI starts with 1,000 free credits, no card required. 4Sale calls use the same shared credit balance as every other ReefAPI engine.
Do I need a 4Sale login or account?
No login to 4Sale is needed for the API response. You call ReefAPI with your x-api-key header, and the playground can run live examples before you create a production key.
How fresh is the 4Sale data?
The page example is captured from a live search call, and production requests fetch live data through ReefAPI rather than a static sample.
How many credits does the 4Sale API use?
4Sale actions currently cost 1-2 credits per successful call. Failed or blocked calls are free. All APIs draw from one credit pool.
Can I call 4Sale from an AI assistant or MCP client?
Yes. Connect ReefAPI once through MCP and your assistant can call q84sale actions with the same key, credit pool and JSON envelope used by normal REST requests.