BİM API & Scraper
The BİM API turns bim.com.tr, Turkey's largest hard-discount grocery chain, into clean JSON in six actions.
🤖 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.
BİM has no online shop, so everything it sells to the public is announced in a dated leaflet: the Aktüel Ürünler special-buy sheet tied to a single day, and the İndirim price-cut sheet that runs across a date range. leaflets returns every sheet BİM is publishing right now, including the upcoming ones it posts days ahead, each with its key, its family, BİM's own date label, the dates it covers and whether it is on shelf today. leaflet/products returns one sheet's products: title, brand, campaign price in lira, the struck price and BİM's own discount percent where BİM prints them, package size, feature bullets, interest-free instalments, image and product link. product/detail opens a single product's page for its fuller feature list and every image. posters returns the printed sheets as page images, across the Aktüel, İndirim and Kırtasiye tabs. stores is BİM's own store finder: 81 provinces, their districts, and each branch's name and address. brands lists BİM's eleven own-label categories and the 147 brands inside them. In a live run on 2026-09-24 the API read 636 products across all 12 leaflets BİM had live, and the sheet returned matched the sheet requested on 12 of 12. Prices are Turkish lira and national. No BİM account, one ReefAPI key and the standard { ok, data, meta, error } envelope.
What a BİM leaflet prints, and what it does not
The two leaflet families do not publish the same fields, and the difference belongs to BİM rather than to the parser. Measured on 2026-09-24 across the 12 leaflets BİM had live and the 636 products on them.
| Field | Measured 2026-09-24 | What comes back |
|---|---|---|
| price | 636 of 636 | The campaign price in TRY. A price BİM renders as 0,00 is dropped rather than published as zero. |
| price_before_discount | 0 of 584 Aktüel products · 52 of 52 İndirim products | The struck price where BİM prints one. Null on an Aktüel sheet, because BİM prints none there. |
| discount_percent | the same split as the struck price | BİM's own printed figure, kept verbatim. It truncates: 199,00 down to 189,00 is printed as 5 per cent where the arithmetic is 5.03. |
| discount_percent_calculated | filled wherever a struck price exists | The exact arithmetic, in its own field, so neither number hides the other. |
| brand | 562 of 636 | Null when BİM left its own brand field empty. The brand is often inside the title, and it is not split out of the title. |
| starts_on / ends_on | every label BİM prints carries a day and a month, never a year | Dates are completed and flagged year_inferred, with BİM's own date_label kept verbatim beside them. |
| stock, ratings, reviews, barcodes | 0 on every surface | BİM publishes none of these. They are absent, not estimated. |
BİM keeps no archive. Once a sheet drops off its site it is gone, and a key BİM no longer lists comes back as NOT_FOUND rather than the current week's products under an old label. The store finder prints a branch name and street address only, with no coordinates, telephone number or opening hours.
Real request and response JSON
Captured from the indexed primary action, leaflets, on .
{
"method": "POST",
"url": "https://api.reefapi.com/bim/v1/leaflets",
"headers": {
"x-api-key": "$REEF_KEY",
"content-type": "application/json"
},
"body": {
"type": "all"
}
}{
"ok": true,
"meta": {
"api": "bim",
"endpoint": "leaflets",
"mode": "live",
"latency_ms": 513.9,
"record_count": 13,
"bytes": 86647,
"cache_hit": false,
"charged_credits": 0,
"version": "0.1.0"
},
"data": {
"leaflets": [
{
"leaflet_key": 1658,
"type": "aktuel",
"date_label": "15 Eylül Salı",
"starts_on": "2026-09-15",
"ends_on": "2026-09-15",
"weekday": "salı",
"is_current": false,
"days_from_today": -11,
"status": "past",
"url": "https://www.bim.com.tr/?Bim_AktuelTarihKey=1658",
"year_inferred": true
},
{
"leaflet_key": 1659,
"type": "aktuel",
"date_label": "16 Eylül Çarşamba",
"starts_on": "2026-09-16",
"ends_on": "2026-09-16",
"weekday": "çarşamba",
"is_current": false,
"days_from_today": -10,
"status": "past",
"url": "https://www.bim.com.tr/?Bim_AktuelTarihKey=1659",
"year_inferred": true
},
{
"leaflet_key": 1660,
"type": "aktuel",
"date_label": "18 Eylül Cuma",
"starts_on": "2026-09-18",
"ends_on": "2026-09-18",
"weekday": "cuma",
"is_current": false,
"days_from_today": -8,
"status": "past",
"url": "https://www.bim.com.tr/?Bim_AktuelTarihKey=1660",
"year_inferred": true
}
],
"count": 13,
"current_leaflet_key": 1666,
"today": "2026-09-26",
"types_present": [
"aktuel",
"indirim"
],
"type": "all"
}
}What the BİM API does
| Action | Description | Concrete use case | Key params |
|---|---|---|---|
| leaflets | Every leaflet BİM is publishing right now — the recent ones, the one on shelf today, and the UPCOMING ones (BİM puts the next week's sheets up days early). Each entry carries the leaflet key you pass to `leaflet/products`, its family (`aktuel` special-buy sheet or `indirim` price-cut sheet), BİM's own date label, the start and end dates, and whether it is current, upcoming or past. This is the only legitimate source of a leaflet key: BİM keeps no archive. | Pricing teams call leaflets to get every leaflet BİM is publishing right now. | type, max_rotations |
| leaflet/products | Every product on one BİM leaflet: title, brand, campaign price in TRY, the struck price and BİM's discount percent where BİM prints them, package size, feature bullets, interest-free instalments, image and product URL. Pick the leaflet by `leaflet_key`, by `date` (future dates included), or leave both out for the sheet on shelf today. An unknown key is rejected, never answered with the wrong week. | Marketplace operators call leaflet/products to get every product on one BİM leaflet. | leaflet_key, date, type, max_rotations |
| product/detail | One BİM leaflet product by its URL or slug: title, price, struck price and discount where BİM prints them, package size, the feature list (the product page often carries more bullets than the leaflet tile), every image, instalments — plus which leaflet it belongs to and its brand, read from that leaflet. A product whose leaflet has expired returns NOT_FOUND rather than BİM's silent homepage. | Catalog enrichment teams call product/detail to get one BİM leaflet product by its URL or slug. | url, slug, include_brand, max_rotations |
| posters | BİM's leaflet sheets as images — the scanned Aktüel, İndirim and Kırtasiye posters, each with BİM's date label, a cover image, every page image in order and BİM's own download link. This is the printed sheet; `leaflet/products` is the same campaign as structured rows. | Retail analysts call posters to get bİM's leaflet sheets as images. | type, max_rotations |
| stores | BİM's public store finder. With no parameters it returns the 81 provinces; with a `city` it returns that province's districts; with both it returns the stores — branch name and street address. Works by name or by BİM's own numeric ids. | Pricing teams call stores to get bİM's public store finder. | city, county, max_rotations |
| brands | BİM's own-label brands. With no parameters it returns BİM's eleven product categories; with a `category` it returns that category's own-label brand names and logos. BİM publishes brand names and logos here only — there are no products or prices on this surface. | Marketplace operators call brands to get bİM's own-label brands. | category, max_rotations |
Call leaflets from your stack
curl -X POST https://api.reefapi.com/bim/v1/leaflets \
-H "x-api-key: $REEF_KEY" \
-H "content-type: application/json" \
-d '{"type":"all"}'import requests
r = requests.post(
"https://api.reefapi.com/bim/v1/leaflets",
headers={"x-api-key": REEF_KEY},
json={
"type": "all"
},
)
print(r.json()["data"])const res = await fetch("https://api.reefapi.com/bim/v1/leaflets", {
method: "POST",
headers: {
"x-api-key": process.env.REEF_KEY,
"content-type": "application/json",
},
body: JSON.stringify({
"type": "all"
}),
});
const { ok, data, meta, error } = await res.json();Ask your MCP-connected assistant: call reefapi.bim.leaflets with {"type":"all"}.Who uses this API and why
- Deals and discount sites publish BİM's sheet the moment it goes up, using the upcoming leaflets to have the page ready before the campaign opens.
- Price trackers compare BİM against the other Turkish discounters week over week from the same struck price and discount fields.
- Retail and FMCG analysts follow promotion frequency, discount depth and category mix across both leaflet families.
- Shopping apps and subscriber channels push each new leaflet to their users, with the poster page images alongside the structured rows.
- Store locators and delivery-area tools read the 81 provinces, their districts and each branch's address from BİM's own finder.
Questions developers ask before integrating
Can I get next week's BİM leaflet before it starts?
Yes, once BİM has posted it. BİM puts the coming sheets up days ahead of the day they open, and leaflets returns them with status upcoming, their start date and the leaflet_key that leaflet/products takes. That is the whole point of the action: you can have the deals page written before the campaign opens.
Can I get an old BİM leaflet?
No, because BİM does not keep one. Its site publishes a rolling window and nothing behind it. Ask for a key that leaflets no longer lists and you get NOT_FOUND. That matters more than it sounds: BİM's own site answers a stale key with the current sheet, so a naive reader would store this week's prices under last week's date.
Why is the discount percent different from the one I calculate?
Because BİM rounds its own figure down and the API keeps both. 169,50 down to 129,00 is printed as 23 per cent where the arithmetic is 23.89, and 12 of 52 measured İndirim products differ from the arithmetic by more than 0.6 points. discount_percent is BİM's printed number, discount_percent_calculated is the exact one. Use whichever your product needs and know which you have.
Are BİM prices per store?
No. BİM's leaflet prices are national, so there is no per-store price and no basket. The stores action is a locator: it returns the 81 provinces, then a province's districts, then that district's branch names and addresses. A province on its own returns the district list rather than an empty success, because BİM's own finder needs a district before it will list shops.
Does it cover the İndirim sheets as well as Aktüel?
Both, and each is tagged. leaflets takes type with all, aktuel or indirim. leaflet/products takes aktuel or indirim, and picks a sheet by leaflet_key, by date, or by neither for the one on shelf today. On a day covered by two overlapping İndirim sheets, a date lookup takes the one whose start is nearest and the other stays reachable by its key.
Is there a BİM product search?
No, and no permanent catalogue to search. BİM's site has neither. The leaflet is the catalogue, so the pattern is to list a sheet and filter its rows yourself. leaflets costs nothing, which makes the check for a new sheet free.
What is the BİM API?
BİM API is a ReefAPI endpoint group for turkey's biggest discount grocer: the weekly aktüel and i̇ndirim leaflets with every product priced, plus the store finder. It returns live JSON through POST requests under /bim/v1.
Is the BİM API free to try?
Yes. ReefAPI starts with 1,000 free credits, no card required. BİM calls use the same shared credit balance as every other ReefAPI engine.
Do I need a BİM login or account?
No login to BİM 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 BİM data?
The page example is captured from a live leaflets call, and production requests fetch live data through ReefAPI rather than a static sample.
How many credits does the BİM API use?
BİM actions currently cost 1 credit per successful call. Failed or blocked calls are free. All APIs draw from one credit pool.
Can I call BİM from an AI assistant or MCP client?
Yes. Connect ReefAPI once through MCP and your assistant can call bim actions with the same key, credit pool and JSON envelope used by normal REST requests.
Is the BİM API a BİM scraper?
It is the managed alternative to a DIY BİM scraper. Instead of building and maintaining your own scraper — proxies, headless browsers, captcha and constant breakage — you call one ReefAPI endpoint and get the same turkey's biggest discount grocer: the weekly aktüel and i̇ndirim leaflets with every product priced, plus the store finder back as clean JSON.
Why does my BİM scraper keep getting blocked?
Most BİM scrapers break on anti-bot defenses, rate limits and IP bans that need rotating residential proxies and browser fingerprinting to clear. ReefAPI handles all of that for you — no proxies, no captchas, no maintenance — and returns live JSON. Blocked calls are free.