# Serbia Grocery Prices: Retailer Price Lists by Barcode (`yappman/serbia-grocery-prices`) Actor

Look up Serbian grocery prices by barcode, product name or category from retailer price lists hosted on the national Open Data Portal (covered retailers are listed in the README). One row per product per retailer: price in dinars, promotion, unit price, VAT, list date, source and licence.

- **URL**: https://apify.com/yappman/serbia-grocery-prices.md
- **Developed by:** [Russell Yapp](https://apify.com/yappman) (community)
- **Categories:** E-commerce, Business
- **Features:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 33.3% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $2.00 / 1,000 rows

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

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

## Serbia Grocery Prices

Look up Serbian grocery prices by barcode (EAN), by words in the product name (Latin or Cyrillic), or by category. The Actor reads price lists that Serbian retailers publish on the national Open Data Portal. A price-list rule (Pravilnik, Sl. glasnik RS 76/2026 as amended by 98/2026) requires larger retailers to publish them there; the rule does not cover re-use, which rests on the licence shown on each dataset. It reads only the files held on the portal itself: 8 retailers on 17 November 2026, listed below. Many retailers' portal entries link to a file on the retailer's own server instead; those are not read, so a retailer you expect may be missing. Each row is one product at one retailer, with the retailer's listed price in dinars, any reduced price and its dates, the unit price, the VAT rate, the price list's date, and the source and licence. **The price is the retailer's highest valid price across its shops, as the price-list rule and each dataset's description state; a given shop may charge less.**

Na srpskom: cene namirnica u Srbiji po barkodu (EAN), nazivu proizvoda ili kategoriji (цене намирница у Србији по баркоду, називу производа или категорији).

### What it costs

You pay per event (pay per event pricing; prices in US dollars):

| Event | Price | When |
| --- | --- | --- |
| `run` | $0.005 | once per run, with the first retailer file read |
| `retailerFile` | $0.003 | for each retailer file read and checked, even if nothing in it matches |
| `row` | $0.002 | for each row in your dataset |

Example: 10 barcodes checked at all covered retailers, 40 rows found: $0.005 + 8 × $0.003 + 40 × $0.002 = **$0.109**. One barcode at two named retailers, 2 rows: $0.005 + 2 × $0.003 + 2 × $0.002 = **$0.015**.

The price lists themselves are free on the Serbian Open Data Portal. You pay for the lookup: finding each retailer's file on the portal, checking it, matching your barcodes or words, and returning rows with the source on each one.

- The default `retailers` (empty) reads every covered retailer: up to 15 `retailerFile` events, even for one barcode that matches nothing (fewer when `maxItems` is reached in search or category mode, when your spending limit stops the run, or when a retailer's file is not on the portal or cannot be read). Name the retailers you need to pay for fewer.
- A file that cannot be read, is too large, or is not on the portal is **never charged**. If no selected retailer can be read, the run fails and nothing is charged.
- Your spending limit stops the run cleanly when it is reached. In the rare case that your limit leaves room for the `run` event but not for the first `retailerFile`, the run ends having charged `run` only, with no file read.
- In search and category mode, `maxItems` counts rows across all the retailers read, not per retailer. Barcode mode has no `maxItems`: it returns every listed product for up to 500 barcodes at every retailer read, bounded only by your spending limit, so start with a short barcode list.
- If the platform restarts a run part way, every row is stored and charged once: on restart the run compares the platform's own count of charged rows with its progress record. In the unlikely case that the platform also loses the run's own key-value store during a restart, you are not charged for more retailer files than were read, but a file already paid for may be charged again, and rows already stored may be stored and charged again.

### Example input

```json
{
  "mode": "barcode",
  "barcodes": ["8606107841571", "8600742012853"],
  "retailers": ["beltorg", "ros-produkt"],
  "listType": "current"
}
```

```json
{
  "mode": "search",
  "query": "mleko 1l",
  "brand": "Imlek",
  "maxItems": 50
}
```

```json
{
  "mode": "category",
  "category": 1,
  "retailers": ["ros-produkt"],
  "maxItems": 100
}
```

- **barcode** (default): up to 500 13-digit barcodes; the GS1 check digit is verified and only rows whose barcode passes it are returned. A barcode must match the 13-digit code a retailer's list publishes, and the same product can carry a different code in another country.
- **search**: words in the product name, Latin or Cyrillic (accents and case ignored), optionally a brand; `maxItems` rows at most. Rows whose barcode fails the check are included and marked.
- **category**: a category number (1 to 24) or its name; `maxItems` rows at most.
- `listType`: `current` (the latest valid list) or `monthly` (the 1st-of-month snapshot).

### Quick spec for AI agents

- **Purpose:** look up Serbian grocery prices in the price lists retailers publish on the Serbian Open Data Portal.
- **`mode`:** `barcode` needs `barcodes` (up to 500 13-digit codes with a valid GS1 check digit); `search` needs `query` (Latin or Cyrillic, optional `brand`); `category` needs `category` (1 to 24, or its name).
- **Other inputs:** `retailers` (retailer keys; empty means every covered retailer), `listType` (`current` or `monthly`, default `current`), `maxItems` (1 to 10,000, default 100; search and category modes only).
- **Output:** one dataset row per product per retailer, with `price` in dinars, `reducedPrice`, `unitPrice`, `vatRate`, `priceListDate`, `barcodeCheck` and the source fields. A `RUN_SUMMARY` record names every retailer skipped and why.
- **Cost:** `run` $0.005 once, `retailerFile` $0.003 for each file read, `row` $0.002 for each row. Empty `retailers` reads every covered retailer, so name the ones you need.
- **Reading the result:** the price is the retailer's highest valid price across its shops. The Actor never says which price is cheapest in Serbia.

Minimal inputs:

```json
{ "mode": "barcode", "barcodes": ["8606107841571"] }
```

```json
{ "mode": "search", "query": "mleko", "maxItems": 10 }
```

```json
{ "mode": "search", "query": "чоколада", "maxItems": 10 }
```

```json
{ "mode": "category", "category": 1, "maxItems": 10 }
```

### Retailers covered

A retailer is read when its dataset on the Serbian Open Data Portal holds exactly one CSV file hosted on the portal itself. On 17 November 2026 that was true for 8 retailers:

| Key | Publisher (as on the portal) |
| --- | --- |
| `metro` | METRO Cash\&Carry doo Beograd |
| `beltorg` | Beltorg DOO |
| `vp-dima` | VP DIMA |
| `medius` | Medius d.o.o. Nova Pazova |
| `qvattro` | Qvattro Company |
| `soulfood` | Soulfood doo Beograd |
| `domaca-trgovina` | Domaca trgovina doo |
| `ros-produkt` | ROS PRODUKT SERVIS |

Seven more are on the list and are read again automatically if their file returns to the portal: `ric`, `aman`, `veropoulos`, `matijevic`, `tekijanka`, `fortuna`, `zam`. On 17 November 2026 their datasets held no CSV file hosted on the portal itself; files on retailers' own servers are not read. Each run's `RUN_SUMMARY` names every retailer skipped and why.

### Output

One row per product per retailer: `barcode`, `barcodeCheck` (`valid` or `invalid`), `barcodeScope` (`global`, `in-store` or `unknown`), `productName`, `brand`, `categoryNumber`, `categoryName`, `retailer`, `retailerFormat`, `unit`, `price` (RSD), `unitPrice`, `reducedPrice`, `promotionStart`, `promotionEnd`, `vatRate`, `priceListDate`, `listType`, `onPromotion`, and the source fields `source`, `datasetPage`, `sourceUrl`, `downloadedAt`, `changes`, `licence`, `disclaimer`.

- Barcodes starting 20 to 29, 02, 04, 98 or 99 are the retailer's own (`barcodeScope: in-store`) and are not comparable across retailers.
- `onPromotion` is true when a reduced price below the regular one is valid today in Belgrade.
- Matching across retailers relies on the retailers' own barcodes. The Actor never claims a price is the cheapest in Serbia, only what each retailer read lists.
- A text value (or a barcode that fails the check) that looks like an email address or phone number is replaced by `[removed: contact-like text]` (the row and its prices are kept). A barcode written like a Serbian phone number in the 00381 form is replaced even when it passes the check digit; it then reads `barcodeCheck: invalid` and `barcodeScope: unknown`, so a real product code of that shape cannot be looked up. A text starting with `=`, `+`, `-` or `@` gets a leading apostrophe so a spreadsheet never runs it.

### FAQ

**Is this the price in my local shop?** Not necessarily. The portal list shows one price per retailer, the highest valid one where its shops differ. The rule asks retailers to publish per-shop lists on their own websites; this Actor does not read them.

**How fresh is it?** Each run reads the file held on the portal at run time. `priceListDate` is the list's own date, and the rule asks a retailer to publish a new list when its prices change, so an older date can still be current. Some retailers also keep a copy on their own server, which this Actor does not read and which may be newer; check `priceListDate` before relying on a price.

**Why is a retailer missing from my results?** Its file may not be on the portal today (see Retailers covered), it may not list the product, or the file could not be read. `RUN_SUMMARY` names each skipped retailer with the reason.

**What licence is on the data?** Each dataset is marked on the portal with the Serbian Open Data Licence. Its text allows commercial and non-commercial re-use and asks that each re-use names the source, the download date and address, and any changes; every row carries these fields. If you republish, the licence asks you to keep them. The licence was written for data published by public bodies, and these lists are published by retailers. We pass on the licence as stated on each dataset and give no warranty of rights; read the licence on the portal for your own use. This is not legal advice.

**Does it store data between runs?** No. Each run reads the files it needs once and writes your rows to your own dataset, plus a run summary (`RUN_SUMMARY`) and a progress record (`PROGRESS`, used only if the platform restarts the run) in the run's own key-value store.

**Can I schedule it?** Yes, as an Apify schedule or task. A weekly run of a short barcode list at named retailers is the cheapest way to track prices.

### Source and licence

Source: each retailer's price list as published on the Serbian Open Data Portal, made available via the portal by the Office for IT and eGovernment, under the Serbian Open Data Licence as shown on each dataset. The download date and address are on every row, and the changes are listed in `changes`. The data comes with no guarantee of accuracy or suitability. Not affiliated with or endorsed by the Government of Serbia, the portal or any retailer. We hold no agreement with, or permission from, any retailer, the portal or the Government of Serbia.

# Actor input Schema

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

Barcode finds the same product at every covered retailer; search matches words in the product name; category lists one of the 24 categories.

## `barcodes` (type: `array`):

Up to 500 13-digit barcodes; the GS1 check digit is verified.

## `query` (type: `string`):

Latin or Cyrillic; accents and case are ignored.

## `brand` (type: `string`):

Keeps only rows whose brand is exactly this name, in any mode; accents and case are ignored. Empty keeps every brand.

## `category` (type: `string`):

A category number from 1 to 24, or its name.

## `listType` (type: `string`):

The current list, or the snapshot each retailer publishes on the 1st of the month.

## `retailers` (type: `array`):

Retailer keys from the covered list; empty means every covered retailer (up to 15 retailerFile events, even when nothing matches). Name the ones you need to pay for fewer.

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

The most rows returned in search and category modes (1 to 10,000); barcode mode returns every match. Each row is one row event.

## Actor input object example

```json
{
  "mode": "search",
  "query": "mleko",
  "listType": "current",
  "maxItems": 10
}
```

# Actor output Schema

## `rows` (type: `string`):

No description

## `runSummary` (type: `string`):

No description

# 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",
    "query": "mleko",
    "maxItems": 10
};

// Run the Actor and wait for it to finish
const run = await client.actor("yappman/serbia-grocery-prices").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",
    "query": "mleko",
    "maxItems": 10,
}

# Run the Actor and wait for it to finish
run = client.actor("yappman/serbia-grocery-prices").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",
  "query": "mleko",
  "maxItems": 10
}' |
apify call yappman/serbia-grocery-prices --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,yappman/serbia-grocery-prices"
        }
    }
}
```

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/ykW9Uu92CsDgGjbu3/builds/jvvyHdIzLzyKVEHrv/openapi.json
