API reference
HomeDiscoveryOther resources
Start typing to search…

Just For You API (JFY) [deprecated]

get deprecated
https://core.dxpapi.com/api/v1/core/
🚧

The Just For You API is now part of the Recommendations and Pathways product and is no longer available for new integrations.

Just For You (JFY) is a Bloomreach Search and Merchandising feature. JFY includes the following personalizations:

  • Product Recommendations is a service that displays product recommendations for customers based on their browsing history. For example, if you have a customer who looks at very high heels, then you might suggest shoes with stiletto heels and shoes with four or five-inch heels.

  • Dynamic Categories is a service that displays recommended categories with sample products based on customers' browsing patterns. For example, if a customer browses several Louboutin slingback heels, then Dynamic Categories might suggest Shoes by Christian Louboutinor Evening Wear Shoes by Christian Louboutin, and display products matching those categories.

Endpoints

Production: https://core.dxpapi.com/api/v1/core/?
Staging: https://staging-core.dxpapi.com/api/v1/core/?

Example request and response

GET https://staging-core.dxpapi.com/api/v1/core/?
account_id=<Bloomreach Provided Account ID>
&auth_key=jazzhands
&domain_key=example_com
&request_id=2779692816548
&_br_uid_2=uid%3D9683404349848%3A_uid%3D1060194806196%3Av%3D11.5%3Ats%3D1366069652967%3Ahc%3D109
&url=http://www.example.com/index.html?JFY
&ref_url=http://www.example.com/home
&request_type=jfy
&content_type=jfy,dynamic_categories
&fl=thumb_image,url,title,brand,pid,sale_price,sale_price_type,price
{
 "dynamic_cats_response": {
     "title":"dynamic_cats"
      "docs": [ // list of suggestions
            { // suggestion 1
             "docs": [ // list of products in suggestion 1
                 {
                  title: "example product",
                  price: 34.9,
                  url: "http://www.example.com/91000048803",
                  pid: "91000048803",
                  thumb_image:"http://example/6838/1000048803-930-MAIN-170x269.jpg",
                  sale_price: 15,
                  sale_price_type: "",
                  brand: "Almost Famous"
               },
               {
                  // second product in suggestion 1
               },],
             "master_cat": "name of master category",
             "title": product by almost famous
            },
            {
             //suggestion 2
             .....
            }
       ] // end of list of all suggestions
    "personalized result": "true"
  },
  
 "response": { // jfy response (Recently browsed across devices)
       "docs": [
           {
               "thumb_image": "http://www.example.com/productpics/thumb/screen.jpg",
               "title": "Samsung Galaxy Anti-Glare Screen Protector Film",
               "url": "http://www.example.com/p-166880",
               "brand": "Samsung",
               "pid": "166880",
               "sale_price": 7.99,
               "sale_price_type": "",
               "price": 7.99
           },
           {
              // product 2
           },
           {
              // Product 3
           }
       ],
       "title": "jfy"
   }
  "personalized result": "true"
}
❗️

API requests should be limited to 16K Bytes. API requests above this length will throw Error Code 414.

Suggest categories

The Dynamic Categories service can suggest up to five Dynamic Categories. Each of these categories contains as many as 30 products with ranking optimized by Commerce Search and Categories based on various signals such as product generated revenue, conversions, views, and others.

Dynamic Categories are derived by examining the user's browsing history for product categories, brands, and on-sale statuses (boolean). The tuples (category, brand, sale) with the highest number of user activities become the user's personalized Dynamic Categories. These categories are tuned to user activities. The recommended categories and products are sensitive to changes in the category tree, product availability, price, and product performance. As the user browses more products, the recommendations become richer and more relevant.

Dynamic Categories are stored in dynamic_cats_response.docs.

You can specify excluded categories from Dynamic Categories. For example, you might decide to exclude sexual wellness categories from Dynamic Categories. Putting these categories on a blocklist prevents them from being automatically suggested when a user browses for other drugstore items. To block items from Product Recommendations, you need to contact your Bloomreach Technical Manager.

Suggest products

JFY begins generating personalized content after a user does three qualified activities, such as opening a product page. The Product Recommendations service can suggest as many as 20 products. These suggestions are based on the user's browsing history. The service compares the user's history with that of other users, identifying products with similar browsing patterns from similar users. As the browses more products, the recommendations are automatically updated. The more the user browses, the more refined the recommendations become.

The example response uses JSON output with JFY plus dynamic_cats_reponse. The user browsed at least three products, which is the threshold for showing Product Recommendations.

Product Recommendations are stored in response.docs.

What do JFY widgets display for new site visitors?

JFY widgets personalize suggestions and recommendations based on individual site visitor activity. If Bloomreach doesn't have enough information about a site visitor to generate personalized suggestions and recommendation, then your JFY widgets display bestseller products. For information about deploying the bestseller API on your site, see Bestseller API.

How do I check the quality of my JFY recommendations?

Here's how you can QA your JFY widgets:

  1. Open your site
    For best results, open your site in an incognito window. This way, you can be sure that your results are due to your activities during your test rather than prior activities.

  2. Open a page that displays a JFY widget
    Let's call this page your test page. Observe the products in the widgets. You're going to compare these products with the products displayed at the end of the test.

  3. Run a few searches and open at least five product pages per search
    This step simulates site visitor behavior so that Bloomreach can personalize the quality of results to individual visitors on your site.

  4. Return to your test page
    That's the page where you first noted the product recommendations in the JFY widget. Observe the set of products in the JFY widget. You're checking to see that the product recommendations are changed according to the search behavior you simulated during this test.

If your JFY widgets are still not displaying recommendations that are influenced by your activities, then contact your Bloomreach representative for help.

Native mobile app and non-JS integration

API requests for native mobile apps or non-JS environments need different values for some parameters:

  • _br_uid_2: The value should be the same as described on the Cookie page . Generate a br_uid_2 for your app user and store it in the app permanently if a br_uid_2 does not exist. This br_uid_2 should be used on the corresponding API calls for the app. If the user is on iPhone and resets their IDFA, or if the user is on an Android device and resets their advertising settings: the br_uid_2 should be erased and regenerated the next time the app is set.
  • ref_url: Leave your ref_url parameters empty.
  • url: Use a dummy value for your url parameters, such as exampledomain.app.
Query Params
int32
required
Defaults to 6702

Your site's numerical Bloomreach account ID. Your Bloomreach representative gives your site's account ID to you before or during your integration kickoff meeting.

The value shown here, 6702, is included for your convenience to send a request with Try It.

string
required

The Bloomreach-provided authentication key for the Bloomreach account that's sending the request. You must pass this parameter, but if your integration is client-side, then you can send it empty.

string
required
Defaults to uid%3D7797686432023%3Av%3D11.5%3Ats%3D1428617911187%3Ahc%3D55

A first-party cookie created by the Bloomreach tracking pixel library (BrTrk). This cookie creates a unique, anonymous identifier for every browser or device.

Use the default value provided, which is already encoded.

string
required

Your site domain's ID, which is provided by Bloomreach. This ID is for the domain that you want to receive your Bloomreach API requests. This parameter identifies the specific site version when the one account ID hosts multiple site versions with unique characteristics, such as language versions. Bloomreach uses your domain_key parameter value to ensure that only the data that pertains to that site version is used for query and analytics features, such as autosuggestions.

string
required

The attributes that you want returned in your API response, such as product IDs and prices.

All fl parameters must include pid as one of their values. Any attribute from your product feed may be used as a value for fl.

Multiple values should be comma separated, such as fl=pid,price.

string
required

An ID to track site visitor clicks. We recommend that you generate unique, random values of 13 digits to enable click-tracking.

Bloomreach doesn't automatically enforce the requirements for this parameter. For example, you can enter test as your value for each instance of the request_id parameter without triggering an error message. However, using a unique value allows us to help you if you encounter a problem.

string
enum
required
Defaults to jfy

The type of API request. Value should be jfy for JFY requests.

Allowed:
string
required

The universal customer ID of the user. You only need to pass this field if your particular integration tracks customers this way. The parameter captures user IDs from the customer side, and reuses the information when powering apps or enhancing cross-device linking. In this way, Bloomreach recognizes users in a way that's aligned with your system.

Use an anonymous string. Don't use email or other personally identifiable information.

If you do not track users this way, then omit this field.

string
enum
Defaults to jfy

Specifies the type of content to return in the response.

You can use multiple values by entering the values as a comma-separated list.

Allowed:
string

A unique identifier for a specific view of your product catalog. If you have multiple versions of your site, each with their own product catalog characteristics like product titles and prices, then add view_id to your call.

Bloomreach uses your view_id parameter value to display the right product information for your customers based on their individual site views. You can enter any string value to identify the specific site catalog view. This string must be consistent in your pixel, API, and product catalog.

Updated 9 days ago

Language
Response 
Click Try It! to start a request and see the response here!
Updated 9 days ago 




    
    

        

            ©  Bloomreach, Inc. All rights reserved.