Page tree
Skip to end of metadata
Go to start of metadata

IMPORTANT NOTE: Please keep in mind that due to network failures or other unexpected issues an error may occur while getting the recommendation from or while adding events to the recommendation engine. This error can cause a program exception which always has to be handled in the proper way. Without handling the possible exceptions your code may terminate at an unexpected place and your site will operate abnormally. Even if you do not get a valid list of recommended items as a result of the recommendation request take care about hiding the recommendation widget or filling it with relevant items. Please ensure the safe error handling. Gravity does not take any responsibility for any damages caused by the lack or deficiency of error handling.


API base URL

Your API endpoint URL depends on your CUSTOMERID and the data center you are served from. The pattern for generating your base API endpoint is:

API base URL
http://<customer>-<location>.gravityrd-services.com/grrec-<customer>-war/WebshopServlet

As an example if your CUSTOMERID is mywebshop and you are served from our Amsterdam cluster your API base URL would be:

Example API base URL
http://mywebshop-ams.gravityrd-services.com/grrec-mywebshop-war/WebshopServlet

Add event

Events are included in the body of HTTP request.

API endpoint - HTTP POST:

Add events API endpoint
<baseurl>/addEvents?async=true

Example HTTP request body:

Add events request body
[
    {
        "itemId":"sampleItemId1",
        "userId":"sampleUserId1",
        "eventType":"BUY",
        "nameValues":
        [
            {"name":"unitPrice","value":"199.9"},
            {"name":"quantity","value":"1"},
            {"name":"orderId","value":"order-0123"}
        ]
    },
    {
        "itemId":"sampleItemId2",
        "userId":"sampleUserId2",
        "eventType":"BUY",
        "nameValues":
        [
            {"name":"unitPrice","value":"15"},
            {"name":"quantity","value":"2"},
            {"name":"orderId","value":"order-2423"}
        ]
    },
    ...
]

The response is an empty HTTP 200 in case of success.

Add or update items

Items can be added to the RECO by the following calls. If you want to modify an item you should add it again with the same ID but with the modified properties. The unmodified properties should be included in the call also.

API endpoint - HTTP POST:

Add items API endpoint
<baseurl>/addItems?async=true

Example HTTP request body:

Add items request body
[
    {
        "itemId":"sampleItem1",
        "title":"Sample product 1",     
        "hidden":false,
        "nameValues":
        [
            {"name":"description","value":"This is only a sample product."},
            {"name":"categoryPath","value":"mainCategory/subCategory"},
            {"name":"url","value":"http://example.com/sampleItem1"},
            {"name":"imageUrl","value":"http://example.com/sampleItem1Image.jpg"}
        ]
    },
    {
        "itemId":"sampleItem2",
        "title":"Sample product 2",
        "hidden":false,
        "nameValues":
        [
            {"name":"description","value":"This is only a sample product."},
            {"name":"categoryPath","value":"mainCategory/subCategory"},
            {"name":"url","value":"http://example.com/sampleItem2"},
            {"name":"imageUrl","value":"http://example.com/sampleItem2Image.jpg"}
        ]
    },
    ...
]

The response is an empty HTTP 200 in case of success.

Delete items

If an item is removed from your catalog you should delete it also from the RECO. More precisely you should set it to hidden. RECO never deletes the items because it's data may be necessary for the training of the recommendation algorithms, but it's set to hidden it will never be recommended.

API endpoint - HTTP POST:

Delete items API endpoint
<baseurl>/updateItems?async=true

Example HTTP request body:

Delete items request body
[
    {
        "itemId":"sampleItem1", 
        "hidden":true
    },
    {
        "itemId":"sampleItem2",
        "hidden":true
    },
    ...
]

The response is an empty HTTP 200 in case of success.


Add or update users

Users are included in the body of HTTP request. Even when the user already exists in the recommendation engine, all of its name values should be sent with the request.

API endpoint - HTTP POST:

Add users API endpoint
<baseurl>/addUsers?async=true

Example HTTP request body:

Add users request body
[
    {
        "userId":"testUser1",
        "hidden":false,
        "nameValues":
        [
            {"name":"name","value":"Jack Test"},
            {"name":"sex","value":"male"},
            {"name":"country","value":"USA"}
        ]
    },
    {
        "userId":"testUser2",
        "hidden":false,
        "nameValues":
        [
            {"name":"name","value":"Rose Reco"},
            {"name":"sex","value":"female"},
            {"name":"country","value":"USA"}
        ]
    },
    ...
]

The response is an empty HTTP 200 in case of success.


Get item recommendation

IMPORTANT NOTE: Please keep in mind that trough network error or through other unexpected issues may an error occurs while getting the recommendation from or while adding events to the recommendation engine. This error can cause a program exception which always has to be handled in the proper way. Without handling the possible exceptions your code may terminate at an unexpected place and your site will operate abnormally. Even if you do not get a valid list of recommended items as a result of the recommendation request take care about hiding the recommendation widget or filling it with relevant items. Please ensure the safe error handling. Gravity does not take any responsibility for any damages caused by the lack or deficiency of error handling

Parameters can be included in the query string.

API endpoint - HTTP GET:

Get recommendation API endpoint
<baseurl>/getItemRecommendation?userId=testUser1&cookieId=1512467a76a-5cc340e5fa6ba5c2&scenarioId=MAIN_PAGE&numberLimit=5&resultNameValue=title&resultNameValue=imageUrl&resultNameValue=Url
Query string parameter nameDescription
userIdThe identifier of the user
cookieIdThe cookie identifier
scenarioIdThe name of the scenario
numberLimitThe number of recommended items
resultNameValueAn item attribute name to be returned
OtherA custom request name and value, for example for filtering

The response is in JSON format. Example HTTP response body:

Recommendation response
{
    "recommendationId":"hlt9c2h4-hb28ld2viza-S.MAIN_PAGE-1xutalp",
    "items":
    [
        {
            "itemId":"sampleItem1",
            "title":"Sample Item 1",
            "itemType":"",
            "hidden":false,
            "fromDate":0,
            "toDate":0,
            "nameValues": [
                {"name":"url","value":"http://example.com/sampleItem1"},
                {"name":"imageUrl","value":"http://example.com/sampleItem1Image.jpg"}
            ]
        }, 
        {
            "itemId":"sampleItem2",
            "title":"Sample Item 2",
            "itemType":"",
            "hidden":false,
            "fromDate":0,
            "toDate":0,
            "nameValues": [
                {"name":"url","value":"http://example.com/sampleItem2"},
                {"name":"imageUrl","value":"http://example.com/sampleItem2Image.jpg"}
            ]
        }
    ],
  "itemIds":["sampleItem1", "sampleItem2"],
  "predictionValues" : [ 1.0, 0.9 ]
}

Get bulk item recommendation

Parameters for the recommendation requests are sent as the body of the HTTP POST request.

Example request - HTTP POST:

Get recommendation API endpoint
<baseurl>/getItemRecommendationBulk?userId=120&cookieId=150b84fc9fa-2c4e4e60fdd7f1f1


Example HTTP request body:

{
    "scenarioId": "MAIN_PAGE_PERSONAL",
    "numberLimit": 2,
    "nameValues": [{
        "name": "categoryId",
        "value": "3"
    }],
    "resultNameValues": [
        "imgUrl",
        "price",
        "categoryId"
    ]
}, {
    "scenarioId": "MAIN_PAGE_PERSONAL",
    "numberLimit": 2,
    "nameValues": [{
        "name": "categoryId",
        "value": "4"
    }],
    "resultNameValues": [
        "imgUrl",
        "price",
        "categoryId"
    ]
}

In the response recommendation list each item is the answer for the same recommendation request

Example HTTP response body:

 {
    "recommendationId":"hlt9c2h4-hb28ld2viza-S.MAIN_PAGE_PERSONAL-1xutalp",
    "items":
    [
      {
        "itemId":"1",
        "title":"Example Item Title 1",
        "itemType":"Product",
        "hidden":false,
        "fromDate":0,
        "toDate":0,
        "nameValues":
        [
          {"name":"imageUrl","value":"http://webshop.example.com/img1.jpg"},
          {"name":"price","value":"10"},
          {"name":"categoryId","value":"2"},
          {"name":"categoryId","value":"8"}
        ]
      },
      {
        "itemId":"2",
        "title":"Example Item Title 2",
        "itemType":"Product",
        "hidden":false,
        "fromDate":0,
        "toDate":0,
        "nameValues":
        [
          {"name":"imageUrl","value":"http://webshop.example.com/img2.jpg"},
          {"name":"price","value":"15"},
          {"name":"categoryId","value":"2"},
          {"name":"categoryId","value":"9"}
        ]
      }
    ],
    "itemIds":["1","2"],
    "predictionValues" : [ 4.2068971, 3.80689716 ]
  },
  {
    "recommendationId":"hlt9egaz-e8x3w6d7ez5-S.MAIN_PAGE_PERSONAL-15u0c0n",
    "items":
    [
      {
        "itemId":"3",
        "title":"Example Item Title 3",
        "itemType":"Product",
        "hidden":false,
        "fromDate":0,
        "toDate":0,
        "nameValues":
        [
          {"name":"imageUrl","value":"http://webshop.example.com/img3.jpg"},
          {"name":"price","value":"10"},
          {"name":"categoryId","value":"2"},
          {"name":"categoryId","value":"8"}
        ]
      },
      {
        "itemId":"3",
        "title":"Example Item Title 3",
        "itemType":"Product",
        "hidden":false,
        "fromDate":0,
        "toDate":0,
        "nameValues":
        [
          {"name":"imageUrl","value":"http://webshop.example.com/img4.jpg"},
          {"name":"price","value":"15"},
          {"name":"categoryId","value":"2"},
          {"name":"categoryId","value":"9"}
        ]
      }
    ],
    "itemIds":["1","2"],
    "predictionValues" : [ 4.2068971, 3.80689716 ]
  }

Scenario information

 It is possible to get the list of currently available scenarios with some of its traits. For a detailed list of the traits please read our Java documentation.

Example request - HTTP GET:

Get recommendation API endpoint
<baseurl>/scenarioInfo

Sample answer:

 [{
    "id": 42,
    "apiName": "TEST_1",
    "humanReadableName": "Third magical test coupon",
    "description": null,
    "order": 0,
    "numberLimit": 12,
    "type": "email",
    "modifierName": "Gabor Bernat"
}, {
    "id": 6,
    "apiName": "basic",
    "humanReadableName": "basic",
    "description": null,
    "order": 1,
    "numberLimit": 12,
    "type": "web",
    "modifierName": "Gabor Bernat"
}]
  • No labels