Sample API requests
This article shows some example API requests and associated responses. Each example shows a base recommendations scenario along with other response modification features such as filtering, paging, selecting an alternative algorithm, and more. If you want to try these examples on your Intelligent Recommendations endpoint, be sure to replace the endpoint name (DNS part) and adjust the parameters to your data.
Note
The count parameter will control the number of items returned in each response. Examples will have the count set to 5 for clarity and brevity. For more information on ways to construct your API requests, see Intelligent Recommendations API and Quick start guide for calling the API.
Examples
Here are some examples that you can test with your Intelligent Recommendations account:
- Get New Items
- Get Popular Items
- Get Similar Items
- Get User Picks
- Next Best Action (Cart)
- Metadata Tagging and User Bucketing
- How to use the AlgoType parameter
- How to use the Refinements parameter
- API Status Codes
If you run into errors while testing the responses, see Error logs.
Get new items
The New Items API returns a list of products ordered by release date.
The API request looks like this:
https://ir-example.mir.prod.reco.microsoft.com/Reco/V1.0/New?modeling=adw&Count=5
A successful response looks like this:
{
"id": "Lists",
"name": "Lists",
"version": "v1.0",
"interactionsVersion": "20220104115104",
"items": [
{
"id": "70000",
"trackingId": "00000000-0000-0000-0000-000000000003"
},
{
"id": "70002",
"trackingId": "00000000-0000-0000-0000-000000000003"
},
{
"id": "70003",
"trackingId": "00000000-0000-0000-0000-000000000003"
},
{
"id": "70004",
"trackingId": "00000000-0000-0000-0000-000000000003"
},
{
"id": "70005",
"trackingId": "00000000-0000-0000-0000-000000000003"
}
],
"title": "New",
"longTitle": "New",
"titleId": 3,
"pagingInfo": {
"totalItems": 278
},
"status": "Success"
}
Get new items while skipping the top 3
You can skip items in a list by appending "SkipItems" to the request.
The API request looks like this:
https://ir-example.mir.prod.reco.microsoft.com/Reco/V1.0/New?modeling=adw&Count=5&SkipItems=3
A successful response looks like this:
{
"id": "Lists",
"name": "Lists",
"version": "v1.0",
"interactionsVersion": "20220104115104",
"items": [
{
"id": "70004",
"trackingId": "00000000-0000-0000-0000-000000000003"
},
{
"id": "70005",
"trackingId": "00000000-0000-0000-0000-000000000003"
},
{
"id": "70006",
"trackingId": "00000000-0000-0000-0000-000000000003"
},
{
"id": "66001",
"trackingId": "00000000-0000-0000-0000-000000000003"
},
{
"id": "66002",
"trackingId": "00000000-0000-0000-0000-000000000003"
}
],
"title": "New",
"longTitle": "New",
"titleId": 3,
"pagingInfo": {
"totalItems": 278
},
"status": "Success"
}
Get popular items
The Get Popular Items API returns a list of items ordered by count of interactions, such as transaction, purchase, view, select, or download. Whatever a user-item interaction means in your business, the first item in the list is the one that has the most interactions, and the rest are ordered in descending order.
The API request looks like this:
https://ir-example.mir.prod.reco.microsoft.com/Reco/V1.0/Popular?modeling=adw&Count=5
A successful response looks like this:
{
"id": "Lists",
"name": "Lists",
"version": "v1.0",
"interactionsVersion": "20220104115104",
"items": [
{
"id": "65106",
"trackingId": "00000000-0000-0000-0000-000000000003"
},
{
"id": "62604",
"trackingId": "00000000-0000-0000-0000-000000000003"
},
{
"id": "70006",
"trackingId": "00000000-0000-0000-0000-000000000003"
},
{
"id": "63503",
"trackingId": "00000000-0000-0000-0000-000000000003"
},
{
"id": "62452",
"trackingId": "00000000-0000-0000-0000-000000000003"
}
],
"title": "Popular",
"longTitle": "Popular",
"titleId": 5,
"pagingInfo": {
"totalItems": 278
},
"status": "Success"
}
Get popular items in a specific category
You can define categories within the ItemCategories data entity. For more information, see Data contract overview.
The API request when searching for most popular clothing items looks like this:
https://ir-example.mir.prod.reco.microsoft.com/Reco/V1.0/Popular?modeling=adw&Count=5&Category=Clothing
A successful response looks like this:
{
"id": "Lists",
"name": "Lists",
"version": "v1.0",
"interactionsVersion": "20220104115104",
"items": [
{
"id": "62604",
"trackingId": "00000000-0000-0000-0000-000000000003"
},
{
"id": "62452",
"trackingId": "00000000-0000-0000-0000-000000000003"
},
{
"id": "62502",
"trackingId": "00000000-0000-0000-0000-000000000003"
},
{
"id": "62606",
"trackingId": "00000000-0000-0000-0000-000000000003"
},
{
"id": "63402",
"trackingId": "00000000-0000-0000-0000-000000000003"
}
],
"title": "Popular",
"longTitle": "Popular",
"titleId": 5,
"pagingInfo": {
"totalItems": 95
},
"status": "Success"
}
Get popular items in a specific category with a discrete filter
You can define filters within the ItemAndVariantFilters data entity. For more information, see Data contract overview.
The API request looks like this:
https://ir-example.mir.prod.reco.microsoft.com/Reco/V1.0/Popular?modeling=adw&Count=5&Category=Clothing&Size=S
A successful response looks like this:
{
"id": "Lists",
"name": "Lists",
"version": "v1.0",
"interactionsVersion": "20220104115104",
"items": [
{
"id": "61453",
"trackingId": "00000000-0000-0000-0000-000000000003"
},
{
"id": "62104",
"trackingId": "00000000-0000-0000-0000-000000000003"
},
{
"id": "62100",
"trackingId": "00000000-0000-0000-0000-000000000003"
},
{
"id": "62103",
"trackingId": "00000000-0000-0000-0000-000000000003"
},
{
"id": "61406",
"trackingId": "00000000-0000-0000-0000-000000000003"
}
],
"title": "Popular",
"longTitle": "Popular",
"titleId": 5,
"pagingInfo": {
"totalItems": 32
},
"status": "Success"
}
Get popular items in a specific category while filtering for a range of values
For more information on the syntax of filtering by range, see the guide to range filters.
The API request looks like this:
https://ir-example.mir.prod.reco.microsoft.com/Reco/V1.0/Popular?modeling=adw&Count=10&Category=Clothing&$filter=rating gt 2 and rating lt 5
A successful response looks like this:
{
"id": "Lists",
"name": "Lists",
"version": "v1.0",
"interactionsVersion": "20220104115104",
"items": [
{
"id": "62604",
"trackingId": "00000000-0000-0000-0000-000000000003"
},
{
"id": "62452",
"trackingId": "00000000-0000-0000-0000-000000000003"
},
{
"id": "62502",
"trackingId": "00000000-0000-0000-0000-000000000003"
},
{
"id": "62507",
"trackingId": "00000000-0000-0000-0000-000000000003"
},
{
"id": "62106",
"trackingId": "00000000-0000-0000-0000-000000000003"
}
],
"title": "Popular",
"longTitle": "Popular",
"titleId": 5,
"pagingInfo": {
"totalItems": 5
},
"status": "Success"
}
Get similar items
The Similar Items API provides contextual recommendations based on specific seed items. The seed item is the pivot point that product suggestions will be based on. The API request given for seed Item Id immediately follows Similar/. For example, a stripped sweater seed item has different product suggestions when compared to a men's suit jacket.
The API request looks like this:
https://ir-example.mir.prod.reco.microsoft.com/Reco/V1.0/Similar/64702?modeling=adw&Count=5
A successful response looks like this:
{
"id": "Related",
"name": "Related",
"version": "v1.0",
"interactionsVersion": "20220104115104",
"items": [
{
"id": "63102",
"trackingId": "00000000-0000-0000-0000-000000000003"
},
{
"id": "62106",
"trackingId": "00000000-0000-0000-0000-000000000003"
},
{
"id": "61511",
"trackingId": "00000000-0000-0000-0000-000000000003"
},
{
"id": "63503",
"trackingId": "00000000-0000-0000-0000-000000000003"
},
{
"id": "68100",
"trackingId": "00000000-0000-0000-0000-000000000003"
}
],
"title": "People also like",
"longTitle": "People also like",
"titleId": 1,
"pagingInfo": {
"totalItems": 138
},
"status": "Success"
}
Get similar items with shuffling
To prevent users from seeing the same recommendations over and over again, Intelligent Recommendations has a weighted shuffle feature that slightly changes the order of items without significantly affecting the relevance. Results can be shuffled by adding the refinement enableshuffling. You can learn more about refinements and their different types here.
The API request looks like this:
https://ir-example.mir.prod.reco.microsoft.com/Reco/V1.0/Similar/64702?modeling=adw&Count=5&Refinements=EnableShuffling
A successful response looks like this:
{
"id": "Related",
"name": "Related",
"version": "v1.0",
"interactionsVersion": "20220104115104",
"items": [
{
"id": "62403",
"trackingId": "00000000-0000-0000-0000-000000000003"
},
{
"id": "61511",
"trackingId": "00000000-0000-0000-0000-000000000003"
},
{
"id": "71603",
"trackingId": "00000000-0000-0000-0000-000000000003"
},
{
"id": "64201",
"trackingId": "00000000-0000-0000-0000-000000000003"
},
{
"id": "62452",
"trackingId": "00000000-0000-0000-0000-000000000003"
}
],
"title": "People also like",
"longTitle": "People also like",
"titleId": 1,
"pagingInfo": {
"totalItems": 138
},
"status": "Success"
}
Bring The Look
This API request takes a composite image and returns a list of recommended items that are visually similar to the items listed in the composite image. A composite image and its itemIds mapping can be configured using the Image-to-Item Data Entity here..
The API request looks like this for a given composite image (642):
https://ir-example.mir.prod.reco.microsoft.com/Reco/V1.0/Similar/642?AlgoType=BringSimilarItems
A successful response looks like this:
{
"id": "Related",
"name": "Related",
"version": "v1.0",
"interactionsVersion": "20220104115104",
"items": [
{
"id": "62403",
"trackingId": "00000000-0000-0000-0000-000000000003"
},
{
"id": "61511",
"trackingId": "00000000-0000-0000-0000-000000000003"
},
{
"id": "71603",
"trackingId": "00000000-0000-0000-0000-000000000003"
},
{
"id": "64201",
"trackingId": "00000000-0000-0000-0000-000000000003"
},
{
"id": "62452",
"trackingId": "00000000-0000-0000-0000-000000000003"
}
],
"title": "Bring Similar Items",
"longTitle": "Bring Similar Items",
"titleId": 1,
"pagingInfo": {
"totalItems": 138
},
"status": "Success"
}
Complete similar styles
This API request takes an item id and returns a list of composite pictures IDs that contain the item or contain different similar item, where the similarity is based on visual style.
The API request looks like this for a given item ID (64702):
https://ir-example.mir.prod.reco.microsoft.com/Reco/V1.0/Similar/64702?AlgoType=CompleteSimilarStyles
A successful response looks like this:
{
"id": "Related",
"name": "Related",
"version": "v1.0",
"interactionsVersion": "20220104115104",
"items": [
{
"id": "403",
"trackingId": "00000000-0000-0000-0000-000000000003"
},
{
"id": "511",
"trackingId": "00000000-0000-0000-0000-000000000003"
},
{
"id": "603",
"trackingId": "00000000-0000-0000-0000-000000000003"
},
{
"id": "201",
"trackingId": "00000000-0000-0000-0000-000000000003"
},
{
"id": "452",
"trackingId": "00000000-0000-0000-0000-000000000003"
}
],
"title": "Complete Similar Styles",
"longTitle": "Complete Similar Styles",
"titleId": 1,
"pagingInfo": {
"totalItems": 138
},
"status": "Success"
}
Complete similar items
This API request takes an item id, finds composite pictures that contain the item or a visually similar item, and returns a list of item IDs extracted from those composite pictures.
The API request looks like this for a given item ID (64702):
https://ir-example.mir.prod.reco.microsoft.com/Reco/V1.0/Similar/64702?AlgoType=CompleteSimilarItems
A successful response looks like this:
{
"id": "Related",
"name": "Related",
"version": "v1.0",
"interactionsVersion": "20220104115104",
"items": [
{
"id": "62403",
"trackingId": "00000000-0000-0000-0000-000000000003"
},
{
"id": "61511",
"trackingId": "00000000-0000-0000-0000-000000000003"
},
{
"id": "71603",
"trackingId": "00000000-0000-0000-0000-000000000003"
},
{
"id": "64201",
"trackingId": "00000000-0000-0000-0000-000000000003"
},
{
"id": "62452",
"trackingId": "00000000-0000-0000-0000-000000000003"
}
],
"title": "Complete Similar Items",
"longTitle": "Complete Similar Items",
"titleId": 1,
"pagingInfo": {
"totalItems": 138
},
"status": "Success"
}
Get user picks
The Picks API returns a personalized set of recommendations based on the interactions history of a given user.
The API request looks like this:
https://ir-example.mir.prod.reco.microsoft.com/Reco/V1.0/Picks?modeling=adw&UserId=ID1644&Count=5
A successful response looks like this:
{
"id": "Picks",
"name": "Picks",
"version": "v1.0",
"items": [
{
"id": "68100",
"trackingId": "00000000-0000-0000-0000-000000000003"
},
{
"id": "62500",
"trackingId": "00000000-0000-0000-0000-000000000003"
},
{
"id": "61504",
"trackingId": "00000000-0000-0000-0000-000000000003"
},
{
"id": "65103",
"trackingId": "00000000-0000-0000-0000-000000000003"
},
{
"id": "61401",
"trackingId": "00000000-0000-0000-0000-000000000003"
}
],
"title": "Picks for you",
"longTitle": "Picks for you",
"titleId": 6,
"personalizationConfidence": 1.0,
"pagingInfo": {
"totalItems": 139
},
"status": "Success"
}
Get user picks using sessionId
The Picks API returns personalized recommendations based on the current views in a session, regardless of whether the user is known (signed-in) or unknown (anonymous). The sessionId parameter identifies the products a user has viewed in their current browsing session, and the API returns a list of recommendations based on the recent viewing activity of the signed-in or anonymous user.
The modified Picks API request replaces userId with the sessionId and uses the AlgoType "Recent Views", given as follows:
https://ir-example.mir.prod.reco.microsoft.com/Reco/V1.0/picks?SessionId=123&AlgoType=RecentViews.
Note
The SessionId parameter should be used in Similar API request in the given session before calling the picks API, otherwise the recent activity recommendations return empty results.
When using the Similar API:
https://ir-example.mir.prod.reco.microsoft.com/Reco/V1.0/Similar/64702?SessionId=123
a successful recent activity picks response is as follows:
```json
{
"id": "Picks",
"name": "Picks",
"version": "v1.0",
"items": [
{
"id": "68100",
"trackingId": "00000000-0000-0000-0000-000000000003"
},
{
"id": "62500",
"trackingId": "00000000-0000-0000-0000-000000000003"
},
{
"id": "61504",
"trackingId": "00000000-0000-0000-0000-000000000003"
},
{
"id": "65103",
"trackingId": "00000000-0000-0000-0000-000000000003"
},
{
"id": "61401",
"trackingId": "00000000-0000-0000-0000-000000000003"
}
],
"title": "Picks for you",
"longTitle": "Picks for you",
"titleId": 6,
"personalizationConfidence": 1.0,
"pagingInfo": {
"totalItems": 139
},
"status": "Success"
}
Note
The SessionId parameter has been added to the API request in this example.
Next Best Action
The API request returns a list of items that are most often purchased together with the seed item(s) in a user's cart (or coupled together, when not in a retail cart scenario).
The API request for single seed item/actions is:
https://ir-example.mir.prod.reco.microsoft.com/Reco/V1.0/Cart/64702?AlgoType=DAS&modeling=adw&Count=5
The API request for multiple seed items/actions is:
https://ir-example.mir.prod.reco.microsoft.com/Reco/V1.0/Cart/Items?SeedItemIds=22565300000,41023461-0005-0000-ffff-00ffffffff00,22565300000,22565300001&Count=5
A successful response is:
{
"id": "Cart",
"name": "Cart",
"version": "v1.0",
"items": [
{
"id": "63102",
"trackingId": "00000000-0000-0000-0000-000000000003"
},
{
"id": "62106",
"trackingId": "00000000-0000-0000-0000-000000000003"
},
{
"id": "61511",
"trackingId": "00000000-0000-0000-0000-000000000003"
},
{
"id": "63503",
"trackingId": "00000000-0000-0000-0000-000000000003"
},
{
"id": "68100",
"trackingId": "00000000-0000-0000-0000-000000000003"
}
],
"title": "Frequently bought together",
"longTitle": "Frequently bought together",
"titleId": 2,
"pagingInfo": {
"totalItems": 138
},
"status": "Success"
}
Metadata tagging and user bucketing
Implementing metadata tagging and user bucketing require some configurations to the data contract. See our Guide to metadata tagging and user bucketing for an overview of data contract changes and API examples, including a walkthrough of two common use cases that benefit from metadata tagging and provide some examples with demo data for each.
- To get "most popular items for you" for cold users. To see an example, see the section titled "Get Most Popular Items for you for Cold Users".
- To create a machine learned map of Users' metadata-values. To see an example, see the section titled "Create an ML map of users' metadata values".
How to use the AlgoType parameter
Intelligent Recommendations feature offers multiple algorithms to compute recommendations for various scenarios. If you want to use a specific algorithm other than the default, you can utilize the AlgoType parameter.
Example AlgoTypes
See the AlgoTypes Table for the full list of currently supported AlgoTypes. Examples of AlgoTypes include:
| AlgoType | Definition | Supported API |
|---|---|---|
| RecentPurchases | Picks recommendations are computed based on the most recent purchases of the user. | Only available with the User Picks API. |
| Visual | Item similarities are computed based on visual similarities of catalog images. | Only available with the Similar API. |
| Textual | Item similarities are computed based on textual (language understanding) similarities of catalog textual descriptions. | Only available with the Similar API. |
Constructing an API request with AlgoType
The API request for adding an Algo Type to a get user picks API request looks like this:
https://ir-example.mir.prod.reco.microsoft.com/Reco/V1.0/Picks?AlgoType=RecentPurchases&modeling=adw&UserId=ID1644&Count=5
A successful response looks like this:
{
"id": "Picks",
"name": "Picks",
"version": "v1.0",
"items": [
{
"id": "61100",
"trackingId": "00000000-0000-0000-0000-000000000003"
},
{
"id": "61406",
"trackingId": "00000000-0000-0000-0000-000000000003"
},
{
"id": "63203",
"trackingId": "00000000-0000-0000-0000-000000000003"
},
{
"id": "73401",
"trackingId": "00000000-0000-0000-0000-000000000003"
},
{
"id": "71801",
"trackingId": "00000000-0000-0000-0000-000000000003"
}
],
"title": "Picks for you",
"longTitle": "Picks for you",
"titleId": 6,
"pagingInfo": {
"totalItems": 327
},
"status": "Success"
}
How to use the Refinements parameter
Intelligent Recommendations feature offers various behaviors to compute and return recommendations, but sometimes it's necessary to request a different behavior than the default for a better buying experience. For instance, displaying recommendations only on unpurchased items or preventing the repetition of the same order. The Refinements parameter can be utilized in such cases to achieve the desired recommendation behavior.
See the Refinements Table for the full list of currently supported refinements.
Constructing an API request with Refinements
You can add multiple refinements separated by comma, as long as they aren't contradicting each other. A sample API request for adding a refinement to Similar API can be found here.
API Status Codes
A full list of API status codes, descriptions, and how to resolve errors is as follows:
| Code | Status | Reason | How to resolve |
|---|---|---|---|
| 200 | Success | The API Request was successful. | N/A |
| 200 | EmptyResults | There are recommendations for this seed item (itemId), however, they were all filtered out. | The main reason for filtering is data associated to the items in the catalog. When you anticipate certain products to be returned, it's important to verify their availability dates and ensure that they're correctly configured with the appropriate filtering assignments, such as category, channel, catalog, and availability. |
| 200 | DataDoesNotExist | The seed item (itemId) doesn’t exist in the results. The specified itemId may be missing from the input data or doesn't have sufficient data to have calculated results. | Check that the item: - is valid - belongs in the right channel - Has enough interactions/images/text. For more information, check the Data Contract Formatting Guide. |
| 200 | WaitingForData | When a new modeling component is created, calculation can take some time, and may not be ready to return results. | Check the logs or the modeling status report to see if there are errors. If after 24 hours, the issue persists without error logging, contact us. |
| 400 | UnsupportedRequest | One of the API parameters has an unsupported value, or there's another issue with the API request, such as: an unsupported or disabled scenario. | Check to see whether the header value is different than the actual parameter. For examples of working API requests, go to the top of this article. Different API requests are disabled depending on if your modeling feature set is configured to Standard or Premium. You can also check the modeling status report to see if there are errors with any of the algorithms. |
| 400 | UnsupportedFeature | You're attempting to call an API that is Unsupported based on your current Modeling feature set. | Enable the correct modeling feature set to standard or premium. List of which scenarios are available for each feature set. |
| 401 | Unauthenticated request | Make sure that your tenant has assigned permissions for the service to operate. Follow these steps to check your authentication. | |
| 408 | RequestTimeout | Your request timed out. | Try calling the API request again. |
| 429 | RPS is above the preallocated tier and is at risk of being throttled. | Increase the preallocated RPS capacity to a higher tier or decrease the current RPS. | |
| 500 | Internal server error | There was an error on Intelligent Recommendations side. | This issue can be a temporary one, so try back after a couple of minutes. Check the logs or the modeling status report to see if there are errors. If the issue persists without error logging, contact us. |
| 503 | ServiceUnavailable | The service isn't able to process the account. | Check the logs or the modeling status report to see if there are errors. If the issue persists without error logging, contact us. |
See also
Intelligent Recommendations API
Quick start guide for calling the API
Common logging errors
Data contract overview