Retrieve Product Metadata

Retrieves aggregated metadata about products, including total count and price/discount ranges. This endpoint is useful for building product filters, price ranges, and analytics dashboards.

HTTP Request

GET/api/shop/products/metadata

Authorization

Authorization

• Required: No
• Permission: Public (read-only)
• Authentication: None

Query Parameters

This endpoint supports all the same filtering parameters as the List Products endpoint to get metadata for specific product subsets:

Parameter	Type	Default	Description
search	string	—	Search term to filter products before calculating metadata
brand_id	integer	—	Filter by specific brand ID
brand_in	string	—	Filter by multiple brand IDs (comma-separated: `1,2,3`)
category_id	integer	—	Filter by specific category ID
category_in	string	—	Filter by multiple category IDs (comma-separated: `1,2,3`)
category_tree_id	integer	—	Filter by category tree ID (returns metadata for products in the category and subcategories)
regular_price_min	number	—	Minimum regular price filter
regular_price_max	number	—	Maximum regular price filter
sale_price_min	number	—	Minimum sale price filter
sale_price_max	number	—	Maximum sale price filter
price_min	number	—	Minimum final price filter
price_max	number	—	Maximum final price filter
has_discount	boolean	—	Filter products with/without discount
discount_min	number	—	Minimum discount amount filter
discount_max	number	—	Maximum discount amount filter
discount_percent_min	number	—	Minimum discount percentage filter
discount_percent_max	number	—	Maximum discount percentage filter
in_stock	boolean	—	Filter by stock availability
has_image	boolean	—	Filter products with/without image
has_comments	boolean	—	Filter products with/without comments
comments_count_min	integer	—	Minimum comments count filter
comments_count_max	integer	—	Maximum comments count filter
rating_min	number	—	Minimum rating filter
rating_max	number	—	Maximum rating filter
id_min	integer	—	Minimum ID filter
id_max	integer	—	Maximum ID filter
created_date	string	—	Filter by creation date (e.g., `2023-01-01`)
updated_date	string	—	Filter by last updated date (e.g., `2023-01-01`)
created_from	string	—	Filter by creation date range start
created_to	string	—	Filter by creation date range end
updated_from	string	—	Filter by last updated date range start
updated_to	string	—	Filter by last updated date range end

Example Requests

🐍 Python

1import requests
2
3# Get metadata for all products
4response = requests.get('http://www.example.com/api/shop/products/metadata')
5print(response.json())
6
7# Get metadata for specific category
8response = requests.get('http://www.example.com/api/shop/products/metadata', params={
9  'category_id': 1
10})
11print(response.json())
12
13# Get metadata for products with discounts
14response = requests.get('http://www.example.com/api/shop/products/metadata', params={
15  'has_discount': True
16})
17print(response.json())
18
19# Get metadata for specific brand and price range
20response = requests.get('http://www.example.com/api/shop/products/metadata', params={
21  'brand_id': 5,
22  'price_min': 100,
23  'price_max': 1000
24})
25print(response.json())
26
27# Get metadata for search results
28response = requests.get('http://www.example.com/api/shop/products/metadata', params={
29  'search': 'smartphone'
30})
31print(response.json())

🌐 Curl

1# Get metadata for all products
2curl "http://www.example.com/api/shop/products/metadata"
3
4# Get metadata for specific category
5curl "http://www.example.com/api/shop/products/metadata?category_id=1"
6
7# Get metadata for products with discounts
8curl "http://www.example.com/api/shop/products/metadata?has_discount=true"
9
10# Get metadata for specific brand and price range
11curl "http://www.example.com/api/shop/products/metadata?brand_id=5&price_min=100&price_max=1000"
12
13# Get metadata for search results
14curl "http://www.example.com/api/shop/products/metadata?search=smartphone"

Status Codes

Code	Description
200	Metadata retrieved successfully
400	Bad request — invalid query parameters
500	Internal server error

Response Fields

Field	Type	Description
total_products	integer	Total number of products matching the filters
max_price	decimal or null	Highest final price among filtered products
min_price	decimal or null	Lowest final price among filtered products
max_discount	decimal or null	Highest discount amount among filtered products
min_discount	decimal or null	Lowest discount amount among filtered products
max_discount_percent	decimal or null	Highest discount percentage among filtered products
min_discount_percent	decimal or null	Lowest discount percentage among filtered products

Example Response

{
  "total_products": 150,
  "max_price": 999.99,
  "min_price": 49.99,
  "max_discount": 200.00,
  "min_discount": 10.00,
  "max_discount_percent": 50.0,
  "min_discount_percent": 5.0
}

Use Cases

Price Range Filters

Use the min_price and max_price values to set the bounds for price range sliders in your UI:

# Get price range for a category
response = requests.get('/api/products/metadata?category_id=1')
metadata = response.json()
price_slider_min = float(metadata['min_price'])
price_slider_max = float(metadata['max_price'])

Discount Information

Use discount metadata to show discount ranges and filter availability:

# Check if any products have discounts
response = requests.get('/api/products/metadata?has_discount=true')
metadata = response.json()
if metadata['total_products'] > 0:
    max_discount_percent = float(metadata['max_discount_percent'])
    print(f"Discounts up to {max_discount_percent}% available!")

Search Results Summary

Display result counts and price ranges for search results:

# Get metadata for search results
response = requests.get('/api/products/metadata?search=laptop')
metadata = response.json()
print(f"Found {metadata['total_products']} laptops")
print(f"Price range: ${metadata['min_price']} - ${metadata['max_price']}")

Analytics and Reporting

Use metadata for dashboard analytics:

# Compare categories
categories = [1, 2, 3]
for cat_id in categories:
    response = requests.get(f'/api/products/metadata?category_id={cat_id}')
    metadata = response.json()
    print(f"Category {cat_id}: {metadata['total_products']} products")

Performance Notes

• Caching: This endpoint supports caching to improve performance for frequently requested metadata
• Filtering Impact: All filters are applied before calculating aggregations, so metadata reflects the filtered dataset
• Real-time Data: Metadata is calculated from the current state of the database, including real-time price and discount calculations
• Search Performance: When using search parameters, metadata calculation may take longer due to text search operations

Notes

• All price and discount values are calculated using the same logic as the product listing endpoints
• Null values may be returned for min/max fields if no products match the filters
• The total_products count reflects only active products that match all applied filters
• Search functionality supports the same operators and syntax as the main product search
• This endpoint is particularly useful for building dynamic UI components like price sliders and filter summaries