Loyaly/loyaly-catalogue
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

MD Doc updates

Browse Source
This commit is contained in:
sriram
2026-10-07 11:10:15 +05:30
parent 19b6a63021
commit f2688c7984
2 changed files with 242 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

49
docs/API.md
View File

@@ -40,6 +40,7 @@ Reliance Digital, Vijay Sales, Tata CLiQ, Poorvika, Sangeetha, Vasanth & Co and
| GET | [`/api/elec/products`](#get-apielecproducts) | Product list with filters |
| GET | [`/api/elec/products/{product_id}`](#get-apielecproductsproduct_id) | Full product detail |
| GET | [`/api/elec/products/{product_id}/price-history`](#get-apielecproductsproduct_idprice-history) | Price over time per platform |
| GET | [`/api/elec/products/{product_id}/recommendations`](#get-apielecproductsproduct_idrecommendations) | Similar or better-rated products to suggest, and other variants |
| GET | [`/api/elec/sites`](#get-apielecsites) | The retail platforms read |
### `GET /api/health`
@@ -103,12 +104,15 @@ curl "http://31.97.228.132:8000/api/elec/products?category=mobiles&brand=samsung
"best_price": "42999.00",
"best_price_site": "Reliance Digital",
"platform_count": 5,
"image_url": "https://img-prd-pim.poorvika.com/product/Samsung-Galaxy-A56-5G-Awesome-Graphite-Main.png"
"image_url": "https://img-prd-pim.poorvika.com/product/Samsung-Galaxy-A56-5G-Awesome-Graphite-Main.png",
"rating": 4.5,
"rating_count": 1224
}
]
}
```
`total` is the full match count; use `limit`/`offset` to page. Some extra fields (`brand_slug`,
`total` is the full match count; use `limit`/`offset` to page. `rating` / `rating_count` are the same
overall rating as the product detail's `rating.value` / `rating.count` (`null` when no platform publishes one). Some extra fields (`brand_slug`,
`family`, `model`, `processor`, `sold_by_tn_retailer`, `updated_at`, ...) are also present.
### `GET /api/elec/products/{product_id}`
@@ -160,6 +164,46 @@ curl http://31.97.228.132:8000/api/elec/products/551/price-history
```
Oldest first, one row per observation per platform.
### `GET /api/elec/products/{product_id}/recommendations`
```bash
curl http://31.97.228.132:8000/api/elec/products/551/recommendations
```
| Parameter | Meaning |
|---|---|
| `type` | `similar` (default) or `better_rated` |
| `limit` | 1–12, default 6 |
| `tn_only` | `true` to suggest only products sold by a Tamil Nadu retailer |
```json
{
"product_id": 551, "type": "similar",
"items": [
{ "product_id": 560, "brand": "Samsung", "display_name": "Samsung Galaxy A37 (8GB RAM, 256GB)",
"ram_gb": 8.0, "storage_gb": 256.0, "image_url": "https://…", "best_price": "52999.00",
"best_price_site": "Croma", "rating": 4.7, "rating_count": 648,
"basis": "similar", "reason": "Similar specs · 4.7★ vs 4.5★" }
],
"other_variants": [
{ "product_id": 552, "display_name": "Samsung Galaxy A56 (8GB RAM, 128GB)",
"ram_gb": 8.0, "storage_gb": 128.0, "best_price": "38999.00" }
]
}
```
Notes:
- Same category, in stock, never the product itself. Other RAM/storage variants of the same model are left
out of `items` and listed in `other_variants` instead. A laptop variant must also have the same processor
(other CPUs of one model line are separate products).
- **Price limit:** every item's best price is within ±30% (`similar`) or ±20% (`better_rated`) of this
product's. A product with no price of its own gets no limit.
- `similar` is ranked by `0.60 × spec similarity + 0.25 × rating + 0.15 × price closeness`. The rating is weighted by
how many people rated it, so 5.0★ from 3 ratings does not beat 4.4★ from 2,000.
- `basis` is `similar`, or `top_rated` when fewer than 3 similar products exist and the best-rated in the
category fill the list. `rating` is `null` when no platform publishes one.
- `better_rated` lists only products rated higher than this one (any rated product if this one has no
rating) by at least 5 people, best weighted rating first; ties go to the product whose reviews are more
positive. `basis` is `better_rated` and `reason` reads e.g. `"4.5★ vs 4.1★ · 2,300 ratings"`. Often
empty: few products have 5+ ratings yet.
- See [RECOMMENDATIONS.md](RECOMMENDATIONS.md) for the full design.
### `GET /api/elec/sites`
```bash
curl http://31.97.228.132:8000/api/elec/sites
@@ -213,6 +257,7 @@ The same catalogue is an MCP server (Streamable HTTP transport) at
| `search_products` | `query`, `category`, `brand`, `max_price`, `min_price`, `limit` (all optional, `limit` 1–100, default 20) | `total` and products: id, name, RAM/storage, best price and platform, platform count, image URL |
| `get_product` | `product_id` | Offers per platform, specs, `image_urls`, rating, reviews |
| `price_history` | `product_id` | Every observed price per platform |
| `recommend_products` | `product_id`, `kind` (`similar` or `better_rated`, default `similar`), `limit` (1–12, default 6) | Alternatives with a reason each, and the model's other variants |
Images are returned as **URLs** on the retailers' own image servers; nothing is re-hosted. Only part
of the catalogue has an image.