--- title: "Using the Recommendation API" slug: "using-the-recommendation-api" updated: 2024-03-20T11:00:51Z published: 2024-03-20T11:00:51Z canonical: "docs.mapp.com/using-the-recommendation-api" --- > ## Documentation Index > Fetch the complete documentation index at: https://docs.mapp.com/llms.txt > Use this file to discover all available pages before exploring further. # Using the Recommendation API 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](/v1/docs/recommendation-rest-api-get-started). | | 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. > [!TIP] > 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. > [!WARNING] > 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](https://webtrekkapi.docs.apiary.io/#reference/recommendation-items/recommendations-collection/get-a-recommendation-items-list) --- ## 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](/v1/docs/intelligent-tracking-prevention-itp-21), the API calls differ as follows. > [!WARNING] > 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](/v1/docs/recommendation-rest-api-get-started). | | 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. > [!WARNING] > 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](https://webtrekkapi.docs.apiary.io/#reference/recommendation-items/recommendations-collection/get-a-recommendation-items-list) --- ## 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 ```json [    {        "reco": [            {                "value": " ",                "identifier": "",                "type": ""            },            {                "value": " ",                "identifier": "",                "type": ""            }        ]    },    {        "reco": [            {                "value": " ",                "identifier": "",                "type": ""            }        ]    } ] ``` #### Example Response ```json [    {        "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. | 1. Log in Mapp Q3. 2. Go to *"Configuration > System Configuration > Data Collection"*. 3. Your account ID is the one in the field Your **Track ID**.