Soriana APIsoriana.com ↗
Access Soriana's online grocery catalog via API. Search products, retrieve prices in MXN, browse departments, fetch coupons, and check basket totals.
What is the Soriana API?
The Soriana API provides 5 endpoints for extracting product data, pricing, department taxonomy, and coupons from Soriana's online grocery store. Use search_products to query the catalog by keyword or category slug, get_product_details to pull brand, EAN barcode, and current MXN price for a single item, and get_basket_prices to check prices for multiple product IDs in one call. All prices are returned in Mexican pesos.
curl -X GET 'https://api.parse.bot/scraper/ad967404-4c0a-4e91-977a-35a311dc0737/search_products?limit=5&query=leche&start=0&category_id=despensa' \ -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 soriana-com-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: Soriana API — search products, browse departments, check coupons."""
from parse_apis.soriana_api import Soriana, ProductNotFound
client = Soriana()
# List all departments to discover browseable categories
for dept in client.departments.list(limit=5):
print(dept.name, dept.id)
# Search products by keyword — limit caps total items fetched
product = client.products.search(query="leche", limit=1).first()
if product:
print(product.name, product.sale_price, product.list_price)
# Browse coupons — each category carries nested coupon objects
for cat in client.couponcategories.list(limit=3):
print(cat.label, cat.quantity)
for coupon in cat.coupons[:2]:
print(coupon.callout_msg, coupon.end_date)
# Check basket prices for multiple products at once
try:
for bp in client.basketproducts.check_prices(product_ids='["11400966"]', limit=3):
print(bp.name, bp.price, bp.availability)
except ProductNotFound as exc:
print(f"Product gone: {exc.product_id}")
print("exercised: departments.list / products.search / couponcategories.list / basketproducts.check_prices")
Search for products by keyword or category ID. Returns a paginated list of products with prices and images. Pagination is offset-based via the start parameter (multiples of limit). At least one of query or category_id should be provided for meaningful results.
| Param | Type | Description |
|---|---|---|
| limit | integer | Max results to return per page. |
| query | string | Search keyword (e.g. 'leche', 'coca cola'). At least one of query or category_id should be provided. |
| start | integer | Offset for pagination. Use multiples of limit to paginate (0, 25, 50, ...). |
| category_id | string | Category slug to filter by (e.g. 'lacteos-y-huevo', 'despensa'). Use get_departments to discover valid values. |
{
"type": "object",
"fields": {
"count": "integer number of products returned in this page",
"items": "array of product objects with id, name, url, sale_price, list_price, and image",
"limit": "integer max results requested",
"total": "integer total number of matching products"
},
"sample": {
"data": {
"count": 1,
"items": [
{
"id": "11400966",
"url": "https://www.soriana.com/leche-uht-lala-deslactosada-1-litro-6-piezas/11400966.html",
"name": "Leche UHT Lala Deslactosada 1 Litro 6 Piezas",
"image": "https://www.soriana.com/dw/image/v2/BGBD_PRD/on/demandware.static/-/Sites-soriana-grocery-master-catalog/default/dwdf6ddcaa/images/product/7501020565997_A.jpg?sw=473&sh=473&sm=fit",
"list_price": 215,
"sale_price": 186
}
],
"limit": 5,
"total": 258
},
"status": "success"
}
}About the Soriana API
Catalog Search and Product Details
The search_products endpoint accepts a query string (e.g. 'leche', 'coca cola') or a category_id slug (e.g. 'lacteos-y-huevo', 'despensa'), or both. Results are paginated via start and limit parameters — pass multiples of limit to walk through pages. Each item in the items array includes id, name, url, sale_price, list_price, and image. The total field tells you how many matching products exist across all pages.
The get_product_details endpoint takes a single product_id (available from search results) and returns a richer record: ean (13-digit barcode), brand, description, price in MXN, list_price, and a canonical url. The currency field is always MXN.
Departments, Coupons, and Basket Prices
get_departments requires no inputs and returns an array of top-level department objects, each with a human-readable name and a id slug you can pass directly as category_id in search_products. This is the correct way to discover valid category slugs.
get_coupons returns active promotions organized into couponCategories, each containing a label, a quantity, and a coupons array with codes, validity dates, and discount details. An optional postal_code parameter is accepted but currently returns the same national coupon set regardless of value. get_basket_prices accepts a JSON-encoded array of product IDs and returns price, list_price, promotionalPrice, currency, and availability for each — useful for validating prices across a saved list of items.
The Soriana API is a managed, monitored endpoint for soriana.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when soriana.com 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 soriana.com 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?+
- Build a price-tracking tool that monitors MXN prices for specific Soriana SKUs over time using get_product_details
- Compare sale_price vs list_price across a category to identify discounted items via search_products with a category_id
- Aggregate active coupon codes and their validity dates from get_coupons for a deal-alert newsletter
- Validate and reprice a saved shopping list by submitting multiple product IDs to get_basket_prices
- Populate a department navigation tree for a grocery companion app using get_departments slugs
- Look up EAN barcodes from Soriana's catalog to cross-reference products across retailers via get_product_details
- Paginate through an entire department's catalog using search_products with start and limit to build a local product index
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does Soriana have an official public developer API?+
How does pagination work in search_products?+
start to 0 for the first page, then increment by the value of limit for each subsequent page (e.g. 0, 25, 50). The total field in the response tells you the full count of matching products so you can calculate how many pages exist.Does get_coupons return location-specific offers?+
postal_code parameter, but currently returns the same national coupon set regardless of the postal code provided. Location-specific offer filtering is not currently differentiated in the response.Does the API return product reviews or star ratings?+
Can I retrieve products within a subcategory, not just a top-level department?+
get_departments endpoint returns top-level department slugs. Passing those slugs as category_id in search_products filters at the department level. Subcategory-level IDs are not exposed by get_departments. You can fork this API on Parse and revise it to add a subcategory listing endpoint.