# Ouedkniss API scraper — search Algeria's largest classifieds marketplace (ouedkniss.com): keyword and category search with wilaya/city, price-band, photo and sort filters, full ad detail with every photo and the ad's own specification table, the live category tree with its region and city ids, and professional store search. Prices come back in Algerian dinar with the source's own `price_unit` and `price_preview` beside every number; an unpriced ad returns null, never a fake zero. No account, public logged-out data only, no seller phone numbers.

> Search Ouedkniss classifieds by keyword and/or category, filtered by wilaya (region) ids, city ids, price band, has-photo and has-price, with two sorts and paging (up to 48 ads per page). Give at least `query` or `category`. Returns the source's own `total_results`, the category Ouedkniss matched the search to, and the sibling categories it suggests.
> ReefAPI engine `ouedkniss` · 4 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/ouedkniss/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.
- **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). Clients that add connectors by URL, such as ChatGPT and the Claude app, connect with OAuth 2.1 (the user pastes their key once on a ReefAPI page; discovery at `/.well-known/oauth-protected-resource/mcp`). Config files send the key as `Authorization: Bearer <key>`. `?key=<key>` in the URL also works as a last-resort fallback.

## Endpoints

### POST https://api.reefapi.com/ouedkniss/v1/search — 1 credit
Search Ouedkniss classifieds by keyword and/or category, filtered by wilaya (region) ids, city ids, price band, has-photo and has-price, with two sorts and paging (up to 48 ads per page). Give at least `query` or `category`. Returns the source's own `total_results`, the category Ouedkniss matched the search to, and the sibling categories it suggests.

**Parameters:**
- `query` (string, optional) — Free-text keywords, in French or Arabic — the site's own search box. Give at least `query` or `category`.
- `category` (string, optional) — Ouedkniss category slug (e.g. `telephones`, `automobiles-voitures`, `immobilier-vente`). Read the live slugs with the `categories` action. Give at least `query` or `category`.
- `region_ids` (array, optional) — Numeric wilaya ids (16 = Alger). The `categories` action lists every id with its name. Names are not accepted — Ouedkniss filters on ids only.
- `city_ids` (array, optional) — Numeric city/commune ids (560 = Bab el Oued). These are NOT wilaya ids: passing a wilaya id here matches nothing. The `categories` action lists them.
- `price_min` (integer, optional) — Lower bound of the price band, in the category's own price unit (see `price_unit` on every row).
- `price_max` (integer, optional) — Upper bound of the price band, in the category's own price unit.
- `has_pictures` (boolean, optional) — true keeps only ads that carry at least one photo.
- `has_price` (boolean, optional) — true keeps only ads that state a price.
- `exchange` (enum, optional) — Filter on whether the seller accepts a swap. Omit for both. [one of: yes, no]
- `delivery_available` (boolean, optional) — true keeps only ads that offer delivery. Ouedkniss publishes no 'no delivery' side of this filter, so false is rejected rather than silently ignored — read `has_delivery` on each row instead.
- `seller_type` (enum, optional) — Keep only ads from professional stores, or only ads from private sellers. Omit for both. [one of: store, individual]
- `sort` (enum, optional, default "refreshed") — Ouedkniss orders by the ad's refresh time by default; `newest` orders by original creation time. [one of: refreshed, newest]
- `page` (integer, optional, default 1) — 1-based page number.
- `page_size` (integer, optional, default 24) — Ads per page, 1-48 (the site's own maximum is 48).
- `language` (enum, optional, default "fr") — Language of the category and specification LABELS Ouedkniss returns. Ad titles and descriptions come back exactly as the seller typed them and are never translated. [one of: fr, ar, en]

**Returns:** query/category/filter echo, language, total_results (the source's own paginator total), page, page_size, last_page, has_more, currency, matched_category{} and suggested_categories[], plus listings[] with listing_id, url, title, description, price (always dinars), price_preview and price_display (the number and string Ouedkniss itself prints, in price_unit), price_preview_basis (total | per_square_metre), price_unit, price_type, price_currency, old_price, exchange_type, city/city_id/region/region_id, store{}, image, images[], image_count, specs[], refreshed_at, status, has_delivery, delivery_type, payment_method, like_count and is_from_store. An ad with no price returns null for all three price numbers — Ouedkniss prints 0 there.

**Example request body:**
```json
{
  "query": "iphone 13"
}
```

### POST https://api.reefapi.com/ouedkniss/v1/listing — 1 credit
Full detail of one Ouedkniss ad: title, complete description, price with its unit, wilaya and city, the store or private seller, every photo at full size and the ad's own specification table. Accepts the ad id or the ad URL.

**Parameters:**
- `listing_id` (string, optional) — Numeric ad id — the digits after `-d` in the ad URL. Give `listing_id` or `url`.
- `url` (string, optional) — Full ouedkniss.com ad URL; the id is taken from it. Give `listing_id` or `url`.
- `language` (enum, optional, default "fr") — Language of the category and specification LABELS Ouedkniss returns. Ad titles and descriptions come back exactly as the seller typed them and are never translated. [one of: fr, ar, en]

**Returns:** listing_id, url, title, slug, description, price (dinars), price_preview, price_display, price_preview_basis, price_unit, price_type, price_currency, old_price, exchange_type, created_at, refreshed_at, status, view_count, like_count, city/city_id/region/region_id, category/category_id/category_slug, store{} (with follower_count and announcements_count), seller_user_id, image, images[], image_count, specs[] (label + value), has_delivery, delivery_type, payment_method, is_from_store, language.

**Example request body:**
```json
{
  "url": "https://www.ouedkniss.com/smartphones-iphone13-bab-el-oued-alger-algerie-d54590864"
}
```

### POST https://api.reefapi.com/ouedkniss/v1/categories — 1 credit
The live Ouedkniss category tree — the resolver `search` needs, because a category slug is the strongest filter the marketplace has. With no `category` it returns the top-level categories off the site's own menu; with a `category` slug it returns that category with its children, its parent chain, its price units and its filterable specifications (each with the value list Ouedkniss allows), plus how many ads sit under it right now.

**Parameters:**
- `category` (string, optional) — Category slug to open, e.g. `telephones`, `automobiles-voitures`. Omit to list the top-level categories.
- `language` (enum, optional, default "fr") — Language of the category and specification LABELS Ouedkniss returns. Ad titles and descriptions come back exactly as the seller typed them and are never translated. [one of: fr, ar, en]

**Returns:** With no category: categories[] (category_id, name, slug, icon). With a category: category{} (category_id, name, slug, icon, price_units, has_delivery, delivery_type, is_without_exchange), children[], parent_tree[], parent{}, specifications[] (codename, label, type, class, is_required, values[]), suggested_categories[] and total_listings.

**Example request body:**
```json
{
  "category": "automobiles-voitures"
}
```

### POST https://api.reefapi.com/ouedkniss/v1/stores — 1 credit
Search the professional stores (boutiques) on Ouedkniss by name or keyword, with their location, follower count and how many ads they run.

**Parameters:**
- `query` (string, required) — Store name or keyword.
- `page` (integer, optional, default 1) — 1-based page number.
- `page_size` (integer, optional, default 24) — Stores per page, 1-48.
- `language` (enum, optional, default "fr") — Language of the category and specification LABELS Ouedkniss returns. Ad titles and descriptions come back exactly as the seller typed them and are never translated. [one of: fr, ar, en]

**Returns:** query echo, total_results, page, page_size, last_page, has_more and stores[] with store_id, name, slug, url, website, description, image, is_official, is_verified, follower_count, announcements_count, city/city_id and region/region_id.

**Example request body:**
```json
{
  "query": "phone"
}
```

## 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=ouedkniss
- Human docs page: https://reefapi.com/docs/ouedkniss
- Overview page: https://reefapi.com/ouedkniss-api
- Every ReefAPI API in one file (for your AI): https://reefapi.com/llms-full.txt
