From raw product data to intelligent recommendations and sentiment insights — in minutes.
In the modern e-commerce landscape, data is abundant, but intelligence is scarce. Retailers are sitting on thousands of product descriptions, mountains of customer reviews, and untapped cross-selling opportunities — yet most of them are still relying on rigid, manually maintained rule sets to power their "You might also like" sections.
Building a proper AI infrastructure to fix this — handling vector databases, embedding models, large language model (LLM) orchestration, and multi-tenant data isolation — is a months-long engineering project. That is the gap NeoRetailBrain (NRB) was built to close.
NRB is an enterprise-grade API suite that turns your product catalog into a semantic recommendation engine and your customer reviews into structured business intelligence. All through simple REST calls. No ML infrastructure required.
This article walks you through what NRB does, how it works, and how to integrate it end-to-end in Python.
What NeoRetailBrain Solves
1. The "You might also like" problem
Traditional recommendation engines operate on association rules: people who bought X also bought Y. This works at massive scale (think Amazon), but it requires enormous transaction volumes to produce reliable rules. For most retailers, it produces generic, unhelpful suggestions.
NRB uses semantic vector search instead. When you upload a product, NRB generates a high-dimensional representation of its meaning — based on its name, category, and description. When a customer adds items to their cart, NRB finds the products in your catalog that are semantically closest to what they already intend to buy. No transaction history needed. No cold-start problem.
A customer buying noise-cancelling headphones gets recommended a carrying case and a USB-C audio adapter — not because other users bought those items together, but because the AI understands they are contextually related.
2. The review analysis problem
Star ratings are a blunt instrument. A product with a 3.8 average tells you nothing about why customers are unhappy — or which specific features they love. NRB's Insight Engine processes batches of reviews through an LLM and returns:
- Overall sentiment score (0.0 = very negative, 1.0 = very positive)
- Top positive topics — the features customers praise most
- Top negative topics — the pain points they keep mentioning
- Executive summary — a two-sentence human-readable synthesis
This is the difference between knowing your product has a 3.8 and knowing "customers love the sound quality but consistently complain about comfort during extended use."
3. The multi-tenancy problem
Every business has a different catalog. NRB keeps them completely separated. Your products are indexed under your account only — no other API consumer can access or influence your recommendations. The isolation is enforced at the database level on every query.
How It Works: The Full Architecture
NRB exposes six endpoints organized into three modules:
Catalog Management
├── POST /catalog/upsert → Upload / update products
├── GET /catalog/products → List your indexed catalog
└── DELETE /catalog/product/{id} → Remove a product
Recommendation Engine
└── POST /cross_sell → Get cross-sell suggestions
Insight Engine
└── POST /analyze_reviews → Batch sentiment analysis
Monitoring
└── GET /health → System status
The recommended flow is straightforward:
Upload catalog → Index & embed products → Query cross_sell with cart → Get recommendations
Getting Started
You only need Python and the requests library:
pip install requests
Set up your credentials once and reuse them across all calls:
import requests
API_KEY = "YOUR_RAPIDAPI_KEY_HERE"
HOST = "neoretailbrain-api-ai-powered-e-commerce-intelligence.p.rapidapi.com"
BASE_URL = f"https://{HOST}"
HEADERS = {
"X-RapidAPI-Key": API_KEY,
"X-RapidAPI-Host": HOST,
"Content-Type": "application/json"
}
Never hardcode your API key in frontend code or public repositories. Use environment variables.
Step 1: Verify the API is Online
Before any business-critical call, check system status:
response = requests.get(f"{BASE_URL}/health", headers=HEADERS)
print(response.json())
{
"status": "UP",
"database": "CONNECTED",
"ai_subsystem": "READY"
}
Step 2: Upload Your Product Catalog
This is the step that unlocks everything. Send your products to /catalog/upsert and NRB will automatically generate a semantic representation for each one.
products = [
{
"product_id": "PROD-001",
"name": "Wireless Noise-Cancelling Headphones",
"category": "electronics",
"description": "Over-ear headphones with 30-hour battery life, active noise cancellation, and premium sound quality. Foldable design for travel."
},
{
"product_id": "PROD-002",
"name": "Headphone Carrying Case",
"category": "accessories",
"description": "Hard-shell protective case for over-ear headphones. Water-resistant exterior with interior cable organizer."
},
{
"product_id": "PROD-003",
"name": "USB-C Audio Adapter",
"category": "accessories",
"description": "High-fidelity USB-C to 3.5mm audio adapter. Compatible with all major smartphone and laptop brands."
},
{
"product_id": "PROD-004",
"name": "Replacement Ear Cushions",
"category": "accessories",
"description": "Memory foam replacement ear pads compatible with most over-ear headphone models. Soft protein leather finish."
}
]
response = requests.post(f"{BASE_URL}/catalog/upsert", json={"products": products}, headers=HEADERS)
print(response.json())
{
"processed": 4,
"inserted": 4,
"updated": 0,
"errors": []
}
The endpoint is idempotent — call it again with the same product_id and it updates the existing record. This means you can run it on every deployment or catalog sync without side effects.
A note on description quality: The description field is what drives recommendation accuracy. The more context you provide — materials, compatibility, use case, target audience — the better the semantic matching will be. A description like "Case for headphones" will produce significantly weaker results than "Hard-shell protective case for over-ear headphones with water-resistant exterior and interior cable organizer."
Batch limit: Up to 500 products per request. For larger catalogs, split into sequential batches of 500.
Step 3: Audit Your Catalog
Before going to production, verify what was indexed:
response = requests.get(f"{BASE_URL}/catalog/products", headers=HEADERS)
data = response.json()
print(f"Total products indexed: {data['total']}")
for product in data['products']:
print(f" [{product['product_id']}] {product['name']} — {product['category']}")
Total products indexed: 4
[PROD-001] Wireless Noise-Cancelling Headphones — electronics
[PROD-002] Headphone Carrying Case — accessories
[PROD-003] USB-C Audio Adapter — accessories
[PROD-004] Replacement Ear Cushions — accessories
To remove a discontinued product:
response = requests.delete(f"{BASE_URL}/catalog/product/PROD-003", headers=HEADERS)
print(response.json())
# {"message": "Product 'PROD-003' removed successfully."}
Step 4: Get Cross-Sell Recommendations
With the catalog indexed, the recommendation engine is ready. Pass the items currently in the customer's cart:
cart = [
{"product_id": "PROD-001", "category": "electronics"}
]
response = requests.post(
f"{BASE_URL}/cross_sell",
json={"cart_items": cart, "top_k": 3},
headers=HEADERS
)
print(response.json())
{
"recommended_product_ids": ["PROD-004", "PROD-002"],
"confidence_score": 0.8912,
"message": "Recomendações geradas com sucesso."
}
The engine identified that a customer buying headphones would likely want replacement ear cushions and a carrying case — without a single rule manually written.
Understanding the confidence score
| Score range | What it means |
|---|---|
0.80 – 1.00 |
Strong semantic match from your catalog |
0.55 – 0.79 |
Fallback result — rule-based suggestions |
Scores above 0.80 mean the engine found genuinely relevant products in your catalog. Scores below 0.80 indicate the fallback was triggered (more on this below).
The Fallback: Never an Empty Response
NRB is designed to always return something useful, even when the catalog is empty, the database is temporarily unreachable, or no semantically close products are found.
In those cases, the engine switches to a rule-based fallback:
| Cart category | Fallback suggestions |
|---|---|
smartphones |
Cases, screen protectors, earbuds, chargers |
laptops |
Mouse, bag, stand, monitor |
smartwatches |
Straps, chargers, screen protectors |
| Anything else | Gift cards, warranties, batteries |
Your front-end should be built to display recommendations regardless of whether they come from your catalog or the fallback — your "You might also like" section should never be blank.
Step 5: Analyze Customer Reviews
The Insight Engine works independently from the catalog. Pass any batch of reviews and receive structured intelligence:
reviews = [
{"review_id": "rev_001", "text": "The noise cancellation is incredible. I use these on every flight and they block out everything."},
{"review_id": "rev_002", "text": "Sound quality is outstanding but they get uncomfortable after about two hours of continuous use."},
{"review_id": "rev_003", "text": "Battery life is exactly as advertised. Carried them through a 12-hour travel day without charging."},
{"review_id": "rev_004", "text": "The carrying case feels cheap for the price. Expected better build quality on the accessories."},
{"review_id": "rev_005", "text": "Best headphones I have ever owned. Customer support helped me with the setup in minutes."}
]
response = requests.post(f"{BASE_URL}/analyze_reviews", json={"reviews": reviews}, headers=HEADERS)
data = response.json()['data']
print(f"Sentiment score: {data['overall_sentiment']}")
print(f"Positive topics: {data['positive_topics']}")
print(f"Negative topics: {data['negative_topics']}")
print(f"Summary: {data['executive_summary']}")
{
"processed_count": 5,
"overall_sentiment": 0.76,
"positive_topics": [
"Noise cancellation effectiveness",
"Battery life accuracy",
"Sound quality",
"Customer support responsiveness"
],
"negative_topics": [
"Long-term wearing comfort",
"Accessory build quality"
],
"executive_summary": "Customers are highly satisfied with core audio performance and battery life, but consistently flag discomfort during extended use and disappointment with accessory quality relative to the price point."
}
This is actionable intelligence. Instead of seeing a 3.8-star average and guessing, your product team now knows exactly what to improve.
Batch limit: Up to 100 reviews per request. For larger datasets, split into sequential batches.
Full End-to-End Script
Here is everything together in one script — a complete integration you can run today:
import requests
API_KEY = "YOUR_RAPIDAPI_KEY_HERE"
HOST = "neoretailbrain-api-ai-powered-e-commerce-intelligence.p.rapidapi.com"
BASE_URL = f"https://{HOST}"
HEADERS = {
"X-RapidAPI-Key": API_KEY,
"X-RapidAPI-Host": HOST,
"Content-Type": "application/json"
}
# 1. Health check
health = requests.get(f"{BASE_URL}/health", headers=HEADERS).json()
print(f"[1] API: {health['status']} | DB: {health['database']}")
# 2. Upload catalog
products = [
{"product_id": "PROD-001", "name": "Wireless Headphones", "category": "electronics",
"description": "Premium noise-cancelling wireless headphones with 30h battery and foldable design."},
{"product_id": "PROD-002", "name": "Carrying Case", "category": "accessories",
"description": "Hard-shell protective case for over-ear headphones, water-resistant."},
{"product_id": "PROD-003", "name": "Replacement Ear Cushions", "category": "accessories",
"description": "Memory foam replacement ear pads compatible with most over-ear headphone models."},
]
upsert = requests.post(f"{BASE_URL}/catalog/upsert", json={"products": products}, headers=HEADERS).json()
print(f"[2] Catalog: {upsert['inserted']} inserted, {upsert['updated']} updated")
# 3. Audit catalog
catalog = requests.get(f"{BASE_URL}/catalog/products", headers=HEADERS).json()
print(f"[3] {catalog['total']} products indexed")
# 4. Cross-sell recommendation
cart = [{"product_id": "PROD-001", "category": "electronics"}]
recs = requests.post(f"{BASE_URL}/cross_sell", json={"cart_items": cart, "top_k": 2}, headers=HEADERS).json()
print(f"[4] Recommended: {recs['recommended_product_ids']} (confidence: {recs['confidence_score']})")
# 5. Review analysis
reviews = [
{"review_id": "r1", "text": "Incredible noise cancellation, perfect for travel."},
{"review_id": "r2", "text": "Great sound but uncomfortable after two hours of use."},
{"review_id": "r3", "text": "Battery lasted exactly 30 hours as advertised. Very impressed."},
]
insights = requests.post(f"{BASE_URL}/analyze_reviews", json={"reviews": reviews}, headers=HEADERS).json()['data']
print(f"[5] Sentiment: {insights['overall_sentiment']} — {insights['executive_summary']}")
Limitations to Know Before You Ship
Transparency matters. Here is what you should account for when integrating NRB into production:
Recommendation quality depends on catalog quality. Thin descriptions like "Blue shirt, size M" will produce weak recommendations. Rich descriptions covering materials, use cases, compatibility, and target audience will produce strong ones. Invest time in your product data.
100 reviews per batch, 500 products per batch. Design your pipelines around these limits. For high-volume review ingestion, process in parallel batches.
Fallback is automatic but generic. If your catalog is empty, the cross-sell engine will return rule-based suggestions with generic product IDs. Always populate your catalog before directing production traffic to the /cross_sell endpoint.
Catalog pagination is not yet available. The /catalog/products endpoint returns your full catalog. For very large catalogs, this response can be sizable — plan accordingly on the client side.
First request latency. If the API has been idle, the first request may take slightly longer than subsequent ones as internal services warm up. This is a one-time cost per idle period and does not affect ongoing throughput.
The Takeaway
NeoRetailBrain compresses what would be months of AI infrastructure work into a few API calls. You bring the catalog and the reviews; NRB handles the embeddings, the semantic search, the LLM orchestration, and the multi-tenant isolation.
The result: a recommendation engine that understands your products the way a knowledgeable salesperson would, and a review analysis pipeline that tells your product team exactly what to fix next.
Ready to integrate? Find the full endpoint documentation and start testing on the RapidAPI Hub.
Top comments (0)