Image Search Using Search ID

Description

The user sends search id (which was returned in earlier POST call) along with optional additional parameters to search for similar images in Macy's catalog. The assumption that this service will return list of similar product with their IDs and thumbnail information about those products.

back to top

HTTP Method and Request URL

GET

http://api.macys.com/v4/catalog/visualsearch

back to top

Path and Query Parameters

HTTP Header Parameters

Parameter

Description

Mandatory

Sample Value

Accept

Specifies the output format. Can be application/json or application/xml.

Yes

application/json

application/xml

x-macys-webservice-client-id

Pass the apikey as a header value which is called x-macys-webservice-client-id. The api key is the 24 character alphanumeric string assigned to your application when you registered it. Click here for a list of your API keys. 

Yes

xmj9js4jkdpe1983fmwu98gh

Content-Type Specifies the content type. Must be multipart/form-data Yes multipart/form-data

Path Parameters

Parameter

Description

Mandatory

Sample Value

productID

Unique ID for each product. Multiple productIDs can be sent in one call by using a comma separator

optional, but you need at least upcNumber or productId.

 77589,520910

Object Parameters

Object

Nested Object

Description

Mandatory

Sample Value
productdetails

 

sizemap, colormap,typemap, domainvaluesmap, price, summary, badges, collection, childproducts, masterproducts, shipping, attributes, primaryimage, additionalimages, brand, corpclass, availability, urlmetadata This object includes 15 nested objects. If no nested objects are specified we return them all. You can select one nested object or multiples. If you include multiples, seperate them by commas.

 

No (productdetails(price,summary))
upcs upcdetails Returns UPC details No (upcs(upcdetails))
productcategory No (productcategory)
reviews Up to 10 reviews are returned No (reviews)
rebates Returns any rebates for product No (rebates)
promotions Returns any promotions for product No (promotions)
categoryids Returns all category ID's for the product No (categoryids)
storedetails Parameter "bopstore" must be specified to return details if this object is specified No (storedetails)

 

Form Parameters (Payload)

QueryParameter

Description

Type

Mandatory

Sample Value

 

searchId

which can be used for the same search request without uploading image

String

Yes

12345


perPage

Results per page displayed. Default 10.

String

No

10


page

What is current page number requested. default 1

String

No

1


latitude

GPS latitude position data from app

String

No

latitude=37.355965


longitude

GPS longitude position data from app


No

longitude=-122.01318


sortBy

sorts the results . Default sortorder is "DEFAULT" 

 

 

DEFAULT, PRICE_ASCENDING, PRICE_DESCENDING, 
CUSTOMER_RATING, NEWNESS, BEST_SELLERS, NO_SORTING

 

colourRatio

Color ratio of the image from the app

String

No

colourRatio=30

 

textureRatio

Textyre ratio of the image from the app

String

No

textureRatio=70

 

invAssort

Pass Inventory Assortment value to retreive Context specific to return customized search results Default is SITE

String

No

STORE, SITE, JEWELRY, WEDDING_REGISTRY, SHOES, SEARCH_AND_SEND

 

appl

Pass Application value to retreive Context specifc to return customized search results. Default is ASSOCIATE 

String

No

SITE, ASSOCIATE, MOBILE, MEW,SEO_LINK_MODULE, SEARCH_AND_SEND

 

device

Pass Device value to retreive Context specifc to return customized search results. Default is TABLET

String

No

PHONE, TABLET, PC, POS

 

country

Pass Country value to retreive Context specifc to return customized search results. Default is US 

String

No

US

 

callback

If sent, the format is JSONP (JSON with Padding) with the callback returned with the JSON response. You can put anything in the callback parameter and whatever you send is returned.  

String

No

magicofmacysapi

 

Optional facet refinements Query Params:

example : BRAND=Levi's&SPECIAL_OFFERS=Sales+%26+Discounts 

 

 

 

 

back to top

Sample Requests and Responses

Sample Requests

Request URL:

GET

http://api.macys.com/v4/catalog/visualsearch?searchId=70558&BRAND=Alfani

HTTP Header:

x-macys-webservice-client-id: xmj9js4jkdpe1983fmwu98gh

Accept: application/json

 

Sample Response

{
    "productThumbnails": [
        {
            "name": "Alfani Floral-Print A-Line Chiffon Dress",
            "productid": 2207835,
            "isCollection": false,
            "reviewrating": 5,
            "primaryimageURL": "http://slimages.macys.com/is/image/MCY/products/0/optimized/2911230_fpx.tif?bgc=255,255,255&wid=164&qlt=90&layer=comp&op_sharpen=0&resMode=bicub&op_usm=0.7,1.0,0.5,0&fmt=jpeg",
            "productprice": {
                "was": {
                    "value": 59.7,
                    "label": "Was"
                },
                "original": {
                    "value": 99.5,
                    "label": "Orig."
                },
                "current": {
                    "value": 43.99,
                    "label": "Now"
                },
                "pricetype": "Additional Off Perm",
                "pricetypeid": 6,
                "onsale": true
            },
            "productURL": "http://www1.macys.com/shop/product/alfani-floral-print-a-line-chiffon-dress?ID=2207835",
            "onsale": true,
            "available": true,
            "customerrating": 5,
            "totalreviews": 2,
            "badge": {
                "new": false,
                "OnlyatMacys": true,
                "Rebate": false,
                "onsale": true
            }
        },
        {
            "name": "Alfani Ikat-Print Blouson Dress",
            "productid": 2185127,
            "isCollection": false,
            "reviewrating": 5,
            "primaryimageURL": "http://slimages.macys.com/is/image/MCY/products/6/optimized/2911236_fpx.tif?bgc=255,255,255&wid=164&qlt=90&layer=comp&op_sharpen=0&resMode=bicub&op_usm=0.7,1.0,0.5,0&fmt=jpeg",
            "productprice": {
                "was": {
                    "value": 59.7,
                    "label": "Was"
                },
                "original": {
                    "value": 99.5,
                    "label": "Orig."
                },
                "current": {
                    "value": 43.99,
                    "label": "Now"
                },
                "pricetype": "Additional Off Perm",
                "pricetypeid": 6,
                "onsale": true
            },
            "productURL": "http://www1.macys.com/shop/product/alfani-ikat-print-blouson-dress?ID=2185127",
            "onsale": true,
            "available": true,
            "customerrating": 5,
            "totalreviews": 2,
            "badge": {
                "new": false,
                "OnlyatMacys": true,
                "Rebate": false,
                "onsale": true
            }
        },
        {
            "name": "Alfani Animal-Print A-Line Shift Dress",
            "productid": 2185125,
            "isCollection": false,
            "reviewrating": 4.5,
            "primaryimageURL": "http://slimages.macys.com/is/image/MCY/products/2/optimized/2911232_fpx.tif?bgc=255,255,255&wid=164&qlt=90&layer=comp&op_sharpen=0&resMode=bicub&op_usm=0.7,1.0,0.5,0&fmt=jpeg",
            "productprice": {
                "was": {
                    "value": 59.7,
                    "label": "Was"
                },
                "original": {
                    "value": 99.5,
                    "label": "Orig."
                },
                "current": {
                    "value": 43.99,
                    "label": "Now"
                },
                "pricetype": "Additional Off Perm",
                "pricetypeid": 6,
                "onsale": true
            },
            "productURL": "http://www1.macys.com/shop/product/alfani-animal-print-a-line-shift-dress?ID=2185125",
            "onsale": true,
            "available": true,
            "customerrating": 4.5,
            "totalreviews": 4,
            "badge": {
                "new": false,
                "OnlyatMacys": true,
                "Rebate": false,
                "onsale": true
            }
        },
        {
            "name": "Alfani Plus Size Printed Faux-Wrap Dress",
            "productid": 2265988,
            "isCollection": false,
            "reviewrating": 4.8333,
            "primaryimageURL": "http://slimages.macys.com/is/image/MCY/products/0/optimized/2862220_fpx.tif?bgc=255,255,255&wid=164&qlt=90&layer=comp&op_sharpen=0&resMode=bicub&op_usm=0.7,1.0,0.5,0&fmt=jpeg",
            "productprice": {
                "was": {
                    "value": 59.99,
                    "label": "Was"
                },
                "original": {
                    "value": 109.5,
                    "label": "Orig."
                },
                "current": {
                    "value": 35.99,
                    "label": "Now"
                },
                "pricetype": "Additional Off Perm",
                "pricetypeid": 6,
                "onsale": true
            },
            "productURL": "http://www1.macys.com/shop/product/alfani-plus-size-printed-faux-wrap-dress?ID=2265988",
            "onsale": true,
            "available": true,
            "customerrating": 4.8333,
            "totalreviews": 6,
            "badge": {
                "new": false,
                "OnlyatMacys": true,
                "Rebate": false,
                "onsale": true
            }
        }
    ],
    "searchId": "70558",
    "facets": {
        "facet": [
            {
                "displayname": "Special Offers",
                "facetName": "SPECIAL_OFFERS",
                "facetValues": {
                    "facetValue": [
                        {
                            "facetValue": "Sales & Discounts",
                            "productCount": "4"
                        },
                        {
                            "facetValue": "Clearance/Closeout",
                            "productCount": "4"
                        }
                    ]
                }
            },
            {
                "displayname": "Gender",
                "facetName": "GENDER",
                "facetValues": {
                    "facetValue": [
                        {
                            "facetValue": "Female",
                            "productCount": "4"
                        }
                    ]
                }
            },
            {
                "displayname": "Age Group",
                "facetName": "AGE_CATEGORY",
                "facetValues": {
                    "facetValue": [
                        {
                            "facetValue": "Adult",
                            "productCount": "4"
                        }
                    ]
                }
            },
            {
                "displayname": "Special Size",
                "facetName": "SPECIAL_SIZE",
                "facetValues": {
                    "facetValue": [
                        {
                            "facetValue": "Regular",
                            "productCount": "3"
                        },
                        {
                            "facetValue": "Plus Sizes",
                            "productCount": "1"
                        }
                    ]
                }
            },
            {
                "displayname": "Size ",
                "facetName": "SIZE_NORMAL",
                "facetValues": {
                    "facetValue": [
                        {
                            "facetValue": "2",
                            "productCount": "2"
                        },
                        {
                            "facetValue": "4",
                            "productCount": "1"
                        },
                        {
                            "facetValue": "6",
                            "productCount": "2"
                        },
                        {
                            "facetValue": "8",
                            "productCount": "3"
                        },
                        {
                            "facetValue": "10",
                            "productCount": "3"
                        },
                        {
                            "facetValue": "12",
                            "productCount": "3"
                        },
                        {
                            "facetValue": "14",
                            "productCount": "3"
                        },
                        {
                            "facetValue": "16",
                            "productCount": "2"
                        },
                        {
                            "facetValue": "22W",
                            "productCount": "1"
                        }
                    ]
                }
            },
            {
                "displayname": "Color",
                "facetName": "COLOR_NORMAL",
                "facetValues": {
                    "facetValue": [
                        {
                            "facetValue": "Black",
                            "productCount": "1"
                        },
                        {
                            "facetValue": "Brown",
                            "productCount": "1"
                        },
                        {
                            "facetValue": "Multi",
                            "productCount": "1"
                        },
                        {
                            "facetValue": "Yellow",
                            "productCount": "1"
                        }
                    ]
                }
            },
            {
                "displayname": "Customer Ratings",
                "facetName": "CUSTRATINGS",
                "facetValues": {
                    "facetValue": [
                        {
                            "facetValue": "5 stars",
                            "productCount": "2"
                        },
                        {
                            "facetValue": "4 stars & up",
                            "productCount": "4"
                        },
                        {
                            "facetValue": "3 stars & up",
                            "productCount": "4"
                        }
                    ]
                }
            }
        ]
    },
    "totalProductCount": 4,
    "mediaDetails": null,
    "searchinput": {
        "sortorderby": "DEFAULT",
        "perpage": 10,
        "page": 1,
        "inventoryassortment": "SITE",
        "inputrefinements": [
            {
                "refinementname": "BRAND",
                "refinementvalues": [
                    "Alfani"
                ]
            }
        ],
        "device": "PC",
        "country": "US"
    }
}

 

 

back to top

Error Codes

Call Specific Error Codes:

NONE

General Error Handling Documentation:

Click Here

back to top

Docs Navigation