# CF API documentation: stores vs related_stores

`store` and `related_stores` are two fields in the response payload from the `/search` endpoint, from Adeptmind. In this document we briefly explain the bahavior/expectations regarding these two fields.

### Overview
- stores:
- when the search is likely to be targeting one or more specific stores, Adeptmind will put targeted stores under `stores` field.
- related_stores:
- for stores that the returned products are sold in, they are put into `related_stores` field
- additionally, if Adeptmind has additional knowlege that similar products can be sold in some other stores, those stores will also be put into `related_stores` field
- if a store appears in `stores` field, it will be removed from `related_stores` field

### Specific cases
Assuming Adeptind has three stores in its catalog, "SportsChek", Nike" and "Adidas", all three selling sports shoes.
"SportsChek" also sells "Nike" sports shoes and "Adidas" sports shoes
Below are the expectations:
- 1, Query: "sports shoes"
- stores: []
- related_stores: [Nike, SportsChek, Adidas]
- 2, Query: "sports shoes", Guided-Discovery-Pill: "Nike"
- stores: [Nike]
- related_stores: [SportsChek]
- 3, Query: "sports shoes", Filter: "BRAND:Nike"
- stores: []
- related_stores: [Nike, SportsChek]
- 4, Query: "sports shoes", Filter: "STORE:Nike"
- stores: [Nike]
- related_stores: []
- 5, Query: "nike sports shoes"
- stores: [Nike]
- related_stores" [SportsChek]

### Action items as of 20200205, if we agree with everything above.
- for bug https://cadillacfairview.atlassian.net/browse/CFB-860
- need to implement #2 under specific cases, as a new feature
- need to improve related_stores quality, this is a bug reported by Elza
- need to figure out if there are any more problems with non-shop queries (query: "specialty food")

- for bug https://cadillacfairview.atlassian.net/browse/CFB-897
- need to implement #4 under specific cases, as a new feature

- we also need to double check on #1, #3, #5 for the specific cases. But since there are no bugs reported yet, we don't have to rush for them.

- are there any other cases that we particularly care about:
- does it matter if Nike/SportsChek is hidden?
- potentially more..

### 20200206 comments
- we cannot support 2 perfectly, because we cannot tell if `Guided-Discovery-Pill: "Nike"` should be translated to `Filter: "STORE:NIKE"`, or `Filter: "BRAND:NIKE"`, unless we extend our API to include additional information.
- we cannot always treat `Guided-Discovery-Pill: "Nike"` as `Filter: "STORE:NIKE"`
- for example, if user search for `SPORTS CHEK running shoes`, and sees a pill `Guided-Discovery-Pill: "Nike"`, this pill is actually meant for `BRAND:NIKE`. Treating it as `Filter: "STORE:NIKE"` will be wrong.
- we can, however, support 2 partially.
- we can support 2 for all the stores, where their brand is only sold in store, not any other stores.
- in this case, we can be confident that the guided-D pills definitely means `STORE` instead of `BRAND`
- out of all current stores, we can support: `['CARYL_BAKER_VISAGE', 'JOHNSTON_&_MURPHY', 'DANIER', 'HOT_TOPIC', 'BAILEY_NELSON', 'ABERCROMBIE_&_FITCH', 'OAK+FORT', 'DYNAMITE', 'LUSH_FRESH_HANDMADE_COSMETICS', 'LA_SENZA', 'H&M', 'NORDSTROM', "L'INTERVALLE", 'GARAGE', "MARK'S", 'FRANK_&_OAK', 'MARC_CAIN', 'LOFT', 'YVES_ROCHER', 'LE_CHATEAU', 'EDDIE_BAUER', 'RW_&_CO.', 'M0851', 'FOOT_LOCKER', 'LITTLE_BURGUNDY', 'CALENDAR_CLUB', "HUDSON'S_BAY", 'THEFACESHOP', 'TORRID', 'OLD_NAVY', 'DAVIDSTEA', 'SAKS_FIFTH_AVENUE', 'REITMANS', 'FOREVER_21', 'SWATCH', 'NYX_PROFESSIONAL_MAKEUP', 'HOLLISTER', 'GNC', 'ZARA', 'BENTLEY']`
- we cannot support: `['CLUB_MONACO', 'FREE_PEOPLE', 'GUESS', 'UNO_DE_50', 'COACH', 'APPLE', 'ALDO', 'SWAROVSKI', 'SOIA_&_KYO', 'MACKAGE', 'MICHAEL_KORS', 'STEVE_MADDEN', 'PANDORA', 'MAJE', 'SANDRO', 'ECCO_SHOES', 'NIKE', 'FOSSIL', 'ALLSAINTS', 'LACOSTE', 'SCOTCH_&_SODA', 'CALL_IT_SPRING', 'REISS', "L'OCCITANE", 'ROOTS', 'TUMI', "LEVI'S", 'THE_MICROSOFT_STORE', 'STUART_WEITZMAN', 'BOSS_HUGO_BOSS', 'KATE_SPADE', 'JACK_&_JONES', 'SKECHERS']`

- can we treat 4 and 5 the same
- under the hood, they will be doing the same search, and same products would be returned

### Proposed updates
Add promotion logic at the end of processing pipeline, chech both STORE/BRAND filters to see if we can promote any stores from `related_stores` to `stores`
Assuming Adeptind has three stores in its catalog, "Zara", Nike" and "FootLocker", all three selling running shoes.
- "Zara":
- Zara is both a store, and a brand
- as a brand, the brand is sold exclusively in-store, you cannot find "Zara" products in other stores
- "Nike"
- Nike is both a store, and a brand
- as a brand, the brand is sold in multiple stores, including itself
- "FootLocker":
- FootLocker is a store
- as a store, footlocker sells "Nike" products

- 1, Query: "running shoes"
- stores: []
- related_stores: [FootLocker, Zara, Nike]
- 2a, Query: "running shoes", Guided-Discovery-Pill: "Nike"
- stores: [Nike]
- related_stores: [SportsChek]
- Promotion: Nike is promoted from `related_stores` to `stores`
- 2b, Query: "running shoes", Guided-Discovery-Pill: "Zara"
- stores: [Zara]
- related_stores: []
- promotion: Zara is promoted from `related_stores` to `stores`
- 3a, Query: "running shoes", Filter: "BRAND:Nike"
- stores: [Nike]
- related_stores: [SportsChek]
- promotion: Nike is promoted from `related_stores` to `stores`
- 3b, Query: "running shoes", Filter: "BRAND:Zara"
- stores: [Zara]
- related_stores: []
- promotion: Zara is promoted from `related_stores` to `stores`
- 3c, Query: "running shoes", Filter: "BRAND:Zara" and "BRAND: Nike"
- stores: []
- related_stores: [Zara, Nike, SportsChek]
- promotion won't happen on Brand filters when there are multiple brands selected, so Zara and Nike will stay in related_stores.
- 4a, Query: "running shoes", Filter: "STORE:Nike"
- stores: [Nike]
- related_stores: []
- 4b, Query: "running shoes", Filter: "STORE:Zara"
- stores: [Zara]
- related_stores: []
- 4c, Query: "running shoes", Filter: "STORE:Zara" amd "STORE:Nike"
- stores: [Zara, "Nike"]
- related_stores: []
- 5a, Query: "nike running shoes"
- stores: [Nike]
- related_stores" [SportsChek]
- promotion: Nike is promoted from `related_stores` to `stores`
- 5b, Query: "Zara running shoes"
- stores: [Zara]
- related_stores" []
- promotion: Zara is promoted from `related_stores` to `stores`