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.
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.
<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.
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 |
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:****