GuidesDiscussions
Guides

REST

Suggest Edits

📘

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

https://<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

https://mywebshop-ams.gravityrd-services.com/grrec-mywebshop-war/WebshopServlet

Add events

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:

[
    {
        "itemId":"sampleItemId1",
        "userId":"sampleUserId1",
        "cookieId":"sampleCookieId1",
        "eventType":"BUY",
        "time": 1525625386,
        "nameValues":
        [
            {"name":"unitPrice","value":"199.9"},
            {"name":"quantity","value":"1"},
            {"name":"orderId","value":"order-0123"}
        ]
    },
    {
        "itemId":"sampleItemId2",
        "userId":"sampleUserId2",
        "cookieId":"sampleCookieId2",
        "eventType":"BUY",
        "time": 1525625386,
        "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 (touchpoint)
numberLimitThe (maximum) number of recommended items
resultNameValueAn item attribute name to be returned
(optional) itemIdThe identifier of the current item (for item-to-item recommendations)
OtherA custom request name and value, for example for filtering
(optional) splitGroup(optional) In case there are multiple types of recommendations to be served, (for example: Yusp is competing against an other recommendation service vendor via A/B testing) then splitGroup context property needs to be added to the recommendation request.

The order of the boxes in the request is important. The box / recommendation should be ordered top down. Meaning most relevant box / recommendation are normally ordered top down, in order to create more clicks and generate more revenue.

API endpoint - HTTP POST:
Get recommendation API endpoint

<baseurl>/getItemRecommendation?async=true

Example HTTP request body:

{  
      "cookieId":"1512467a76a-5cc340e5fa6ba5c2",
      "numberLimit":5,
      "scenarioId":"MAIN_PAGE",
      "nameValues":[  
         {  
            "name":"categoryId",
            "value":"\/automoto\/cars"
         },
         ...
      ]
}

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:

<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 ]
 }

Privacy-related

Query user metadata

Example request based on userId - HTTP GET

<baseurl>/getUser?userId=120

Example request based on cookieId - HTTP GET

<baseurl>/getUser?cookieId=1606543fc24-0e4cacafec3db9dc

Example HTTP response body:

{
    "userId": "120",
    "hidden": false,
    "nameValues": [
        {"name": "md5_email", "value": "2dff02796543fc99709b59096ff80ff3"}
    ]
}

Query event history

Example request based on userId - HTTP GET

<baseurl>/getEvents?userId=120

Example request based on cookieId - HTTP GET

<baseurl>/getEvents?cookieId=1606543fc24-0e4cacafec3db9dc

Example HTTP response body:

[{
        "itemId": "4999933",
        "userId": "120",
        "cookieId": "1606543fc24-0e4cacafec3db9dc",
        "time": 1525326427,
        "eventType": "BUY",
        "nameValues": [{
                "name": "quantity",
                "value": "1"
            },
            {
                "name": "unitPrice",
                "value": "37.5"
            },
            {
                "name": "orderId",
                "value": "44000437"
            },
            {
                "name": "_skipped",
                "value": "4"
            }
        ],
        "recommendationId": null
    },
    {
        "itemId": "4999933",
        "userId": "120",
        "cookieId": "1606543fc24-0e4cacafec3db9dc",
        "time": 1525625386,
        "eventType": "VIEW",
        "nameValues": [{
            "name": "_skipped",
            "value": "7"
        }],
        "recommendationId": null
}]

Delete full event history

Example request - HTTP GET

<baseurl>/optOut?cookieId=1606543fc24-0e4cacafec3db9dc

The response is an empty HTTP 200 unless the request is invalid.

Delete full user metadata and event history

Example request - HTTP GET

<baseurl>/optOut?userId=120

The response is an empty HTTP 200 unless the request is invalid.

Performance-related

General

  • Compressed uploads will not be accepted because of security considerations.
  • Issue requests in parallel and use HTTP keep-alive.

Null or empty values omission

  • In production setup null or empty values should not be submitted against API in order to improve performance.

Error-handling

HTTP Error 413 Request Entity Too Large

  • Default limit is 1MB per request. Split data to stay below 1M.
  • In most cases we suggest max 100-200 items/users/events in one batch.

FAQ

Is it possible to use an array of strings in the nameValues?

"nameValues":
   [
    {"name":"field","value":["string_1", "string_2"]},
   ...
]

Array of strings in nameValues can be posted as follows:

"nameValues": 
    [
    {"name": "field", "value": "string_1"},
    {"name": "field", "value": "string_2"},
    ...
]

Updated about 4 years ago