CustomerProfiles / Client / search_recommendations

search_recommendations¶

CustomerProfiles.Client.search_recommendations(**kwargs)¶

Retrieves recommendations for a profile in a specific domain. The profile is identified using a search key, which consists of a KeyName and a KeyValues list. The KeyName can be a predefined key (for example, _profileId, _phone, _email) or a custom-defined key.

The search key must match exactly one profile. If no profile matches the search key, the operation returns a ResourceNotFoundException. If more than one profile matches the search key, the operation returns a BadRequestException. You can use the SearchProfiles API to review the matching profiles.

Request Syntax

response = client.search_recommendations(
    DomainName='string',
    KeyName='string',
    KeyValues=[
        'string',
    ],
    Recommender={
        'Name': 'string',
        'Filters': [
            {
                'Name': 'string',
                'Values': {
                    'string': 'string'
                }
            },
        ],
        'PromotionalFilters': [
            {
                'Name': 'string',
                'Values': {
                    'string': 'string'
                },
                'PromotionName': 'string',
                'PercentPromotedItems': 123
            },
        ]
    },
    CandidateIds=[
        'string',
    ],
    Context={
        'string': 'string'
    },
    Diversity={
        'Enabled': True|False,
        'Values': {
            'string': 123
        }
    },
    Metadata={
        'Columns': [
            'string',
        ]
    },
    MaxRecommendations=123
)

Parameters:

DomainName (string) –
[REQUIRED]

The unique name of the domain.
KeyName (string) –
[REQUIRED]

A searchable identifier of a customer profile. You can use a predefined key, such as _profileId, _phone, or _email, or a custom-defined key.
KeyValues (list) –
[REQUIRED]

A list of key values. Provide one value for each field of the search key.
- (string) –
Recommender (dict) –
[REQUIRED]

The recommender used to generate the recommendations.
- Name (string) – [REQUIRED]
  
  The unique name of the recommender.
- Filters (list) –
  
  A list of filters to apply to the returned recommendations. Filters define criteria for including or excluding items from the recommendation results.
  - (dict) –
    
    A filter that specifies criteria for including or excluding items from recommendations.
    - Name (string) –
      
      The name of the recommender filter to apply.
    - Values (dict) –
      
      The values to use when filtering recommendations. For each placeholder parameter in your filter expression, provide the parameter name (in matching case) as a key and the filter value(s) as the corresponding value. Separate multiple values for one parameter with a comma.
      - (string) –
        
        (string) –
- PromotionalFilters (list) –
  
  A list of promotional filters to apply to the recommendations. Promotional filters allow you to promote specific items within a configurable subset of recommendation results.
  - (dict) –
    
    Contains information on a promotion. A promotion defines additional business rules that apply to a configurable subset of recommended items.
    - Name (string) –
      
      The name of the recommender filter to use for the promotion.
    - Values (dict) –
      
      The values to use when promoting items. For each placeholder parameter in your promotion’s filter expression, provide the parameter name (in matching case) as a key and the filter value(s) as the corresponding value. Separate multiple values for one parameter with a comma.
      - (string) –
        
        (string) –
    - PromotionName (string) –
      
      The name of the promotion.
    - PercentPromotedItems (integer) –
      
      The percentage of recommended items to apply the promotion to.
CandidateIds (list) –
A list of item IDs to rank for the user. Use this when you want to re-rank a specific set of items rather than getting recommendations from the full item catalog. Required for personalized-ranking use cases.
- (string) –
Context (dict) –
The contextual metadata used to provide dynamic runtime information to tailor recommendations.
- (string) –
  - (string) –
Diversity (dict) –
Runtime diversity configuration for this request. Enables diversity-aware recommendations and optionally supplies values for placeholder-based diversity caps configured on the recommender.
- Enabled (boolean) – [REQUIRED]
  
  Whether diversity-aware recommendations are enabled for this request.
- Values (dict) –
  
  An optional map of placeholder name to integer cap value used to resolve $name placeholders defined in the recommender’s DiversityConfig at inference time. Up to 2 entries are supported.
  - (string) –
    - (integer) –
Metadata (dict) –
Configuration for metadata to include in recommendation responses.
- Columns (list) –
  
  A list of metadata column names from your Items dataset to include in the recommendation response.
  - (string) –
MaxRecommendations (integer) – The maximum number of recommendations to return. The default value is 5.

Return type:

dict

Returns:

Response Syntax

{
    'ProfileId': 'string',
    'Recommendations': [
        {
            'CatalogItem': {
                'Id': 'string',
                'Name': 'string',
                'Code': 'string',
                'Type': 'string',
                'Category': 'string',
                'Description': 'string',
                'AdditionalInformation': 'string',
                'ImageLink': 'string',
                'Link': 'string',
                'CreatedAt': datetime(2015, 1, 1),
                'UpdatedAt': datetime(2015, 1, 1),
                'Price': 'string',
                'Attributes': {
                    'string': 'string'
                }
            },
            'Score': 123.0
        },
    ]
}

Response Structure

(dict) –
- ProfileId (string) –
  
  The unique identifier of the profile for which to retrieve recommendations.
- Recommendations (list) –
  
  List of recommendations generated by the recommender.
  - (dict) –
    
    Represents a single recommendation generated by the recommender system.
    - CatalogItem (dict) –
      
      The catalog item being recommended, including its complete details and attributes.
      - Id (string) –
        
        The unique identifier for the catalog item.
      - Name (string) –
        
        The display name of the catalog item.
      - Code (string) –
        
        The product code or SKU of the catalog item.
      - Type (string) –
        
        The type classification of the catalog item.
      - Category (string) –
        
        The category to which the catalog item belongs.
      - Description (string) –
        
        A detailed description of the catalog item.
      - AdditionalInformation (string) –
        
        Supplementary information about the catalog item beyond the basic description.
      - ImageLink (string) –
        
        The URL link to the item’s image.
      - Link (string) –
        
        The URL link to the item’s detailed page or external resource.
      - CreatedAt (datetime) –
        
        The timestamp when the catalog item was created.
      - UpdatedAt (datetime) –
        
        The timestamp when the catalog item was last updated.
      - Price (string) –
        
        The price of the catalog item.
      - Attributes (dict) –
        
        Additional attributes or properties associated with the catalog item stored as key-value pairs.
        
        (string) –
        
        (string) –
    - Score (float) –
      
      Recommendation Score between 0 and 1.

search_recommendations¶

Request Syntax

Response Syntax

Response Structure

Exceptions