Unified Customer-Item Recommender API

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

Returns the items with the highest purchase probability-based scores for a customer.

Returns scores based on purchase probabilities for the next seven days from the instant the query is executed.
If a customer has opted out from profiling and/or has no transactions, scores for popular items are returned as a fallback. API consumers are notified about non-personalized scores i.e. popular items via HTTP response header.

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

Query Parameters

limitinteger

Number of items. May return less than requested items.

Default:10

>= 1<= 300

newnessstring

Select whether to return only items not bought in the last twelve months, items bought in the last twelve months, or all items.

Allowed values:allnot_boughtbought

Default:all

items_liststring

Comma separated list of up to 50 item IDs. If provided, only items contained in item_list will be returned.

Match pattern:^[a-zA-Z0-9]+(,[a-zA-Z0-9]+){0,49}$

items_blackliststring

Comma separated list of up to 50 item IDs. If provided, items contained in items_blacklist will not be returned.

Match pattern:^[a-zA-Z0-9]+(,[a-zA-Z0-9]+){0,49}$

items_rangestring

Select which items will be scored: all or only currently promoted items.

Allowed values:allpromoted

Default:all

Path Parameters

domain_idstringrequired

Default:Cumulus

customer_idstringrequired

e.g. CumulusID, PersonenID or pseudonymized version thereof

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

Example:2099XXXXXXX

Response

application/json

OK

ItemScores

item_idstring

Migros ArtikelID

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

Example:110136400000

scorenumber(float)

Depending on context, a score relates to a 7-day purchase probability or is just a ranking.

>= 0<= 1

get/migros/customers/v1/recommender/customeritempredictions/{domain_id}/{customer_id}
 
application/json

Returns item statistics for a customer.

Get a customer’s purchased items sorted by recency, frequency, or monetary.

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

Query Parameters

limitinteger

Number of items

Default:100

>= 1<= 700

num_daysinteger

Number of days to be considered

Default:180

>= 1<= 365

Path Parameters

domain_idstringrequired

Default:Cumulus

customer_idstringrequired

e.g. CumulusID, PersonenID or pseudonymized version thereof

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

Example:2099XXXXXXX

sort_bystringrequired

A comma separated list of sorting criteria. Currently, the following sorting criteria are understood:

  • recency,
  • frequency,
  • monetary.

The ordering is as follows:

  • For recency, the most recent item comes first,
  • For frequency, the item with highest frequency comes first,
  • For monetary, the item with largest revenue comes first.

It is strongly recommended to specify multiple sorting criteria in order to break ties. Example: sort_by=recency,monetary

Match pattern:^(recency|monetary|frequency)(,(recency|monetary|frequency)){0,2}$

Default:recency,monetary

Response

application/json

OK

frequencynumber
item_idstring

Migros ArtikelID

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

Example:110136400000

monetarynumber
recencynumber
get/migros/customers/v1/recommender/customeritemstatistics/{domain_id}/{customer_id}/{sort_by}
 
application/json