illy APIilly.com ↗
Access illy.com product data via 10 endpoints. Retrieve coffee listings, machine details, availability, customer reviews, Q&A, and current promotions.
What is the illy API?
The illy.com API provides 10 endpoints covering the full illy product catalog — coffee, machines, gifts, and accessories. Use get_product_details to pull SKU, price, description, images, currency, and schema.org availability for any product, or get_product_reviews to retrieve PowerReviews rollup data including average rating and individual review text. Category filtering, keyword search, and pagination are supported across the core listing endpoints.
curl -X GET 'https://api.parse.bot/scraper/814611c7-b1c4-492d-8901-27443f9b4f73/list_all_coffee_products?sz=12&start=0' \ -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 illy-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: illy Coffee SDK — browse products by category, search, check availability, read reviews."""
from parse_apis.illy_coffee_api import Illy, CoffeeCategory, ProductNotFound
client = Illy()
# Browse whole bean coffee using the category enum.
for product in client.products.by_category(category=CoffeeCategory.WHOLE_BEAN, limit=3):
print(product.name, product.price, product.flavor_intensity)
# Search for a specific coffee by keyword, take the first result.
result = client.products.search(query="intenso", limit=1).first()
if result:
print(result.name, result.price)
# Drill into reviews for this product via sub-resource.
for review in result.reviews.list(limit=2):
print(review.ugc_id, review.details, review.metrics)
# Check Q&A entries for the same product.
for question in result.questions.list(limit=2):
print(question.ugc_id, question.details, question.answer_count)
# Check product availability.
avail = client.availabilities.check(url="/en-us/coffee/whole-bean-coffee/whole-bean-classico-coffee-medium-roast/8841ST.html")
print(avail.name, avail.status, avail.price)
# Typed error handling — catch ProductNotFound on a bad product lookup.
try:
bad = client.product(id="NONEXISTENT999")
for review in bad.reviews.list(limit=1):
print(review.ugc_id)
except ProductNotFound as exc:
print(f"Product not found: {exc}")
# Browse current promotions.
for promo in client.promotions.list(limit=3):
print(promo.title, promo.description)
print("exercised: products.by_category / products.search / reviews.list / questions.list / availabilities.check / promotions.list")
Retrieve all coffee products from illy.com with pagination support. Returns product listings including name, price, thumbnail, badge, and flavor intensity. The full catalog has 100+ products; use start/sz to paginate through them.
| Param | Type | Description |
|---|---|---|
| sz | integer | Number of products per page. |
| start | integer | Offset for pagination. |
{
"type": "object",
"fields": {
"sz": "integer page size used",
"start": "integer current pagination offset",
"products": "array of product objects with id, name, url, price, thumbnail, badge, flavor_intensity",
"total_count": "integer total number of products available"
},
"sample": {
"data": {
"sz": 12,
"start": 0,
"products": [
{
"id": "8841ST",
"url": "https://www.illy.com/en-us/coffee/whole-bean-coffee/whole-bean-classico-coffee-medium-roast/8841ST.html",
"name": "Whole Bean Coffee Classico - Medium Roast",
"badge": "BEST SELLER",
"price": "$17.29",
"thumbnail": "https://www.illy.com/dw/image/v2/BBDD_PRD/on/demandware.static/-/Sites-masterCatalog_illycaffe/default/dwdaf207d6/products/sfra/coffee/Medium2x/8841ST_Medium_2x_01.png?q=75",
"flavor_intensity": "5/9"
}
],
"total_count": 116
},
"status": "success"
}
}About the illy API
Product Listings and Search
list_all_coffee_products returns paginated coffee listings with fields including id, name, url, price, thumbnail, badge, and flavor_intensity. Use the sz and start parameters to page through results. list_coffee_by_category accepts a category slug — verified values include whole-bean-coffee and iperespresso-espresso-capsules — and returns the same product object shape. search_products accepts a query string and optional sz/start pagination params, returning matching products across all categories.
Product Detail and Availability
get_product_details takes a URL path beginning with /en-us/ and returns a detailed product record: sku, name, description, price, currency, availability (as a schema.org URL), images (array), and flavor_intensity expressed as a fraction like 5/9. check_product_availability hits the same URL parameter but returns a lightweight response with just sku, name, price, and status — either in_stock or out_of_stock — making it efficient for bulk availability checks without fetching the full detail payload.
Reviews, Q&A, and Promotions
get_product_reviews accepts a product_id (the id field from any listing endpoint, e.g. 8841ST) and returns a rollup object with average_rating, rating_count, and review_count, plus an array of individual reviews each containing ugc_id, headline, comment body, reviewer nickname, and numeric rating. get_product_qa returns structured Q&A entries for the same product IDs, with each result including question text, answerer nickname, and an answer_count. get_promotions needs no inputs and returns current offers from the illy offers page: title, description, link, link_text, and section_label.
Machines and Accessories
list_coffee_machines and list_gifts_and_accessories each support sz and start pagination and return product arrays with id, name, url, price, and thumbnail. Machine listings do not include flavor_intensity, which is only present on coffee product objects.
The illy API is a managed, monitored endpoint for illy.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when illy.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 illy.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?+
- Monitor illy coffee product prices and availability across SKUs for price-tracking dashboards.
- Aggregate customer review ratings from
get_product_reviewsto compare illy blends by average score. - Build a catalog browser filtering coffee by category slug using
list_coffee_by_category. - Check
check_product_availabilityfor a list of SKUs to alert when out-of-stock items return to inventory. - Pull current promotions via
get_promotionsto surface illy deals in a comparison or cashback app. - Retrieve product Q&A with
get_product_qato populate a pre-purchase FAQ widget for illy products. - Extract flavor intensity ratings from
list_all_coffee_productsto build a taste-profile recommendation tool.
| 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 illy have an official public developer API?+
What does `get_product_reviews` return beyond the star rating?+
get_product_reviews returns a rollup object with average_rating, rating_count, and review_count, plus a paging object. Individual reviews each include ugc_id, a details object with comments, headline, and nickname, and a metrics object containing the numeric rating. The answered_questions count is also included in the rollup.Which product categories are supported in `list_coffee_by_category`?+
whole-bean-coffee and iperespresso-espresso-capsules. Other slugs that exist on illy.com may work but are not formally validated by the endpoint spec. Machines and accessories have their own dedicated endpoints (list_coffee_machines and list_gifts_and_accessories) rather than using a category param.Does the API cover subscription or auto-ship options available on illy.com?+
Is product data limited to the US storefront?+
/en-us/ prefix and prices are returned in USD. Other regional storefronts (e.g. UK, DE, IT) are not covered by the current endpoints. You can fork this API on Parse and revise it to point at a different regional path if you need non-US catalog data.