Onliner APIOnliner.by ↗
Search the Onliner.by catalog, fetch product details, and retrieve live shop offers with prices in BYN via 3 structured API endpoints.
What is the Onliner API?
The Onliner.by API provides 3 endpoints to query the Onliner.by product catalog, one of Belarus's largest online shopping indexes. Use search_products to find products by keyword or price range, get_product to retrieve specs, ratings, discount data, and video links for a single item, and get_product_offers to pull every current shop offer—including price, delivery details, and shop ratings—for that product.
curl -X GET 'https://api.parse.bot/scraper/bb38720f-6b11-4166-ac3c-6744c20e15ea/search_products?query=iphone' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace onliner-by-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Walkthrough: Onliner.by catalog SDK — search, detail, and offers."""
from parse_apis.onliner_by_api import Onliner, ProductSort, InputNotFound
client = Onliner()
# Search for products sorted by price, capped at 5 results.
for item in client.product_summaries.search(query="iphone", sort=ProductSort.PRICE_ASC, limit=5):
print(item.name, item.price_min.amount if item.price_min else "no price", item.offers_count)
# Drill into the first search hit's full detail via typed navigation.
summary = client.product_summaries.search(query="samsung galaxy", limit=1).first()
if summary is not None:
product = summary.details()
print(product.name, product.description)
print("rating:", product.rating, "reviews:", product.reviews_count)
if product.used_price_min:
print("used from:", product.used_price_min.amount, product.used_price_min.currency)
# List shop offers for that same product, capped at 3.
for offer in client.offers.list(product_key=product.key, limit=3):
print(offer.shop_name, offer.price.amount, offer.price.currency, offer.shipping_term)
# Point lookup by a known key, with error handling.
try:
detail = client.products.get(key="iphone17256bk")
print(detail.name, detail.manufacturer, detail.is_on_sale)
except InputNotFound:
print("product not found")
print("exercised: product_summaries.search / details / offers.list / products.get")
Full-text search over the whole Onliner catalog. Returns one page of product summaries (site page size is fixed at 10) with total match count and last page number; each product carries a key usable with get_product and get_product_offers. Prices are in BYN as reported by the site. Pages are 1-based; omitting page returns page 1, and a page past last_page returns an empty products list with the same total. Optional price_from/price_to bound the minimum offer price in BYN, and sort orders by price; when sort is omitted the site's relevance order is used. A query with no matches returns an empty products list and total 0.
| Param | Type | Description |
|---|---|---|
| page | integer | 1-based result page number. |
| sort | string | Ordering of results. Omitted = site relevance order. |
| queryrequired | string | Free-text search phrase (product name, model, brand). |
| price_to | integer | Upper bound on the product's minimum offer price, in BYN. |
| price_from | integer | Lower bound on the product's minimum offer price, in BYN. |
{
"type": "object",
"fields": {
"page": "current 1-based page number",
"total": "total number of matching products across all pages",
"products": "array of product summaries: id, key (use with get_product/get_product_offers), name, name_prefix, category_key, category_name, manufacturer, status, description, image, url, rating (0-50 scale), reviews_count, price_min/price_max ({amount, currency}, null when no offers), offers_count",
"last_page": "number of the last page available",
"page_size": "products per page (10)"
},
"sample": {
"data": {
"page": 1,
"total": 16331,
"products": [
{
"id": 4943088,
"key": "iphone17256bk",
"url": "https://catalog.onliner.by/mobile/apple/iphone17256bk",
"name": "Apple iPhone 17 256GB (черный)",
"image": "https://imgproxy.onliner.by/c6GWBOyu5LFyXK5cu7LEJ04bk7-7iWgsY3Stg3tIB6I/w:170/h:250/z:2/f:jpg/aHR0cHM6Ly9jb250/ZW50Lm9ubGluZXIu/YnkvY2F0YWxvZy9k/ZXZpY2UvMjAyNS9l/MDUxMWU5ZWFhOTgz/MmUyMTkwZjJmMzY0/MTc1MmUyZi5qcGc",
"rating": 45,
"status": "active",
"price_max": {
"amount": 3890.89,
"currency": "BYN"
},
"price_min": {
"amount": 2970,
"currency": "BYN"
},
"description": "iOS, экран 6.3\" OLED (1206x2622) 120 Гц, Apple A19 (5 ядер GPU), ОЗУ 8 ГБ, память 256 ГБ, камера 48 Мп, аккумулятор 3692 мАч Li-ion, моноблок, влагозащита IP68",
"name_prefix": "Телефон",
"category_key": "mobile",
"manufacturer": "Apple",
"offers_count": 40,
"category_name": "Мобильные телефоны",
"reviews_count": 39
}
],
"last_page": 100,
"page_size": 10
},
"status": "success"
}
}About the Onliner API
Searching the Catalog
The search_products endpoint accepts a free-text query and returns up to 10 product summaries per page. You can narrow results with price_from and price_to (both in BYN), choose a sort order, and paginate using the 1-based page parameter. Every response includes total match count and last_page so you can walk the full result set. Each product summary carries an id, a key (used to call the other two endpoints), name, name_prefix, category_key, category_name, and manufacturer (man).
Product Details
get_product takes a single product_key from the search results and returns an expanded record. Fields beyond the search summary include a url to the product page, a header image URL, a rating on a 0–50 scale, status, an array of videos, discount percentage, and editorial stickers. The endpoint completes in one round trip and covers the same key space as the search index.
Shop Offers and Pricing
get_product_offers returns every offer currently listed for a product—unpaginated—keyed by the same product_key. Each entry in the offers array includes offer_id, shop_id, shop_name, shop_url, shop_rating (0–5 scale), shop_reviews_count, shop_town, and a price object with amount and currency. The response also surfaces min_price (the lowest current offer or null) and offers_count as reported by the site. This makes it straightforward to build price-comparison views or track the cheapest seller for any given product.
The Onliner API is a managed, monitored endpoint for Onliner.by — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when Onliner.by changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official Onliner.by API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Compare current BYN prices across shops for a specific electronics model using get_product_offers
- Monitor discount percentages on catalog items by polling get_product for the discount field
- Build a product search widget filtered by price range using price_from and price_to in search_products
- Rank shops by rating or review count using shop_rating and shop_reviews_count from get_product_offers
- Aggregate category-level product counts by collecting category_key and category_name from search results
- Track minimum offer price changes over time using the min_price field from get_product_offers
- Identify products with editorial stickers or sale flags using the stickers and discount fields in get_product
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 200 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
| Team | $300/mo | 20,000 | 300 req/min |
| Company | $1,000/mo | 100,000 | 500 req/min |
Each endpoint has a fixed posted price per successful call — most fall between 1 and 10 credits — shown on this API's page before you run it. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.