Introduction

The Visually Similar API accepts a unique product identifier (product ID and color ID), also referred to as ‘item’ in this document, and returns a ranked list of other items that are closest in similarity.  The item passed in the request must be an active, in-stock / available for sale, and fully indexed in the FindMine system. The API response will include products that are active, available for sale and fully indexed.

Recommendations

A server-side implementation of the Visually Similar API maximizes user experience.  Server-side implementations should include best practices including a caching proxy, rate limiting, and exponential backoff on failed requests.

API Endpoint

<https://api.findmine.com/api/v3/visually-similar>

Get

For browser integrations, the GET method provides significantly faster responses. It avoids slow browser cross-origin security checking requests. All API parameters are passed as HTTP GET arguments.

Post

For other integrations, the POST method may be preferable. Posts must be content-type: application/json, and the posted data must be in the JSON format. Otherwise, all parameter names and semantics are the same. Response are plain JSON.

General Parameters

Parameter Required Type Description
application Yes String The application parameter is a unique identifier provided to you at the start of integration. This identifier is not an authorization secret, it is safe and required to embed in your public HTML. Example: application=AB1212CDABCD
product_id Yes String(s) An identifier that represents a product style but without a color/pattern designation or size.  (The exact parameter names will be configured for your integration during onboarding, and reflect the specific product variation structure of your catalog.)This parameter must match identifiers in the product catalog feed exactly. Example: product_id=P_12
product_color_id Yes String An identifier that represents a color/pattern variant of the product_id but doesn’t account for a specific size.  (The exact parameter names will be configured for your integration during onboarding, and reflect the specific product variation structure of your catalog.)This parameter must match identifiers in the product catalog feed exactly. Example: product_color_id=C_00
region No* String Two letter ISO Country code.* - required for multi-region implementations. Example: region=us
language No* String Two letter ISO language code.* - required for multi-language  implementations. Example: language=en
return_details No Boolean Setting this parameter to true returns a fuller set of data about each matching product. Included is a FindMine category attribute for each product, as well as a collection called details. The details collection is defined as part of your onboarding with FindMine, code samples here are for example only.
return_pdp_item No Boolean Example*:* return_pdp_item=true

Testing Requests

If you want to test your implementation while our team is preparing the ingestion scripts for your product feed, you can leverage the fake_result flag. All you need to do is pass a fake_result=true on the GET params or fake_result: true on the POST json body. You will get a randomly generated set of matched items.

Here's a sample POST request with the fake_result flag:

{ 
"application": "xxx", 
"fake_result": **true**
}

And here's one for a GET request:****