Unified Customer-Item Recommender API

Unified Customer-Item Recommender API

2.0.0.dev0OAS 3.0

The Unified Customer-Item Recommender API provides probability-based scores and rankings of items & promotions for individual Cumulus customers.
The API allows to

  • recommend top k relevant items to customers or compute individual customer-item scores.
  • find similar items or similar customers.
  • get vector representations (embeddings) of items and customers.

The Unified Customer-Item Recommender unifies scores for previously-purchased items and not-previously-purchased items (new to the individual customer). It replaces earlier, separate recommenders and their APIs for previously-purchased items (e.g., UIR, Bedarfsrecommender, item statistics) and new items (WRMF).

For support, you can reach team Best Match here: ARG_MGB-Ops-Tech-Analytics-BestMatch-Prod-Support@mgb.ch

API Base URL
  • Server 1:https://prod-unified-recommender.service.migros.cloud

    URL of upstream

Security
apiKeyAuth (apiKey)

An API key is a token that you provide when making API calls. Include the token in a header parameter called X-API-Key.

Example: X-API-Key: 123

Batch

Optimized for processing customers-item scores in large batches; latencies of up to several seconds.

Requests computation of an aggregated score per item group (e.g., a product range) for each customer.

This path requests the computation of scores for all customers known in the domain. Scores are not immediately computed but must be acquired from the Google Storage URI returned. Depending on system load, it can take between a few minutes to several hours before scores are available. Clients must periodically check the returned URI, in order to know if the requested scores are ready for download.

The format of the scores is parquet.

After some period (usually several days) computed scores are garbage collected.

put
https://prod-unified-recommender.service.migros.cloud/migros/customers/v1/recommender/scoreitemgroup/{domain_id}/{reference_date}

Path Parameters

domain_idstringrequired

Default:Cumulus

reference_datestring(date-time)required

Example:2023-04-02T00:00:00Z

Body

application/json

Batch scoring request parameters

bought_limitnumber(float)

Relative share of scores to keep, descending order (aka. X1FilterRatio). This filter is applied after any filters based on single scores (e.g. max_score).

Default:0.75

>= 0<= 1

itemsarray[string]

Migros ArtikelID

Match pattern:^[a-zA-Z0-9=]+$

Example:110136400000

max_scorenumber(float)

Inclusive upper predicted purchase probability limit. Useful for not offering items which will be bought also without any incentive or communication.

Default:0.9

>= 0<= 1

not_bought_rationumber(float)

Ratio of scores for not bought (in the last 12 months) items to bought items (aka. X0toX1FilterRatio). This filter is applied after any filters based on single scores (e.g. max_score).

Default:0.2

>= 0

Response

application/json

Scoring request accepted

scores_uristring(uri)

Example:gs://mgb-recommender-dev-data/1.0.0/scores/Cumulus/c4f01b13d11d7fd2-20211120T113908.123Z-20210919T000000.000Z/scores

put/migros/customers/v1/recommender/scoreitemgroup/{domain_id}/{reference_date}

Body

{}
 
application/json

Online

Online scoring of individual customers/items.

Returns the purchase probability of an item for a specific customer.

Returns score (purchase probability) for the next seven days from the instant the query is executed. Optionally returns the input features that the model used.

get
https://prod-unified-recommender.service.migros.cloud/migros/customers/v1/recommender/customeritemprediction/{domain_id}/{customer_id}/{item_id}

Query Parameters

return_featuresboolean

Return features used as input in recommender model.

Default:false

Path Parameters

domain_idstringrequired

Default:Cumulus

customer_idstringrequired

e.g. CumulusID, PersonenID or pseudonymized version thereof

Match pattern:^[a-zA-Z0-9-]+$

Example:2099XXXXXXX

item_idstringrequired

Migros ArtikelID

Match pattern:^[a-zA-Z0-9=]+$

Example:110136400000

Response

application/json

OK

SingleScore

SingleScoreobject
get/migros/customers/v1/recommender/customeritemprediction/{domain_id}/{customer_id}/{item_id}
 
application/json