# Hepsiburada Product Search & Category Price Scraper (`dataspryva/hepsiburada-product-search-and-category-price`) Actor

Search Hepsiburada by keyword, browse a category page, look up specific product URLs, or find a keyword's top sellers, and get price, rating, discount, and seller details for each product.

- **URL**: https://apify.com/dataspryva/hepsiburada-product-search-and-category-price.md
- **Developed by:** [Dataspryva](https://apify.com/dataspryva) (community)
- **Categories:** E-commerce, Automation, Lead generation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.49 / 1,000 results

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Hepsiburada Product Search & Category Price Scraper

Collect live product data from Hepsiburada, Turkey's largest multi-category marketplace. Search by keyword, browse category pages, or look up specific products by URL or ID. Search and category records carry current price, list price when discounted, discount, rating, review count, seller, stock signal, delivery signal, installments, images, attributes, and category. Enable full details to add descriptions, specifications, variants, stock counts, seller ratings, shipping cost, and return policy. No login, cookies, API key, or proxy setup is required.

### What this actor does

- **Search by keyword:** one or many product searches, with Hepsiburada's own sort orders and filters.
- **Browse categories:** paste one or more Hepsiburada category URLs and collect their product listings.
- **Look up products:** paste product URLs, short product URLs, or bare product/SKU IDs for full detail.
- **Filter on the site:** price range, brand, seller, minimum rating, fast delivery, discounted products, and official sellers.
- **Add full details when needed:** descriptions, specifications, variants, stock counts, seller ratings, shipping cost, and return policy.
- **Go beyond the default page limit:** split broad searches by price band with `maximizeCoverage`.
- Empty fields are omitted from each record, never written as `null`.

### Output per product

Identity and classification:

- `productId` — Hepsiburada product-level ID (for example `HBC0000ELZI4O`)
- `sku` — selected variant SKU (for example `HBCV0000ELZI58`)
- `barcode` — product barcode/GTIN when published
- `title`, `brand`
- `category` — leaf category name
- `categoryId` — leaf category ID
- `categoryPath` — full breadcrumb path (with full details)
- `productUrl` — absolute Hepsiburada product URL
- `imageUrl`, `imageUrls` — main image and gallery

Pricing and reviews:

- `price` — current price in TRY
- `originalPrice` — list price before a real discount
- `discountPercent` — discount percentage when the source publishes one
- `currency` — `TRY`
- `rating` — average customer rating (0-5)
- `reviewCount` — number of customer reviews
- `installmentCount`, `installmentAmount`, `installmentText` — installment plan when published
- `taxVatRate` — VAT rate when published

Seller, stock and delivery:

- `seller`, `sellerId`, `sellerUrl`
- `sellerCity`, `sellerCountry`
- `sellerRating` — seller score on Hepsiburada's 0-10 scale
- `sellerReviewCount`
- `sellerIsOfficial` — true for authorized/official sellers
- `isMerchant` — true when a marketplace seller fulfils the listing, false for Hepsiburada
- `inStock`, `stockQuantity`, `isPreOrder`
- `shipmentDays`, `fastShipping`, `freeShipping`
- `shippingCost`, `shippingCurrency`
- `returnPolicyDays`, `returnPolicyUrl`

Variants and specifications:

- `hasVariants`
- `variants[]` — SKU, title, URL, price, stock, barcode, image, and attributes per variant
- `attributes` — selected colour/capacity/size attributes
- `specifications` — product specification table as name/value pairs
- `tags`, `promotions` — human-readable marketplace labels and campaign text when published; internal tag IDs are never emitted

Provenance:

- `position` — global 1-based order across the run; duplicates are skipped, so positions stay unique
- `searchQuery` — the keyword that produced the record
- `sourceUrl`, `sourceType`, `page` — provenance; `sourceUrl` is the actual page or price-band query URL
- `recordType` — always `product`
- `scrapedAt` — ISO 8601 timestamp

#### Mode differences and limits

- Search and category records contain listing fields only. Set `includeProductDetails=true` to add description, specifications, variants, stock quantity, seller rating, shipping cost, and return policy to each record.
- `productDetails` records include the top-level `productUrl`, `taxVatRate`, `installmentCount`, `installmentAmount`/`installmentText` when published, and human-readable `promotions`. The actor looks up the product's search listing to recover the installment plan and labels when the detail page only has a count.
- A single search or category slice is capped at 49 pages (1,764 raw rows). Repeated or promoted products are deduplicated, so unique counts can be lower; the actor continues across price bands for large targets and reports an honest shortfall when the source is exhausted.
- `maximizeCoverage` splits the price range into bands and takes products round-robin from each band, so cheap and expensive products share the budget. `position` is global and `sourceUrl` identifies the band/query URL.

### Input

| Field | Type | Default | Description |
|---|---|---|---|
| `mode` | string | `search` | `search`, `category`, or `productDetails` |
| `searchQueries` | array | – | Keywords for keyword search (mode=search) |
| `categoryUrls` | array | – | Hepsiburada category URLs (mode=category) |
| `productUrls` | array | – | Product URLs, short URLs, or bare IDs (mode=productDetails) |
| `sortBy` | string | `recommended` | `recommended`, `lowestPrice`, `highestPrice`, `bestSelling`, `mostReviewed`, `topRated`, `highestDiscount`, `newest` |
| `minPrice` | integer | – | Minimum price in TRY |
| `maxPrice` | integer | – | Maximum price in TRY |
| `minRating` | string | – | `3`, `4`, or `4.5` stars and up |
| `brands` | array | – | Exact brand names |
| `sellers` | array | – | Exact seller names |
| `discountedOnly` | boolean | `false` | Only products marked as advantageous/discounted |
| `fastDeliveryOnly` | boolean | `false` | Only products with a fast-delivery signal |
| `officialSellersOnly` | boolean | `false` | Only authorized/official sellers |
| `includeProductDetails` | boolean | `false` | Add description, specifications, variants, stock count, seller rating, shipping cost, and return policy |
| `maximizeCoverage` | boolean | `false` | Split broad searches into price bands to exceed the single-query limit |
| `maxItems` | integer | `100` | Maximum records per query/category; total for product lookup (1-2000) |

#### Example: keyword search with filters

```json
{
  "mode": "search",
  "searchQueries": ["laptop"],
  "minPrice": 20000,
  "maxPrice": 50000,
  "minRating": "4",
  "brands": ["Lenovo", "Asus"],
  "sortBy": "lowestPrice",
  "maxItems": 100
}
```

#### Example: browse a category and add full details

```json
{
  "mode": "category",
  "categoryUrls": [
    "https://www.hepsiburada.com/laptop-notebook-dizustu-bilgisayarlar-c-98"
  ],
  "sortBy": "bestSelling",
  "includeProductDetails": true,
  "maxItems": 50
}
```

#### Example: look up product URLs and IDs

```json
{
  "mode": "productDetails",
  "productUrls": [
    "https://www.hepsiburada.com/acer-nitro-anv15-52-intel-core-i5-13420h-16gb-1tb-ssd-rtx5050-freedos-15-6-165hz-tasinabilir-bilgisayar-nh-qz7ey-004-p-HBCV0000ELZI58",
    "HBC0000EMXA9B"
  ],
  "maxItems": 10
}
```

#### Example: broad coverage with price bands

```json
{
  "mode": "search",
  "searchQueries": ["laptop"],
  "maximizeCoverage": true,
  "maxItems": 2000
}
```

### Use cases

- **Price monitoring:** track current price, list price, and discount changes for a product set.
- **Competitor catalog tracking:** compare brands, sellers, and price bands in a category.
- **Market research:** measure assortment, ratings, and review counts across Turkish e-commerce.
- **Stock and delivery checks:** monitor availability, stock counts, shipping cost, and delivery days.
- **Catalog enrichment:** fill internal product databases with specifications, variants, images, and barcodes.
- **Seller analysis:** compare official sellers and marketplace sellers by rating and product mix.

### FAQ

**What is the difference between `productId` and `sku`?**
`productId` is Hepsiburada's product-level ID. `sku` is the selected variant's SKU. A product can have several SKUs for colour, capacity, or size.

**Why is `originalPrice` missing on some records?**
Only products with a real discount publish a list price above the current price. When there is no discount, the field is omitted.

**Why are some fields missing from search results?**
Search and category pages publish price, rating, seller, images, and installments, but not descriptions, specifications, variants, stock counts, or return policy. Enable `includeProductDetails` to fetch those from each product page.

**What does `includeProductDetails` cost in time?**
It opens one extra product page per record. Small runs finish in seconds; larger runs take longer. The default is off.

**Why do I get fewer than `maxItems` results, and is it per query?**
For `search` and `category`, `maxItems` is per query or category; for `productDetails`, it is the total across all product URLs. A single slice is capped at 49 pages (1,764 raw rows), and deduplication can lower the unique count. For large targets, the actor automatically continues across price bands and takes products round-robin from each band. If the source runs out, the status message reports how many records were requested and emitted.

**Are prices in Turkish Lira?**
Yes. Hepsiburada is a Turkey-only marketplace and all prices are returned in TRY.

**Can I filter by brand and seller?**
Yes. Enter exact brand or seller names in `brands` or `sellers`. Matching is done by Hepsiburada's own filters.

**Does the actor collect full review text or Q\&A?**
No. It collects the rating and review count for each product. Full review and Q\&A collection is not part of this version.

**Do I need a proxy, login, or cookies?**
No. The actor connects directly to Hepsiburada's public pages. Just choose a mode, fill in the inputs, and run it.

**Is this affiliated with Hepsiburada?**
No. This is an independent, third-party actor that reads Hepsiburada's public pages and is not operated by or affiliated with Hepsiburada.

# Actor input Schema

## `mode` (type: `string`):

Choose keyword search, category browsing, or product lookup.

## `searchQueries` (type: `array`):

One or more product searches (mode=search). Each query is collected separately.

## `categoryUrls` (type: `array`):

Hepsiburada category page URLs (mode=category), e.g. https://www.hepsiburada.com/laptop-notebook-dizustu-bilgisayarlar-c-98

## `productUrls` (type: `array`):

Product page URLs, short product URLs, or bare product/SKU IDs (mode=productDetails).

## `sortBy` (type: `string`):

Result order for search and category modes.

## `minPrice` (type: `integer`):

Lowest product price to include, in Turkish Lira.

## `maxPrice` (type: `integer`):

Highest product price to include, in Turkish Lira.

## `minRating` (type: `string`):

Only include products rated at or above this many stars.

## `brands` (type: `array`):

Exact brand names to include, e.g. Lenovo, Asus. Leave empty for all brands.

## `sellers` (type: `array`):

Exact seller names to include, e.g. Hepsiburada. Leave empty for all sellers.

## `discountedOnly` (type: `boolean`):

Keep only products Hepsiburada marks as advantageous or discounted.

## `fastDeliveryOnly` (type: `boolean`):

Keep only products with Hepsiburada's fast-delivery signal.

## `officialSellersOnly` (type: `boolean`):

Keep only products from authorized or official sellers.

## `includeProductDetails` (type: `boolean`):

Open each product page to add description, specifications, variants, stock count, seller rating, shipping cost, and return policy. One extra request per record.

## `maximizeCoverage` (type: `boolean`):

Split broad searches into price bands to go beyond the site's single-query result limit.

## `maxItems` (type: `integer`):

Maximum records per search query or category (1-2000). For product lookup it is the total across all URLs.

## Actor input object example

```json
{
  "mode": "search",
  "searchQueries": [
    "laptop"
  ],
  "sortBy": "recommended",
  "minRating": "",
  "discountedOnly": false,
  "fastDeliveryOnly": false,
  "officialSellersOnly": false,
  "includeProductDetails": false,
  "maximizeCoverage": false,
  "maxItems": 3
}
```

# Actor output Schema

## `results` (type: `string`):

Dataset containing all scraped Hepsiburada product records.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "mode": "search",
    "searchQueries": [
        "laptop"
    ],
    "sortBy": "recommended",
    "minRating": "",
    "discountedOnly": false,
    "fastDeliveryOnly": false,
    "officialSellersOnly": false,
    "includeProductDetails": false,
    "maximizeCoverage": false,
    "maxItems": 3
};

// Run the Actor and wait for it to finish
const run = await client.actor("dataspryva/hepsiburada-product-search-and-category-price").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "mode": "search",
    "searchQueries": ["laptop"],
    "sortBy": "recommended",
    "minRating": "",
    "discountedOnly": False,
    "fastDeliveryOnly": False,
    "officialSellersOnly": False,
    "includeProductDetails": False,
    "maximizeCoverage": False,
    "maxItems": 3,
}

# Run the Actor and wait for it to finish
run = client.actor("dataspryva/hepsiburada-product-search-and-category-price").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "mode": "search",
  "searchQueries": [
    "laptop"
  ],
  "sortBy": "recommended",
  "minRating": "",
  "discountedOnly": false,
  "fastDeliveryOnly": false,
  "officialSellersOnly": false,
  "includeProductDetails": false,
  "maximizeCoverage": false,
  "maxItems": 3
}' |
apify call dataspryva/hepsiburada-product-search-and-category-price --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,dataspryva/hepsiburada-product-search-and-category-price"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/uHUJG57Ky3nZjRKsG/builds/SrCZjDQaXWKNdG1vQ/openapi.json