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

ParameterTypeDescription
accountIdString

Mandatory. The trackId of the Marketing Automation account.

placementIdLongMandatory. How to find the desired placement ID is described here.
userIdString

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.

productStringOptional. 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.
pcatString

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

mediacodeString

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

The media code must be configured in Mapp Q3.
keywordStringOptional. 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

ParameterTypeDescription
accountIdString

Mandatory. The trackId of the Marketing Automation account.

placementIdLongMandatory. How to find the desired placement ID is described here.
productStringOptional. 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.
pcatString

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

mediacodeString

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

The media code must be configured in Mapp Q3.
keywordStringOptional. 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 CodeMessageDescription
200OK

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.