ScreenshotNeo

BlogHow-to

How to Scrape Ceneo Product Pages

Learn the compliant way to collect Ceneo product data with its APIs, plus a careful fallback workflow for inspecting product HTML.

By the ScreenshotNeo team30 September 20269 min read

How to Scrape Ceneo Product Pages

Direct answer: use Ceneo’s official API when you need product or category data. Publishers can apply for the Ceneo Partner Program API, which uses OAuth 2.0 client credentials and exposes product search and category resources. Shops and manufacturers should evaluate Ceneo’s Business API for competitor offers and offer operations. If you still need to inspect product HTML, build a low-rate collector that respects the current Ceneo terms, robots directives, and applicable law. Do not assume that page selectors, prices, availability, or markup are permanent.

This guide shows both routes. The API route is more stable and gives documented fields such as product name, price range, shop count, rating, review count, manufacturer, product URL, and thumbnails. The HTML route is a fallback for fields that an authorized API does not provide, and it requires stronger monitoring and compliance controls.

1. Choose the right Ceneo access route

Need Recommended route What to expect
Publishers directing traffic to Ceneo Partner Program API Program access, OAuth 2.0 client credentials, product and category data, affiliate attribution requirements.
Shops or manufacturers Business API Popular products, competitor offer analysis, offer updates and listing operations; commercial terms must be verified with Ceneo.
Visual archive or a field absent from an API Careful HTML inspection Markup can change without notice. Check terms and robots.txt for the exact host and path before collecting.

The PartnerService documentation says non-token query results are cached for 15 minutes, while warning that the cache duration may change. A documented operation can therefore be fresh enough for discovery without being a guaranteed real-time feed. The Business API page lists starting prices such as 500 zł per month for some popular-product and offer-update methods and 800 zł per month for competitor analysis; treat those as page-listed starting prices, not a quote.

A resilient workflow keeps API records, timestamps, and visual evidence as separate artifacts.
A resilient workflow keeps API records, timestamps, and visual evidence as separate artifacts.

2. Partner API prerequisites

  1. Have a functioning publisher website. Ceneo says this is required when seeking a test API key.
  2. Join or obtain access to the Ceneo Affiliate Program. The Partner API is available only to Affiliate Program users.
  3. Create OAuth client credentials and request a bearer token using the client-credentials flow.
  4. Store the token securely and renew it after expiry.
  5. Append the Partner ID from your affiliate account when constructing attributed product links. API product URLs do not include that ID.

Category records include an IsRestricted flag. Restricted categories are excluded from normal affiliate use; do not silently treat them as eligible inventory. The service may impose quantitative limits and can return HTTP 403 when limits or authorization rules are violated.

3. Obtain an OAuth token

The exact token endpoint and client credentials are supplied with your Ceneo partner account. Keep the endpoint in configuration rather than hard-coding it in application logic. The following Python pattern shows the required client-credentials shape; replace the placeholder endpoint with the one in your account documentation.

import os
import requests

TOKEN_URL = os.environ["CENEO_TOKEN_URL"]
CLIENT_ID = os.environ["CENEO_CLIENT_ID"]
CLIENT_SECRET = os.environ["CENEO_CLIENT_SECRET"]

response = requests.post(
    TOKEN_URL,
    data={"grant_type": "client_credentials"},
    auth=(CLIENT_ID, CLIENT_SECRET),
    timeout=30,
)
response.raise_for_status()
token = response.json()["access_token"]
print(token)

Never commit the client secret or bearer token. Cache the token in memory until its expires_in value, then request a new one. If a request returns 401, renew once and retry; repeated 401 responses should stop the job and alert an operator.

4. Search products with the Partner API

The documented GetProducts operation supports a product-name query and optional category, page size, page index, minimum price, maximum price, and filters for Ceneo’s “Buy on Ceneo” flow. Use small pages and persist the last successful page so a restart does not duplicate an entire run.

import os
import requests

API_URL = os.environ["CENEO_PRODUCTS_URL"]
token = os.environ["CENEO_ACCESS_TOKEN"]

params = {
    "search": "laptop",
    "PageSize": 50,
    "PageIndex": 0,
    "MinPrice": 1000,
    "MaxPrice": 6000,
    # Add the documented category and Buy-on-Ceneo filters when needed.
}

r = requests.get(
    API_URL,
    params=params,
    headers={"Authorization": f"Bearer {token}"},
    timeout=30,
)
if r.status_code == 401:
    raise RuntimeError("Token expired; renew it and retry once")
if r.status_code == 403:
    raise RuntimeError("Authorization, category, or call-limit restriction")
r.raise_for_status()

payload = r.json()
for product in payload.get("value", payload if isinstance(payload, list) else []):
    print({
        "id": product.get("Id"),
        "name": product.get("Name"),
        "lowest_price": product.get("LowestPrice"),
        "highest_price": product.get("HighestPrice"),
        "shops": product.get("ShopCount"),
        "rating": product.get("Rating"),
        "reviews": product.get("ReviewCount"),
        "manufacturer": product.get("Manufacturer"),
        "url": product.get("ProductUrl"),
    })

Field casing and envelope names should follow the schema delivered with your account. Preserve the raw response alongside normalized fields so a schema change can be diagnosed later.

5. Complete API examples in cURL, Python, and Node.js

cURL

curl --fail --silent --show-error \
  -H "Authorization: Bearer $CENEO_ACCESS_TOKEN" \
  --get "$CENEO_PRODUCTS_URL" \
  --data-urlencode "search=coffee maker" \
  --data-urlencode "PageSize=50" \
  --data-urlencode "PageIndex=0"

Python

import os
import requests

params = {"search": "coffee maker", "PageSize": 50, "PageIndex": 0}
r = requests.get(
    os.environ["CENEO_PRODUCTS_URL"],
    params=params,
    headers={"Authorization": f"Bearer {os.environ['CENEO_ACCESS_TOKEN']}"},
    timeout=30,
)
r.raise_for_status()
print(r.json())

Node.js

const endpoint = new URL(process.env.CENEO_PRODUCTS_URL);
endpoint.searchParams.set('search', 'coffee maker');
endpoint.searchParams.set('PageSize', '50');
endpoint.searchParams.set('PageIndex', '0');

const res = await fetch(endpoint, {
  headers: { Authorization: `Bearer ${process.env.CENEO_ACCESS_TOKEN}` }
});
if (!res.ok) throw new Error(`Ceneo API returned ${res.status}`);
console.log(await res.json());

For production, add an exponential backoff for transient 5xx responses, honor any documented call limits, and make retries idempotent. Do not retry a 400 caused by malformed filters or a 403 caused by eligibility or quota rules without changing the request or account state.

6. Pagination, normalization, and storage

  1. Choose a page size accepted by the API and record the requested page index.
  2. Normalize money into a decimal plus currency; retain the original value for auditability.
  3. Use Ceneo’s product ID as the primary key. Treat the product URL as an attribute, not an identifier.
  4. Store retrieval time and the API cache window in your record.
  5. Upsert each page in a transaction, then checkpoint the page number.
  6. Deduplicate by product ID when combining multiple searches.

Ratings, review counts, shop counts, and popularity indicators can change. Keep historical snapshots if you are calculating trends, and label them with collection timestamps rather than presenting them as current indefinitely.

7. HTML collection fallback

Use HTML only when you have a documented, permitted reason. Before running a crawler, review the current Ceneo terms, the exact host’s robots.txt, and legal requirements for your jurisdiction. The available research does not establish blanket permission or blanket prohibition for every Ceneo product page. A rule quoted for the Ceneo Magazine subsite cannot automatically be generalized to the product catalog.

Do not bypass CAPTCHA, bot checks, authentication, rate limits, or other access controls. Start with a single URL, a low request rate, a descriptive user agent, bounded concurrency, and a kill switch. Save the response status and timestamp for every attempt.

Minimal Python collector

from urllib.parse import urlparse
import time
import requests
from bs4 import BeautifulSoup

URL = "https://www.ceneo.pl/123456"
headers = {"User-Agent": "ProductResearchBot/1.0 contact@example.com"}

host = urlparse(URL).hostname
if host not in {"www.ceneo.pl", "ceneo.pl"}:
    raise ValueError("Unexpected host")

r = requests.get(URL, headers=headers, timeout=30)
r.raise_for_status()
soup = BeautifulSoup(r.text, "html.parser")

# Selectors are examples only; inspect the current page and terms before use.
title = soup.select_one("h1")
print({
    "url": URL,
    "title": title.get_text(" ", strip=True) if title else None,
    "status": r.status_code,
})
time.sleep(2)

Expect selectors to break. Prefer structured data embedded in the page when its use is permitted, validate every extracted value, and emit a null value rather than guessing when a field is absent. Never infer availability from a CSS class that has not been validated against the current page.

8. Reliability and performance checklist

  • Rate: use bounded concurrency and a delay between requests; API pagination is usually cheaper and more reliable than page scraping.
  • Timeouts: set connect and read timeouts separately where your client supports them.
  • Retries: retry transient network failures and 5xx responses with jitter; do not blindly retry 401, 403, or validation errors.
  • Freshness: account for the Partner API’s documented 15-minute cache and the Business API method-specific freshness claims.
  • Monitoring: track status codes, empty result rates, schema validation failures, latency, and token-renewal failures.
  • Change detection: keep fixtures from approved pages and alert when required fields disappear.
  • Cost: API commercial terms vary by route; verify current Business API pricing. HTML collection adds infrastructure, maintenance, and compliance overhead.

9. Troubleshooting common errors

Symptom Likely cause Fix
401 Unauthorized Expired or malformed bearer token. Request a fresh token, verify the Authorization header, and retry once.
403 Forbidden Account eligibility, restricted category, or call limit. Check Affiliate Program access, remove restricted categories, and review quota guidance.
Empty search results Wrong parameter name, page index, or overly narrow filters. Test the smallest documented query, then add filters one at a time.
Prices differ from a page API cache, changing offers, or different price fields. Record retrieval time, distinguish range and basket price, and avoid claiming real-time data.
HTML parser returns nulls Markup or selector changed, consent wall, or bot response. Save a redacted fixture, inspect response status, update selectors only after reviewing terms, and stop on challenge pages.
429 or repeated timeouts Too much concurrency or an infrastructure problem. Reduce concurrency, add backoff, honor published limits, and resume from a checkpoint.

10. Capture a reproducible visual record

If your purpose is to preserve how a product page looked at collection time, store the URL, timestamp, response metadata, and a screenshot separately from structured data. A screenshot does not prove that a price was legally collectible or that the value was available to every visitor; it is an audit artifact.

Consent and overlay handling should happen before a screenshot is stored.
Consent and overlay handling should happen before a screenshot is stored.

Or skip the browser setup

When you need a clean visual capture of a Ceneo page, ScreenshotNeo provides a single screenshot API request. It accepts consent banners before capture and removes more than 60 known consent platforms, newsletter popups, and chat widgets. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers identify the page verdict and billing result. An MCP server provides take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients. See the ScreenshotNeo API documentation for all options.

cURL

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://www.ceneo.pl/123456 -o ceneo-product.webp

Python

import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://www.ceneo.pl/123456"}, timeout=90)
r.raise_for_status()
open("ceneo-product.webp", "wb").write(r.content)

Node.js

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://www.ceneo.pl/123456' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`ScreenshotNeo returned ${res.status}`);
const fs = await import('node:fs/promises');
await fs.writeFile('ceneo-product.webp', Buffer.from(await res.arrayBuffer()));

ScreenshotNeo supports full-page capture, element selectors, dark mode, device presets, retina scale, PDF output, custom CSS and JavaScript, waits, request blocking, headers, cookies, user agents, timezone, geolocation, resizing, caching, signed links, asynchronous jobs, bulk capture, usage reporting, and an OpenAPI specification. Use those controls to make captures repeatable while keeping your Ceneo data collection within the permissions that apply to your project. Create a free ScreenshotNeo account for 1,000 screenshots a month with no card; paid plans start at $5 for 3,000.

FAQ

Is Ceneo HTML scraping allowed?

The supplied sources do not establish a universal yes or no. Check the current terms and robots directives for the exact host and path, and obtain legal advice for your use case.

Is the Partner API real time?

No guarantee should be implied. Its documentation describes a 15-minute cache for query results and says that duration may change.

Can I use restricted categories in the affiliate workflow?

The API exposes an IsRestricted flag, and restricted categories cannot be used in the Affiliate Program.

Append the Partner ID from your Affiliate Program account settings to the API product URL. Do not invent an ID.

Which API is for sellers?

Ceneo’s Business API is aimed at shops and manufacturers that need popular-product data, competitor offers, or offer updates.

Should screenshots replace structured data?

No. Use API fields for records and screenshots for visual evidence, debugging, or review workflows.