Search & Scraping
Real-time Amazon product search — builds native Amazon.com search URLs and scrapes results via the Apify e-commerce actor.
How It Works
Build Amazon search URL
ApifyClientService.buildAmazonSearchUrl() converts the query string and any filters into a native amazon.com search URL — for example https://www.amazon.com/s?k=shoes&s=price-asc-rank. Sorting, price range, Prime eligibility, and product condition are all encoded as native Amazon URL parameters so the actor scrapes a pre-filtered page.
Run the Apify actor
The service calls actor('apify/e-commerce-scraping-tool').call(input, { timeout: 300 }) with scrapeMode: 'AUTO' and additionalProperties: true. The actor scrapes the Amazon listing page and stores results in an Apify dataset. A hard timeout of 300 seconds is applied to the actor run.
Retrieve and normalise results
The dataset items are fetched and passed through NormalisationService.normalizeAndValidate(), which filters out malformed entries and maps Apify field names to the internal NormalizedProduct shape.
Return ranked products
The response contains the product list, pagination metadata, execution time, and the source identifier "realtime".
Search Endpoint
GET /api/search/realtime
Rate limit: 10 requests per minute per IP. The endpoint is currently ungated — the @MppCharge payment decorator is disabled in the controller.
Query Parameters
Prop
Type
Response
{
"data": {
"products": [
{
"asin": "B09ABCDEF1",
"title": "Example Running Shoes",
"price": 49.99,
"originalPrice": 69.99,
"rating": 4.5,
"reviewCount": 1234,
"imageUrl": "https://...",
"productUrl": "https://www.amazon.com/dp/B09ABCDEF1",
"brand": "Nike",
"category": "Shoes",
"availability": true
}
],
"total": 18,
"page": 1,
"limit": 20,
"totalPage": 1,
"source": "realtime",
"query": "running shoes",
"executionTime": 8432
},
"status": "OK",
"code": 200,
"message": "Realtime search completed successfully"
}curl Example
curl "http://localhost:3001/api/search/realtime?q=running+shoes&limit=10&minPrice=20&maxPrice=100"Product Endpoint
GET /api/search/realtime/product/:asin
Fetches a single product by ASIN. The ASIN must match /^[A-Z0-9]{10}$/i.
Rate limit: 10 requests per minute per IP.
curl "http://localhost:3001/api/search/realtime/product/B09ABCDEF1"Health Check
GET /api/search/realtime/health
Returns { status: "healthy" } when the Apify API is reachable, { status: "unavailable" } otherwise. This calls ApifyClient.user().get() to validate the token.
Amazon URL Filters
The following search filters are translated to native Amazon URL parameters:
| Filter field | Amazon parameter |
|---|---|
category, brand, color, size | Appended to the k keyword |
minPrice | low-price |
maxPrice | high-price |
sortBy: "price_asc" | s=price-asc-rank |
sortBy: "price_desc" | s=price-desc-rank |
sortBy: "rating" | s=review-rank |
sortBy: "newest" | s=date-desc-rank |
prime: true | rh=p_85:2470955011 |
condition: "new" | rh=p_n_condition-type:6461716011 |
Error Handling
Environment Variables
Prop
Type
APIFY_API_TOKEN is required for search to work. Without it every actor call will fail with an authentication error.
How is this guide?