Com APIwellcome.com.hk ↗
Access Wellcome Hong Kong grocery data: search products, browse categories, get SKU details, and retrieve trending searches via a structured REST API.
What is the Com API?
The Wellcome Hong Kong API provides structured access to grocery product data across 5 endpoints, covering product search, category browsing, SKU-level detail, autocomplete suggestions, and trending searches. The search_products endpoint accepts both English and Chinese keywords and returns price, promotion price, image URLs, and filter facets per query. Prices are returned in HKD.
curl -X GET 'https://api.parse.bot/scraper/8e12dbe9-89fe-49fb-ad81-bee481931230/search_products?page=1&keyword=milk&sort_key=0&page_size=20&sort_rule=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 wellcome-com-hk-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: Wellcome HK grocery SDK — search, browse, detail drill-down."""
from parse_apis.wellcome_hong_kong_grocery_api import (
Wellcome, SortKey, SortDirection, ProductNotFound,
)
client = Wellcome()
# Discover what's trending right now on the platform.
for trend in client.popularsearches.list(limit=5):
print(trend.keyword, trend.rank)
# Search for milk products sorted by price ascending.
product = client.productsummaries.search(
keyword="milk", sort_key=SortKey.PRICE, sort_rule=SortDirection.ASCENDING, limit=1
).first()
# Drill into full detail from the summary.
if product:
detail = product.details()
print(detail.name, detail.price, detail.currency)
print("Brand:", detail.brand_name)
for promo in detail.promotions[:2]:
print(" Promo:", promo.promo_tag, promo.promo_slogan)
# Browse a category (Beverages) and inspect a few items.
for item in client.productsummaries.browse(category_id="100002", limit=3):
print(item.name, item.price, item.promotion_tag)
# Autocomplete suggestions for a prefix.
for suggestion in client.suggestions.search(keyword="choco", limit=5):
print(suggestion.keyword, suggestion.score)
# Typed error handling on a bad SKU lookup.
try:
client.products.get(sku_id="0000000000")
except ProductNotFound as exc:
print(f"Product not found: sku_id={exc.sku_id}")
print("exercised: popularsearches.list / productsummaries.search / product.details / productsummaries.browse / suggestions.search / products.get")
Full-text search over Wellcome's grocery catalog. Supports English and Chinese keywords. Returns paginated product summaries, total counts, and available filter facets (category, brand, origin). Sort by price or new arrivals; default sort is relevance. Each product summary exposes a sku_id for fetching full detail via get_product_detail.
| Param | Type | Description |
|---|---|---|
| page | integer | Page number (1-based) |
| keywordrequired | string | Search keyword (English or Chinese) |
| sort_key | integer | Sort field: 0=default/relevance, 1=price, 2=new arrivals |
| page_size | integer | Results per page |
| sort_rule | integer | Sort direction: 0=ascending, 1=descending |
{
"type": "object",
"fields": {
"page": "integer, current page number",
"filters": "array of filter groups with property_id, property_name, and options array",
"keyword": "string, echoed search keyword",
"products": "array of product summary objects with sku_id, name, price, promotion_price, image_url, etc.",
"page_size": "integer, results per page",
"total_count": "integer, total matching products",
"total_pages": "integer, total pages available"
},
"sample": {
"data": {
"page": 1,
"filters": [
{
"options": [
{
"name": "保鮮牛奶及奶粉",
"count": 82,
"property_id": "105681"
}
],
"property_id": "2",
"property_name": "分類"
}
],
"keyword": "milk",
"products": [
{
"name": "Meadows 常溫全脂奶 1LT",
"price": 25.5,
"rf_id": "763573",
"stock": 13800,
"sku_id": 101366351,
"status": "1",
"ware_id": "11335600",
"allow_cc": 1,
"brand_id": 28570,
"currency": "HKD",
"image_url": "https://img.rtacdn-os.com/20260513/55c873be-4bb2-34a0-89a3-8c610c671d11_480x480H",
"category_id": 22136,
"merchant_id": 2,
"promotion_tag": "3件$45",
"allow_delivery": 1,
"original_price": 25.5,
"promotion_price": 25.5
}
],
"page_size": 20,
"total_count": 747,
"total_pages": 38
},
"status": "success"
}
}About the Com API
Product Search and Discovery
The search_products endpoint accepts a keyword string in English or Traditional Chinese, with optional sort_key (0=default, 1=price, 2=new arrivals) and sort_rule (0=ascending, 1=descending) parameters. Responses include a products array with fields like sku_id, name, price, promotion_price, and image_url, alongside total_count, total_pages, and a filters array of grouped facets keyed by property_id and property_name. This makes it straightforward to replicate the core search experience or build price-comparison tooling.
Category Browsing
The browse_category endpoint takes a category_id (e.g., '100002' for Beverages) and returns paginated products with the same product shape as search results. The response also includes a subcategories array of nested objects containing category_id, category_name, image, and further recursive subcategories — allowing full traversal of the category tree without a separate catalog endpoint.
Product Detail and Identifiers
get_product_detail requires a sku_id obtained from either search_products or browse_category. The detail response includes brand_id, ware_id, item_num (barcode), an images array, sell status, and currency (always HKD). Prices in the detail endpoint are expressed in HKD as a float divided by 100 from cents, consistent with the value seen in listing results.
Trending and Autocomplete
popular_searches requires no inputs and returns a ranked list of currently trending keywords, each with a rank integer and a highlight flag. search_suggestions takes a keyword prefix and returns suggestions objects with keyword and score fields — useful for building typeahead interfaces or understanding how shoppers phrase queries on the platform.
The Com API is a managed, monitored endpoint for wellcome.com.hk — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when wellcome.com.hk 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 wellcome.com.hk 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?+
- Track price and promotion_price changes for specific SKUs over time to monitor Wellcome discount cycles.
- Build a bilingual grocery search interface using the keyword parameter's support for both English and Chinese input.
- Traverse the subcategories tree from browse_category to generate a full catalog map of Wellcome's product hierarchy.
- Feed popular_searches ranked keywords into trend analysis dashboards to spot seasonal demand shifts.
- Use search_suggestions scores to understand common shopper query patterns for SEO or UX research.
- Extract item_num barcodes from get_product_detail to cross-reference Wellcome SKUs with other retailer databases.
- Compare promotion_price versus price across categories to surface the deepest current discounts.
| 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 Wellcome Hong Kong have an official public developer API?+
What does browse_category return beyond a product list?+
products array and total_count, the response includes a subcategories field — a nested array of category objects each with category_id, category_name, and image. These subcategories are themselves nestable, so a single call to a top-level category returns the full branch of its hierarchy alongside the product results and filters facets.Does the API expose stock availability or inventory levels?+
sell field on the product detail endpoint indicating whether an item is available for sale, but does not expose numeric stock quantities or warehouse-level inventory data. You can fork this API on Parse and revise it to add an endpoint targeting additional availability fields if they become accessible.Are product reviews or ratings included in any endpoint response?+
How are prices represented across the endpoints?+
search_products, browse_category) return price and promotion_price as floats in HKD. The get_product_detail endpoint also returns price as a float in HKD (internally derived from a cents value divided by 100) and always sets currency to 'HKD'. There is no multi-currency option.