# Tayara.tn Tunisia Classifieds

> Search Tayara.tn, Tunisia's largest classifieds site: cars, property, phones, electronics, home, fashion, jobs and services. Free text plus the site's own filters (category, governorate, delegation, price, and vehicle/property attributes such as make, model, year, mileage, fuel, rooms and surface). Nothing is required: no parameters browses the whole site newest first.
> ReefAPI engine `tayara` · 5 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/tayara/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 calls are free except verified SHEIN NOT_FOUND on product/detail and price (4 credits).
- **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). Send the key as `Authorization: Bearer <key>`, or put it in the URL (`?key=<key>`) when the client has no header field, as ChatGPT does.

## Endpoints

### POST https://api.reefapi.com/tayara/v1/search — 2 credits
Search Tayara.tn, Tunisia's largest classifieds site: cars, property, phones, electronics, home, fashion, jobs and services. Free text plus the site's own filters (category, governorate, delegation, price, and vehicle/property attributes such as make, model, year, mileage, fuel, rooms and surface). Nothing is required: no parameters browses the whole site newest first.

**Parameters:**
- `query` (string, optional) — Free-text query, as a Tunisian buyer would type it (French, Arabic or transliterated). Optional: with no query and no filter you browse the whole site (45,892 live listings on 2026-10-07).
- `category` (string, optional) — Top-level category: id, English slug or French name — e.g. `vehicles`, `real-estate`, `tech`, `Immobilier`. Full list: the `categories` action.
- `subcategory` (string, optional) — Subcategory: id, slug or French name — e.g. `cars`, `appartments`, `phones`, `Voitures`. Implies its category.
- `governorate` (string, optional) — One of Tunisia's 24 governorates as Tayara names them (Tunis, Ariana, Sfax, Sousse, Nabeul, Ben Arous …). Accents and case are optional.
- `delegation` (string, optional) — One or more delegations inside `governorate`, comma separated (e.g. `La Marsa`). Requires governorate. Full list: the `locations` action.
- `min_price` (integer, optional) — Minimum price in Tunisian dinars.
- `max_price` (integer, optional) — Maximum price in Tunisian dinars.
- `brand` (string, optional) — Vehicle make exactly as Tayara spells it (Marque): `Volkswagen`, `Peugeot`, `Kia`. Case-sensitive: the site returns nothing for a different capitalisation.
- `model` (string, optional) — Vehicle model exactly as Tayara spells it (Modèle), e.g. `Golf`. Case-sensitive.
- `fuel` (string, optional) — Carburant, e.g. `Essence`, `Diesel`.
- `gearbox` (string, optional) — Boite, e.g. `Manuelle`, `Automatique`.
- `body_type` (string, optional) — Type de carrosserie as Tayara spells it.
- `color` (string, optional) — Couleur du véhicule, e.g. `Noir`, `Blanc`.
- `condition` (string, optional) — Etat du véhicule, e.g. `Avec kilométrage`.
- `year_min` (integer, optional) — Vehicle year from (Année).
- `year_max` (integer, optional) — Vehicle year to (Année).
- `mileage_min` (integer, optional) — Kilometres from (Kilométrage).
- `mileage_max` (integer, optional) — Kilometres up to (Kilométrage).
- `fiscal_power_min` (integer, optional) — Puissance fiscale from (CV).
- `fiscal_power_max` (integer, optional) — Puissance fiscale up to (CV).
- `transaction` (enum, optional) — Property: for sale or for rent (Type de transaction). [one of: sale, rent]
- `rooms_min` (integer, optional) — Property bedrooms from (Chambres).
- `rooms_max` (integer, optional) — Property bedrooms up to (Chambres).
- `bathrooms_min` (integer, optional) — Bathrooms from (Salles de bains).
- `bathrooms_max` (integer, optional) — Bathrooms up to (Salles de bains).
- `area_min` (integer, optional) — Surface from, m² (Superficie).
- `area_max` (integer, optional) — Surface up to, m² (Superficie).
- `ad_params` (object, optional) — Any other attribute filter as {label: value} using the French labels a listing's `attributes` carry, e.g. {"Livraison": "Oui"}. Exact, case-sensitive match.
- `range_params` (object, optional) — Any numeric attribute range as {label: {min, max}}, e.g. {"Superficie": {"min": 100, "max": 200}}.
- `sort` (enum, optional, default "newest") — Result order, the four the site itself offers. [one of: newest, oldest, price_asc, price_desc]
- `page` (integer, optional, default 1) — 1-based page. Tayara serves at most the first 10,000 results of any query; `last_page` in the response is the last page you can actually reach.
- `limit` (integer, optional, default 30) — Rows per page, 1-100.
- `include_premium` (boolean, optional, default false) — Also return the paid placements Tayara shows above the results, as a separate `premium_listings` list (they are not counted in `total`).
- `include_pii` (boolean, optional, default true) — Accepted for compatibility; this API never masks anything. Phone numbers and seller names are returned exactly as the page publishes them.

**Returns:** {query, total, page, limit, last_page, has_more, sort, filters_applied, listings[], premium_listings[]}. Each listing: id, url, title, description, price_tnd (null when the seller published no price), price_raw, currency TND, category_id/category_name, subcategory_id/subcategory_name, governorate, delegation, published_at (ISO-8601 UTC), image, images[], images_count, seller_name, seller_is_shop, seller_is_approved, seller_avatar, is_premium.

**Example request body:**
```json
{
  "query": "golf",
  "subcategory": "cars",
  "sort": "newest",
  "limit": 30
}
```

### POST https://api.reefapi.com/tayara/v1/listing — 2 credits
One Tayara listing in full: title, full description, price, every image, location, the advert's contact phone, all structured attributes (make, model, year, mileage, fuel, rooms, surface …) and the seller block — name, account phone, shop flag, shop page and how many live listings they have.

**Parameters:**
- `id` (string, optional) — Tayara listing id (24 hex characters), from `search`.
- `url` (string, optional) — Or the listing URL (https://www.tayara.tn/item/.../<id>/).
- `include_pii` (boolean, optional, default true) — Accepted for compatibility; this API never masks anything. Phone numbers and seller names are returned exactly as the page publishes them.

**Returns:** {id, url, title, description, price_tnd, price_raw, price_ld_json, price_mismatch, currency, category_id, category_name, subcategory_id, subcategory_name, governorate, delegation, published_at, phone, attributes[{label, value}], attributes_map, image, images[], images_count, boost_level, is_sold, is_deleted, state, seller {id, name, phone, email, avatar, is_shop, shop_url, shop_description, address, active_listings}}. Either `id` or `url` is required.

**Example request body:**
```json
{
  "url": "https://www.tayara.tn/item/6ac61fbacdf7e8adb5ef4ef1/"
}
```

### POST https://api.reefapi.com/tayara/v1/seller_listings — 2 credits
Every live listing of one Tayara seller or shop, paged and sortable — the seller id comes from a `listing` response.

**Parameters:**
- `seller_id` (string, required) — The seller id a `listing` returns in seller.id (search rows do not carry it).
- `query` (string, optional) — Optional free text inside that seller's listings.
- `sort` (enum, optional, default "newest") — Result order, the four the site itself offers. [one of: newest, oldest, price_asc, price_desc]
- `page` (integer, optional, default 1) — 1-based page. Tayara serves at most the first 10,000 results of any query; `last_page` in the response is the last page you can actually reach.
- `limit` (integer, optional, default 30) — Rows per page, 1-100.
- `include_pii` (boolean, optional, default true) — Accepted for compatibility; this API never masks anything. Phone numbers and seller names are returned exactly as the page publishes them.

**Returns:** {seller_id, total, page, limit, last_page, has_more, sort, listings[]}. Listing shape as in `search`.

**Example request body:**
```json
{
  "seller_id": "66f1567bb3a80490e8d2e665",
  "limit": 10
}
```

### POST https://api.reefapi.com/tayara/v1/categories — 1 credit
Tayara's category tree: 10 top-level categories and their subcategories with the ids, slugs and French names `search` accepts.

**Parameters:**
- `category` (string, optional) — Only this top-level category and its subcategories (id, slug or name).

**Returns:** {category_count, categories[{id, name, slug, subcategories[{id, name, slug}]}]}

**Example request body:**
```json
{
  "category": "vehicles"
}
```

### POST https://api.reefapi.com/tayara/v1/locations — 1 credit
Tunisia's 24 governorates and their delegations, spelled exactly as Tayara filters on them.

**Parameters:**
- `governorate` (string, optional) — Only this governorate's delegations.

**Returns:** {governorate_count, governorates[{name, delegations[]}]}

**Example request body:**
```json
{
  "governorate": "Tunis"
}
```

## At scale
- **Volume:** 5M+ requests a day, measured at 60 requests a second across the fleet with no
  central bottleneck. Per-key limits are raised for high-volume accounts; volume pricing on request.
- **Missing a source:** tell us a site we do not cover and it becomes an engine. A customer asked
  for bestprice.gr on 21 Sep 2026 and it was in the catalog on 22 Sep.
- **Support:** 2 minute median time from a question in the live chat to the first answer. Setup
  help included, no support tier to buy.
- **One key, one credit pool** across every API. No per-site plans, no separate subscriptions.

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