Image Search Using Search ID

Description
Request URL
Path and Query Parameters
Sample Requests and Responses
Error Codes

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.

HTTP Method and Request URL

GET

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

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

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"
    }
}

Error Codes

Call Specific Error Codes:

NONE

General Error Handling Documentation:

Click Here