| <html><body> |
| <style> |
| |
| body, h1, h2, h3, div, span, p, pre, a { |
| margin: 0; |
| padding: 0; |
| border: 0; |
| font-weight: inherit; |
| font-style: inherit; |
| font-size: 100%; |
| font-family: inherit; |
| vertical-align: baseline; |
| } |
| |
| body { |
| font-size: 13px; |
| padding: 1em; |
| } |
| |
| h1 { |
| font-size: 26px; |
| margin-bottom: 1em; |
| } |
| |
| h2 { |
| font-size: 24px; |
| margin-bottom: 1em; |
| } |
| |
| h3 { |
| font-size: 20px; |
| margin-bottom: 1em; |
| margin-top: 1em; |
| } |
| |
| pre, code { |
| line-height: 1.5; |
| font-family: Monaco, 'DejaVu Sans Mono', 'Bitstream Vera Sans Mono', 'Lucida Console', monospace; |
| } |
| |
| pre { |
| margin-top: 0.5em; |
| } |
| |
| h1, h2, h3, p { |
| font-family: Arial, sans serif; |
| } |
| |
| h1, h2, h3 { |
| border-bottom: solid #CCC 1px; |
| } |
| |
| .toc_element { |
| margin-top: 0.5em; |
| } |
| |
| .firstline { |
| margin-left: 2 em; |
| } |
| |
| .method { |
| margin-top: 1em; |
| border: solid 1px #CCC; |
| padding: 1em; |
| background: #EEE; |
| } |
| |
| .details { |
| font-weight: bold; |
| font-size: 14px; |
| } |
| |
| </style> |
| |
| <h1><a href="recommendationengine_v1beta1.html">Recommendations AI</a> . <a href="recommendationengine_v1beta1.projects.html">projects</a> . <a href="recommendationengine_v1beta1.projects.locations.html">locations</a> . <a href="recommendationengine_v1beta1.projects.locations.catalogs.html">catalogs</a> . <a href="recommendationengine_v1beta1.projects.locations.catalogs.eventStores.html">eventStores</a> . <a href="recommendationengine_v1beta1.projects.locations.catalogs.eventStores.placements.html">placements</a></h1> |
| <h2>Instance Methods</h2> |
| <p class="toc_element"> |
| <code><a href="#predict">predict(name, body=None, x__xgafv=None)</a></code></p> |
| <p class="firstline">Makes a recommendation prediction. If using API Key based authentication,</p> |
| <p class="toc_element"> |
| <code><a href="#predict_next">predict_next(previous_request, previous_response)</a></code></p> |
| <p class="firstline">Retrieves the next page of results.</p> |
| <h3>Method Details</h3> |
| <div class="method"> |
| <code class="details" id="predict">predict(name, body=None, x__xgafv=None)</code> |
| <pre>Makes a recommendation prediction. If using API Key based authentication, |
| the API Key must be registered using the |
| PredictionApiKeyRegistry |
| service. [Learn more](/recommendations-ai/docs/setting-up#register-key). |
| |
| Args: |
| name: string, Required. Full resource name of the format: |
| {name=projects/*/locations/global/catalogs/default_catalog/eventStores/default_event_store/placements/*} |
| The id of the recommendation engine placement. This id is used to identify |
| the set of models that will be used to make the prediction. |
| |
| We currently support three placements with the following IDs by default: |
| |
| * `shopping_cart`: Predicts items frequently bought together with one or |
| more catalog items in the same shopping session. Commonly displayed after |
| `add-to-cart` events, on product detail pages, or on the shopping cart |
| page. |
| |
| * `home_page`: Predicts the next product that a user will most likely |
| engage with or purchase based on the shopping or viewing history of the |
| specified `userId` or `visitorId`. For example - Recommendations for you. |
| |
| * `product_detail`: Predicts the next product that a user will most likely |
| engage with or purchase. The prediction is based on the shopping or |
| viewing history of the specified `userId` or `visitorId` and its |
| relevance to a specified `CatalogItem`. Typically used on product detail |
| pages. For example - More items like this. |
| |
| * `recently_viewed_default`: Returns up to 75 items recently viewed by the |
| specified `userId` or `visitorId`, most recent ones first. Returns |
| nothing if neither of them has viewed any items yet. For example - |
| Recently viewed. |
| |
| The full list of available placements can be seen at |
| https://console.cloud.google.com/recommendation/datafeeds/default_catalog/dashboard (required) |
| body: object, The request body. |
| The object takes the form of: |
| |
| { # Request message for Predict method. |
| "dryRun": True or False, # Optional. Use dryRun mode for this prediction query. If set to true, a |
| # dummy model will be used that returns arbitrary catalog items. |
| # Note that the dryRun mode should only be used for testing the API, or if |
| # the model is not ready. |
| "userEvent": { # UserEvent captures all metadata information recommendation engine needs to # Required. Context about the user, what they are looking at and what action |
| # they took to trigger the predict request. Note that this user event detail |
| # won't be ingested to userEvent logs. Thus, a separate userEvent write |
| # request is required for event logging. |
| # know about how end users interact with customers' website. |
| "productEventDetail": { # ProductEventDetail captures user event information specific to retail # Optional. Retail product specific user event metadata. |
| # |
| # This field is required for the following event types: |
| # |
| # * `add-to-cart` |
| # * `add-to-list` |
| # * `category-page-view` |
| # * `checkout-start` |
| # * `detail-page-view` |
| # * `purchase-complete` |
| # * `refund` |
| # * `remove-from-cart` |
| # * `remove-from-list` |
| # * `search` |
| # |
| # This field is optional for the following event types: |
| # |
| # * `page-visit` |
| # * `shopping-cart-page-view` - note that 'product_event_detail' should be |
| # set for this unless the shopping cart is empty. |
| # |
| # This field is not allowed for the following event types: |
| # |
| # * `home-page-view` |
| # products. |
| "pageCategories": [ # Required for `category-page-view` events. Other event types should not set |
| # this field. |
| # The categories associated with a category page. |
| # Category pages include special pages such as sales or promotions. For |
| # instance, a special sale page may have the category hierarchy: |
| # categories : ["Sales", "2017 Black Friday Deals"]. |
| { # Category represents catalog item category hierarchy. |
| "categories": [ # Required. Catalog item categories. Each category should be a UTF-8 |
| # encoded string with a length limit of 2 KiB. |
| # |
| # Note that the order in the list denotes the specificity (from least to |
| # most specific). |
| "A String", |
| ], |
| }, |
| ], |
| "purchaseTransaction": { # A transaction represents the entire purchase transaction. # Optional. A transaction represents the entire purchase transaction. |
| # Required for `purchase-complete` events. Optional for `checkout-start` |
| # events. Other event types should not set this field. |
| "taxes": { # Optional. All the taxes associated with the transaction. |
| "a_key": 3.14, |
| }, |
| "id": "A String", # Optional. The transaction ID with a length limit of 128 bytes. |
| "currencyCode": "A String", # Required. Currency code. Use three-character ISO-4217 code. This field |
| # is not required if the event type is `refund`. |
| "revenue": 3.14, # Required. Total revenue or grand total associated with the transaction. |
| # This value include shipping, tax, or other adjustments to total revenue |
| # that you want to include as part of your revenue calculations. This field |
| # is not required if the event type is `refund`. |
| "costs": { # Optional. All the costs associated with the product. These can be |
| # manufacturing costs, shipping expenses not borne by the end user, or any |
| # other costs. |
| # |
| # Total product cost such that |
| # profit = revenue - (sum(taxes) + sum(costs)) |
| # If product_cost is not set, then |
| # profit = revenue - tax - shipping - sum(CatalogItem.costs). |
| # |
| # If CatalogItem.cost is not specified for one of the items, CatalogItem.cost |
| # based profit *cannot* be calculated for this Transaction. |
| "a_key": 3.14, |
| }, |
| }, |
| "searchQuery": "A String", # Required for `search` events. Other event types should not set this field. |
| # The user's search query as UTF-8 encoded text with a length limit of 5 KiB. |
| "productDetails": [ # The main product details related to the event. |
| # |
| # This field is required for the following event types: |
| # |
| # * `add-to-cart` |
| # * `add-to-list` |
| # * `checkout-start` |
| # * `detail-page-view` |
| # * `purchase-complete` |
| # * `refund` |
| # * `remove-from-cart` |
| # * `remove-from-list` |
| # |
| # This field is optional for the following event types: |
| # |
| # * `page-visit` |
| # * `shopping-cart-page-view` - note that 'product_details' should be set for |
| # this unless the shopping cart is empty. |
| # * `search` (highly encouraged) |
| # |
| # In a `search` event, this field represents the products returned to the end |
| # user on the current page (the end user may have not finished broswing the |
| # whole page yet). When a new page is returned to the end user, after |
| # pagination/filtering/ordering even for the same query, a new SEARCH event |
| # with different product_details is desired. The end user may have not |
| # finished broswing the whole page yet. |
| # |
| # This field is not allowed for the following event types: |
| # |
| # * `category-page-view` |
| # * `home-page-view` |
| { # Detailed product information associated with a user event. |
| "itemAttributes": { # FeatureMap represents extra features that customers want to include in the # Optional. Extra features associated with a product in the user event. |
| # recommendation model for catalogs/user events as categorical/numerical |
| # features. |
| "numericalFeatures": { # Numerical features. Some examples would be the height/weight of a product, |
| # or age of a customer. |
| # |
| # Feature names must be UTF-8 encoded strings. |
| # |
| # For example: `{ "lengths_cm": {"value":[2.3, 15.4]}, |
| # "heights_cm": {"value":[8.1, 6.4]} }` |
| "a_key": { # A list of float features. |
| "value": [ # Float feature value. |
| 3.14, |
| ], |
| }, |
| }, |
| "categoricalFeatures": { # Categorical features that can take on one of a limited number of possible |
| # values. Some examples would be the brand/maker of a product, or country of |
| # a customer. |
| # |
| # Feature names and values must be UTF-8 encoded strings. |
| # |
| # For example: `{ "colors": {"value": ["yellow", "green"]}, |
| # "sizes": {"value":["S", "M"]}` |
| "a_key": { # A list of string features. |
| "value": [ # String feature value with a length limit of 128 bytes. |
| "A String", |
| ], |
| }, |
| }, |
| }, |
| "id": "A String", # Required. Catalog item ID. UTF-8 encoded string with a length limit of 128 |
| # characters. |
| "originalPrice": 3.14, # Optional. Original price of the product. If provided, this will override |
| # the original price in Catalog for this product. |
| "stockState": "A String", # Optional. Item stock state. If provided, this overrides the stock state |
| # in Catalog for items in this event. |
| "displayPrice": 3.14, # Optional. Display price of the product (e.g. discounted price). If |
| # provided, this will override the display price in Catalog for this product. |
| "availableQuantity": 42, # Optional. Quantity of the products in stock when a user event happens. |
| # Optional. If provided, this overrides the available quantity in Catalog for |
| # this event. and can only be set if `stock_status` is set to `IN_STOCK`. |
| # |
| # Note that if an item is out of stock, you must set the `stock_state` field |
| # to be `OUT_OF_STOCK`. Leaving this field unspecified / as zero is not |
| # sufficient to mark the item out of stock. |
| "quantity": 42, # Optional. Quantity of the product associated with the user event. For |
| # example, this field will be 2 if two products are added to the shopping |
| # cart for `add-to-cart` event. Required for `add-to-cart`, `add-to-list`, |
| # `remove-from-cart`, `checkout-start`, `purchase-complete`, `refund` event |
| # types. |
| "currencyCode": "A String", # Optional. Currency code for price/costs. Use three-character ISO-4217 |
| # code. Required only if originalPrice or displayPrice is set. |
| }, |
| ], |
| "cartId": "A String", # Optional. The id or name of the associated shopping cart. This id is used |
| # to associate multiple items added or present in the cart before purchase. |
| # |
| # This can only be set for `add-to-cart`, `remove-from-cart`, |
| # `checkout-start`, `purchase-complete`, or `shopping-cart-page-view` events. |
| "listId": "A String", # Required for `add-to-list` and `remove-from-list` events. The id or name of |
| # the list that the item is being added to or removed from. Other event types |
| # should not set this field. |
| }, |
| "eventType": "A String", # Required. User event type. Allowed values are: |
| # |
| # * `add-to-cart` Products being added to cart. |
| # * `add-to-list` Items being added to a list (shopping list, favorites |
| # etc). |
| # * `category-page-view` Special pages such as sale or promotion pages |
| # viewed. |
| # * `checkout-start` User starting a checkout process. |
| # * `detail-page-view` Products detail page viewed. |
| # * `home-page-view` Homepage viewed. |
| # * `page-visit` Generic page visits not included in the event types above. |
| # * `purchase-complete` User finishing a purchase. |
| # * `refund` Purchased items being refunded or returned. |
| # * `remove-from-cart` Products being removed from cart. |
| # * `remove-from-list` Items being removed from a list. |
| # * `search` Product search. |
| # * `shopping-cart-page-view` User viewing a shopping cart. |
| # * `impression` List of items displayed. Used by Google Tag Manager. |
| "userInfo": { # Information of end users. # Required. User information. |
| "ipAddress": "A String", # Optional. IP address of the user. This could be either IPv4 (e.g. 104.133.9.80) or |
| # IPv6 (e.g. 2001:0db8:85a3:0000:0000:8a2e:0370:7334). This should *not* be |
| # set when using the javascript pixel or if `direct_user_request` is set. |
| # Used to extract location information for personalization. |
| "directUserRequest": True or False, # Optional. Indicates if the request is made directly from the end user |
| # in which case the user_agent and ip_address fields can be populated |
| # from the HTTP request. This should *not* be set when using the javascript |
| # pixel. This flag should be set only if the API request is made directly |
| # from the end user such as a mobile app (and not if a gateway or a server is |
| # processing and pushing the user events). |
| "userAgent": "A String", # Optional. User agent as included in the HTTP header. UTF-8 encoded string |
| # with a length limit of 1 KiB. |
| # |
| # This should *not* be set when using the JavaScript pixel or if |
| # `directUserRequest` is set. |
| "visitorId": "A String", # Required. A unique identifier for tracking visitors with a length limit of |
| # 128 bytes. |
| # |
| # For example, this could be implemented with a http cookie, which should be |
| # able to uniquely identify a visitor on a single device. This unique |
| # identifier should not change if the visitor log in/out of the website. |
| # Maximum length 128 bytes. Cannot be empty. |
| "userId": "A String", # Optional. Unique identifier for logged-in user with a length limit of 128 |
| # bytes. Required only for logged-in users. |
| }, |
| "eventTime": "A String", # Optional. Only required for ImportUserEvents method. Timestamp of user |
| # event created. |
| "eventDetail": { # User event details shared by all recommendation types. # Optional. User event detailed information common across different |
| # recommendation types. |
| "pageViewId": "A String", # Optional. A unique id of a web page view. |
| # This should be kept the same for all user events triggered from the same |
| # pageview. For example, an item detail page view could trigger multiple |
| # events as the user is browsing the page. |
| # The `pageViewId` property should be kept the same for all these events so |
| # that they can be grouped together properly. This `pageViewId` will be |
| # automatically generated if using the JavaScript pixel. |
| "uri": "A String", # Optional. Complete url (window.location.href) of the user's current page. |
| # When using the JavaScript pixel, this value is filled in automatically. |
| # Maximum length 5KB. |
| "referrerUri": "A String", # Optional. The referrer url of the current page. When using |
| # the JavaScript pixel, this value is filled in automatically. |
| "recommendationToken": "A String", # Optional. Recommendation token included in the recommendation prediction |
| # response. |
| # |
| # This field enables accurate attribution of recommendation model |
| # performance. |
| # |
| # This token enables us to accurately attribute page view or purchase back to |
| # the event and the particular predict response containing this |
| # clicked/purchased item. If user clicks on product K in the recommendation |
| # results, pass the `PredictResponse.recommendationToken` property as a url |
| # parameter to product K's page. When recording events on product K's page, |
| # log the PredictResponse.recommendation_token to this field. |
| # |
| # Optional, but highly encouraged for user events that are the result of a |
| # recommendation prediction query. |
| "experimentIds": [ # Optional. A list of identifiers for the independent experiment groups |
| # this user event belongs to. This is used to distinguish between user events |
| # associated with different experiment setups (e.g. using Recommendation |
| # Engine system, using different recommendation models). |
| "A String", |
| ], |
| "eventAttributes": { # FeatureMap represents extra features that customers want to include in the # Optional. Extra user event features to include in the recommendation |
| # model. |
| # |
| # For product recommendation, an example of extra user information is |
| # traffic_channel, i.e. how user arrives at the site. Users can arrive |
| # at the site by coming to the site directly, or coming through Google |
| # search, and etc. |
| # recommendation model for catalogs/user events as categorical/numerical |
| # features. |
| "numericalFeatures": { # Numerical features. Some examples would be the height/weight of a product, |
| # or age of a customer. |
| # |
| # Feature names must be UTF-8 encoded strings. |
| # |
| # For example: `{ "lengths_cm": {"value":[2.3, 15.4]}, |
| # "heights_cm": {"value":[8.1, 6.4]} }` |
| "a_key": { # A list of float features. |
| "value": [ # Float feature value. |
| 3.14, |
| ], |
| }, |
| }, |
| "categoricalFeatures": { # Categorical features that can take on one of a limited number of possible |
| # values. Some examples would be the brand/maker of a product, or country of |
| # a customer. |
| # |
| # Feature names and values must be UTF-8 encoded strings. |
| # |
| # For example: `{ "colors": {"value": ["yellow", "green"]}, |
| # "sizes": {"value":["S", "M"]}` |
| "a_key": { # A list of string features. |
| "value": [ # String feature value with a length limit of 128 bytes. |
| "A String", |
| ], |
| }, |
| }, |
| }, |
| }, |
| "eventSource": "A String", # Optional. This field should *not* be set when using JavaScript pixel |
| # or the Recommendations AI Tag. Defaults to `EVENT_SOURCE_UNSPECIFIED`. |
| }, |
| "labels": { # Optional. The labels for the predict request. |
| # |
| # * Label keys can contain lowercase letters, digits and hyphens, must start |
| # with a letter, and must end with a letter or digit. |
| # * Non-zero label values can contain lowercase letters, digits and hyphens, |
| # must start with a letter, and must end with a letter or digit. |
| # * No more than 64 labels can be associated with a given request. |
| # |
| # See https://goo.gl/xmQnxf for more information on and examples of labels. |
| "a_key": "A String", |
| }, |
| "pageToken": "A String", # Optional. The previous PredictResponse.next_page_token. |
| "params": { # Optional. Additional domain specific parameters for the predictions. |
| # |
| # Allowed values: |
| # |
| # * `returnCatalogItem`: Boolean. If set to true, the associated catalogItem |
| # object will be returned in the |
| # `PredictResponse.PredictionResult.itemMetadata` object in the method |
| # response. |
| # * `returnItemScore`: Boolean. If set to true, the prediction 'score' |
| # corresponding to each returned item will be set in the `metadata` |
| # field in the prediction response. The given 'score' indicates the |
| # probability of an item being clicked/purchased given the user's context |
| # and history. |
| # * `strictFiltering`: Boolean. If set to true, the service will return empty |
| # instead of generic (unfiltered) popular items if your filter blocks all |
| # prediction results. |
| "a_key": "", |
| }, |
| "pageSize": 42, # Optional. Maximum number of results to return per page. Set this property |
| # to the number of prediction results required. If zero, the service will |
| # choose a reasonable default. |
| "filter": "A String", # Optional. Filter for restricting prediction results. Accepts values for |
| # tags and the `filterOutOfStockItems` flag. |
| # |
| # * Tag expressions. Restricts predictions to items that match all of the |
| # specified tags. Boolean operators `OR` and `NOT` are supported if the |
| # expression is enclosed in parentheses, and must be separated from the |
| # tag values by a space. `-"tagA"` is also supported and is equivalent to |
| # `NOT "tagA"`. Tag values must be double quoted UTF-8 encoded strings |
| # with a size limit of 1 KiB. |
| # |
| # * filterOutOfStockItems. Restricts predictions to items that do not have a |
| # stockState value of OUT_OF_STOCK. |
| # |
| # Examples: |
| # |
| # * tag=("Red" OR "Blue") tag="New-Arrival" tag=(NOT "promotional") |
| # * filterOutOfStockItems tag=(-"promotional") |
| # * filterOutOfStockItems |
| # |
| # If your filter blocks all prediction results, generic (unfiltered) popular |
| # items are returned. This behavior can be overridden by setting |
| # `strictFiltering` to true in `PredictRequest.params`. |
| } |
| |
| x__xgafv: string, V1 error format. |
| Allowed values |
| 1 - v1 error format |
| 2 - v2 error format |
| |
| Returns: |
| An object of the form: |
| |
| { # Response message for predict method. |
| "nextPageToken": "A String", # If empty, the list is complete. If nonempty, the token to pass to the next |
| # request's PredictRequest.page_token. |
| "metadata": { # Additional domain specific prediction response metadata. |
| "a_key": "", |
| }, |
| "dryRun": True or False, # True if the dryRun property was set in the request. |
| "recommendationToken": "A String", # A unique recommendation token. This should be included in the user event |
| # logs resulting from this recommendation, which enables accurate attribution |
| # of recommendation model performance. |
| "results": [ # A list of recommended items. The order represents the ranking (from the |
| # most relevant item to the least). |
| { # PredictionResult represents the recommendation prediction results. |
| "itemMetadata": { # Additional item metadata / annotations. |
| # |
| # Possible values: |
| # |
| # * `catalogItem`: JSON representation of the catalogItem. Will be set if |
| # `returnCatalogItem` is set to true in `PredictRequest.params`. |
| # * `score`: Prediction score in double value. Will be set if |
| # `returnItemScore` is set to true in `PredictRequest.params`. |
| "a_key": "", |
| }, |
| "id": "A String", # ID of the recommended catalog item |
| }, |
| ], |
| "itemsMissingInCatalog": [ # IDs of items in the request that were missing from the catalog. |
| "A String", |
| ], |
| }</pre> |
| </div> |
| |
| <div class="method"> |
| <code class="details" id="predict_next">predict_next(previous_request, previous_response)</code> |
| <pre>Retrieves the next page of results. |
| |
| Args: |
| previous_request: The request for the previous page. (required) |
| previous_response: The response from the request for the previous page. (required) |
| |
| Returns: |
| A request object that you can call 'execute()' on to request the next |
| page. Returns None if there are no more items in the collection. |
| </pre> |
| </div> |
| |
| </body></html> |
