Product recommendations

The recommendations API is used to retrieve product recommendations from Custobar. Recommendations can be based on a specific product, aggregated across all customers, or personalized for an individual customer.

Quick navigation: Product-based recommendations | Top products | Personalized recommendations | Common parameters

Product-based recommendations

Product-based recommendations return other products related to a given product, based on what other customers bought, viewed, or how similar the products are.

Basic recommendation lookup

To retrieve recommendations for a specific product, make a GET request to:

https://COMPANY.custobar.com/api/recommendations/PRODUCT_ID/TYPE/

PRODUCT_ID is the external_id of the product, and TYPE is one of the recommendation types below.

Recommendation types

Type	Description
similar	Products similar to the given product (based on brand, category, type, etc.)
bought	Products that customers who bought this product also bought
viewed	Products that customers who viewed this product also viewed
all	Returns all of the above types together

Extra parameters

You can refine the results using any of the following query parameters. Multiple parameters can be combined.

Parameter	Description	Example Value	Example Usage
ids_only	Return only product IDs instead of full product data	1	?ids_only=1
count	Number of recommended products to return	5	?count=5
boost	Boost products with similar attributes (brand, category, type, etc.) higher. Used with bought and viewed. Boosted fields are configured in company settings	1	?boost=1
category	Filter recommendations by product category	Tablet	?category=Tablet
type	Filter recommendations by product type	Hard+Cover	?type=Hard+Cover
brand	Filter recommendations by brand	Asus	?brand=Asus

If ids_only is not specified, the API returns the full product data (as stored in Custobar) for each recommended product, rather than just its ID.

Filter examples

Products bought together

Retrieve products that other customers also bought, returning IDs only:

https://COMPANY.custobar.com/api/recommendations/0375704027/bought/?ids_only=1

Example response:

{
    "bought": [
        {"score": 4.5243, "id": "0670034355"},
        {"score": 3.8633, "id": "0374272271"},
        {"score": 3.8012, "id": "031601074X"},
        {"score": 3.7608, "id": "0465005640"},
        {"score": 3.7018, "id": "006095485X"},
        {"score": 3.6444, "id": "0393061191"},
        {"score": 3.5705, "id": "0671027638"},
        {"score": 3.3647, "id": "0141022507"},
        {"score": 3.3326, "id": "1560977892"},
        {"score": 3.2243, "id": "0143038354"}
    ],
    "success": true
}

Filter by product type

Retrieve "bought" recommendations limited to a specific product type:

https://COMPANY.custobar.com/api/recommendations/0375704027/bought/?ids_only=1&type=Hard+Cover

Products viewed together

Retrieve products that other customers also viewed:

https://COMPANY.custobar.com/api/recommendations/0375704027/viewed/?ids_only=1

Similar products

Retrieve products similar to a given product:

https://COMPANY.custobar.com/api/recommendations/0375704027/similar/?ids_only=1

Top products

Top products endpoints return aggregate counts of the most bought or most viewed products across all customers, rather than recommendations tied to a specific product.

Most bought products

Retrieve the most sold products (product ID and purchase count):

https://COMPANY.custobar.com/api/products/bought/

Example response:

{
    "bought": [
        {"count": 14249, "id": "1416547363"},
        {"count": 14100, "id": "0141022469"},
        {"count": 13901, "id": "0743249402"},
        {"count": 385, "id": "0385338759"},
        {"count": 380, "id": "1400063841"},
        {"count": 379, "id": "0143114298"},
        {"count": 192, "id": "1568987889"},
        {"count": 191, "id": "0141022167"}
    ],
    "success": true
}

Most viewed products

Retrieve the most viewed products (product ID and view count):

https://COMPANY.custobar.com/api/products/viewed/

Extra parameters

Parameter	Description	Example Value	Example Usage
category	Filter by product category	Tablet	?category=Tablet
brand	Filter by brand	asus	?brand=asus
date	Filter by date range, formatted as START_DATE_END_DATE	2016-01-01_2017-01-01	?date=2016-01-01_2017-01-01
count	Number of products to return	50	?count=50

Filter examples

Filter by category

Retrieve the most bought products in a specific category:

https://COMPANY.custobar.com/api/products/bought/?category=Tablet

Filter by brand

Retrieve the most bought products from a specific brand:

https://COMPANY.custobar.com/api/products/bought/?brand=asus

Retrieve the most viewed products from a specific brand:

https://COMPANY.custobar.com/api/products/viewed/?brand=samsung

Filter by brand and date range

Retrieve the most bought products from a brand within a date range:

https://COMPANY.custobar.com/api/products/bought/?brand=hp&date=2016-01-01_2017-01-01

Filter by count

Retrieve a specific number of top products:

https://COMPANY.custobar.com/api/products/bought/?brand=asus&count=5

https://COMPANY.custobar.com/api/products/bought/?brand=asus&count=50

Personalized product recommendations for customer

Personalized recommendations return products recommended specifically for a given customer, based on that customer's own purchase history.

Basic lookup

To retrieve personalized recommendations for a customer, make a GET request to:

https://COMPANY.custobar.com/api/customers/CUSTOMER_ID/recommendations/?ids_only=1&count=10

CUSTOMER_ID is the Custobar customer ID (not the external_id).

Extra parameters

Parameter	Description	Example Value	Example Usage
ids_only	Return only product IDs instead of full product data	1	?ids_only=1
count	Number of recommended products to return	10	?count=10

Example

https://COMPANY.custobar.com/api/customers/294168/recommendations/?ids_only=1

Note: Personalized product recommendations do not currently use Custobar cookie information. The requesting website or app must always know the customer ID when requesting recommendations.

Common parameters

The following parameters are available across multiple recommendation endpoints. See the relevant section above for which parameters apply to which endpoint.

Parameter	Description
ids_only	Return only product IDs instead of full product data
count	Number of products to return
boost	Boost products with similar attributes higher (product-based recommendations only)
category	Filter results by product category
type	Filter results by product type
brand	Filter results by brand
date	Filter results by date range (top products only), formatted as START_DATE_END_DATE