Contents x
      Using the Recommendation API
      • 5 Minutes to read
      • Print
      • Dark
        Light
      Contents

      Using the Recommendation API

      • 5 Minutes to read
      • Print
      • Dark
        Light
      Article summary

      This chapter describes how to place API calls to get the information you need. There are two ways to do this:

      • Using the API via the Mapp Server

      • Using the API with your own Tracking Domain

      Recommendation API via the Mapp Server

      This chapter describes how to make API calls and which query parameters are required to obtain corresponding recommendation items. Optional query parameters can be added to refine your request.

      URI Syntax

      {server}/dmp/recos/v2?accountId={accountId}&placementId={placementId}&userId={userId}&product={product}&pcat2={productCategory2}&mediacode={mediacode}&keyword={keyword}

      Query Parameters

      Parameter

      Type

      Description

      accountId

      String

      Mandatory. The trackId of the Marketing Automation account. How to get the account ID

      placementId

      Long

      Mandatory. How to find the desired placement ID is described here.

      userId

      String

      Optional. The userId is the Mapp device everId. Depending on your tracking setup you can get this ID from the first-party or third-party cookie. The userId is required for personalized campaign rules such as "last seen products". Furthermore, it is mandatory if you plan targeting based on Mapp segments.

      Always include the userId.

      product

      String

      Optional. The identifier used to track the "PRODUCT" object. It should be unique for each product. This parameter is used to recommend products according to cross-selling rules.

      pcat

      String

      Optional. Filters the results of the recommendation according to the value of the specified product category. Multiple pcat parameters are supported.

      Example

      This example would return all entries that are pcat1 AND pcat8.

      dmp/recos/v2?accountId=999955867561122&placementId=asdasdasdasdf&pcat1=women.shoes&pcat8=casual

      Example

      This can be compared to the result of only one pcat matching.

      dmp/recos/v2?accountId=999955867561122&placementId=asdasdasdasdf&pcat8=casual

      Example

      This example gives you all entries that are pcat8 but NOT pcat1.

      dmp/recos/v2?accountId=999955867561122&placementId=asdasdasdasdf&pcat1=!women.shoes&pcat8=casual

      mediacode

      String

      Optional. The media code value of the campaign from which the user comes.

      The media code must be configured in Mapp Q3.

      keyword

      String

      Optional. The SEM keyword that takes the user to the website.

      Example

      https://reco.webtrekk.com/dmp/recos/v2?accountId=12345678&placementId=9876543

      View in Apiary

      Recommendation API with your own Tracking Domain

      If you want to use your own tracking domain and third-party cookies due to ITP 2.x, the API calls differ as follows.

      In this case separate activation is required. Please contact your Mapp Intelligence.

      This chapter describes how you can make API calls and which query parameters are required to obtain corresponding recommendation items while using your own tracking domain.

      URI Syntax

      {server}/dmp/recos/v2?accountId={accountId}&placementId={placementId}&product={product}&pcat2={productCategory2}&mediacode={mediacode}&keyword={keyword}

      Query Parameters

      Parameter

      Type

      Description

      accountId

      String

      Mandatory. The trackId of the Marketing Automation account. How to get the account ID

      placementId

      Long

      Mandatory. How to find the desired placement ID is described here.

      product

      String

      Optional. The identifier used to track the "PRODUCT" object. It should be unique for each product. This parameter is used to recommend products according to cross-selling rules or to exclude products from the recommendation results.

      pcat

      String

      Optional. Filters the results of the recommendation according to the value of the specified product category. Multiple pcat parameters are supported.

      Example

      This example would return all entries that are pcat1 AND pcat8.

      dmp/recos/v2?accountId=999955867561122&placementId=asdasdasdasdf&pcat1=women.shoes&pcat8=casual

      Example

      This can be compared to the result of only one pcat matching.

      dmp/recos/v2?accountId=999955867561122&placementId=asdasdasdasdf&pcat8=casual

      Example

      This example gives you all entries that are pcat8 but NOT pcat1.

      dmp/recos/v2?accountId=999955867561122&placementId=asdasdasdasdf&pcat1=!women.shoes&pcat8=casual

      mediacode

      String

      Optional. The media code value of the campaign from which the user comes.

      The media code must be configured in Mapp Q3.

      keyword

      String

      Optional. The SEM keyword that takes the user to the website.

      Example

      https://{{OWN_TRACKING_DOMAIN}}/dmp/recos/v2?accountId=12345678&placementId=9876543

      View in Apiary

      GET Recommendation Items

      Using the API via the Mapp server

      GET https://reco.webtrekk.com/dmp/recos/v2?accountId=12345678&placementId=9876543

      Using the API with your own tracking domain

      GET https:// {{OWN_TRACKING_DOMAIN}}/dmp/recos/v2?accountId=12345678&placementId=9876543

      Headers

      content-type: application/json

      Response Syntax

      [
    {
        "reco": [
            {
                "value": "<value of product category 1> ",
                "identifier": "<name of product category 1>",
                "type": "<type of product category 1>"
            },
            {
                "value": "<value of product category n> ",
                "identifier": "<name of product category n>",
                "type": "<type of product category n>"
            }
        ]
    },
    {
        "reco": [
            {
                "value": "<value of product category 1> ",
                "identifier": "<name of product category 1>",
                "type": "<type of product category 1>"
            }
        ]
    }
]

      Example Response

      [
    {
        "reco": [
            {
                "value": "http://pics.shop.de/Shop/PicPOV_MainView/994CC1B916_939.jpg",
                "identifier": "MA product image URL",
                "type": "pictureUrl"
            },
            {
                "value": "http://www.shop.de/ladieswear/jeans/straight/darkdenimstretch994CC1B916939",
                "identifier": "url",
                "type": "url"
            },
            {
                "value": "CampaignDmpCamp",
                "identifier": "campaignTitle",
                "type": "text"
            },
            {
             "value": "4054874992127", 
 "identifier": "id", 
 "type": "text" 
          
            }
            
        ]
    },
    {
        "reco": [
            {
                "value": "http://pics.shop.de/Shop/PicPOV_MainView/995EE1B900_001.jpg",
                "identifier": "MA product image URL",
                "type": "pictureUrl"
            },
            {
                "value": "http://www.shop.de/ladieswear/trousers/straight/cottonstretchpants995EE1B900_001",
                "identifier": "url",
                "type": "url"
            },
            {
                "value": "CampaignNewDmpCamp",
                "identifier": "campaignTitle",
                "type": "text"
            },
            {
             "value": "4055981251855", 
 "identifier": "id", 
 "type": "text" 

            
          
            }
        ]
    }
]

      Error Codes

      Error Code

      Message

      Description

      200

      OK

      The response body includes all found recommendation items.

      400


      The placement ID could not be found. This means either that the placement ID does not exist or that it is not a Reco API placement.

      401


      The account ID could not be found.

      403


      The Recommendation API is not activated for this account.

      Was this article helpful?
      Related articles
      What's Next