Skip to main content
GET
/
6
/
{hashid}
/
_visually_similar
Visually Similar
curl --request GET \
  --url https://{search_zone}-search.doofinder.com/6/{hashid}/_visually_similar \
  --header 'Authorization: <api-key>'
{
  "custom_results_id": 5,
  "facets": [
    {
      "brand": {
        "terms": {
          "items": [
            {
              "name": "Adidas",
              "count": 5
            },
            {
              "name": "Nike",
              "count": 3
            }
          ],
          "selected": []
        }
      }
    }
  ],
  "query_name": "fuzzy",
  "results": [
    {
      "description": "The best product description ever",
      "dfid": "1234567890abcdef1234567890abcdef@product@1234567890abcdef",
      "id": "my_id",
      "image_url": "http://www.example.com/images/alt_product_image.jpg",
      "title": "My item",
      "url": "http://www.example.com/alt_product_description.htm"
    }
  ],
  "total": 1
}

Authorizations

​
Authorization
string
header
required

Doofinder API key. Pass it as: Authorization: Token <api_key>

Path Parameters

​
hashid
string
required

Unique id of a search engine.

Query Parameters

​
dfid
string
required

Doofinder item id. It comes in every Doofinder results for every item. It has the form {hashid}@{index}@{md5id} i.e. 6a96504dc173514cab1e0198af92e6e9@product@e19347e1c3ca0c0b97de5fb3b690855a

​
exclude
string

Exclusive parameters are negative filters.

Doofinder expects the exclude parameters grouped like this:

exclude: { color: ['blue', 'red'], size: ['M', 'S'], price: { gte: 4.36, lt: 99 } }

For the range filters it can be used the following:

  • gte: Greater than or equal
  • lte: Less than or equal
  • gt: Greater than
  • lt: Less than

Writing that down in request parameters language is:

exclude[color][]=blue&exclude[color][]=red&exclude[size]=M&exclude[size]=S&exclude[price][gte]=4.36&exclude[price][lt]=99

Note that [ and ] characters should be escaped (%5B and %5D) in all exclude cases.

​
exclude_self
boolean

Exclude the item being searched from the results. Default: true

​
excluded_results
boolean

Enable/Disable excluded items feature in the search. Default: true

​
facets
object

Aggregates fields values in a facet, you could use a term facet or range facet. Read facets configuration for more deep info about facets.

The type of the facet (term or range) will be determined automatically.

Parameters:

  • field*: That is the field name that you want to aggregate results.
  • size: The number of results to return in each field. Only applicable to facet terms. Maximum: 50 by default to help maintain the speed of the search function. If you need more, please contact Doofinder support.
  • type: The facet type. Indicates the type of the facet, one of term or range. will return an error if the facet type is not correct.

*required parameter

Example request returning the brand term facet and the best_facet range facet:

facets[0][field]=brand&facets[0][size]=10&facets[1][field]=best_price.

​
filter
string

Filter parameters for items.

Doofinder expects the filter parameters grouped like this:

filter: { color: ['blue', 'red'], size: ['M', 'S'], price: { gte: 4.36, lt: 99 } }

Range filters can be used as follow:

  • gte: Greater than or equal
  • lte: Less than or equal
  • gt: Greater than
  • lt: Less than

Writing that down in request parameters language:

filter[color][]=blue&filter[color][]=red&filter[size][]=M&filter[size][]=S&filter[price][gte]=4.36&filter[price][lt]=99

Note that [ and ] characters should be escaped (%5B and %5D) in all filter cases.

​
filter_execution
enum<string>

Filters are applied with "and" boolean logic than means that all filters conditions should be met. If you want to apply any of the filters conditions, you can change it to "or".

Available options:
and,
or
​
rpp
integer

Results per page. how many results per page to return. Limits are rpp <= 100 and rpp * page < 1000.

​
session_id
string

The current session ID, must be unique for each user. Identifier of search session

Maximum string length: 32
​
user_id
string

Identifies the user, must be unique for each user. Identifier of user

Maximum string length: 36
​
stats
boolean

Enable/Disable this search in stats reports. Default: true

​
fields
string[]

These are the fields we will use in the similar search, to search for products similar to the one defined by dfid.

​
sort
string

Sorted results by certain fields.

Doofinder expects sort parameters like this:

sort: [{"price": "asc"}, {"brand": "desc"}]

Writing that down in request parameters language is:

sort[0][price]=asc&sort[1][brand]=desc

Note that [ and ] characters should be escaped (%5B and %5D) in all filter cases.

Response

OK

Search response. Some fields can not be included in the request if they have not data.

​
banner
Banner Response · object

Banner response for a query search.

​
count
integer

Total number of items found in the search engine for the searched term.

​
custom_results_id
integer

Id of applied custom results. This field will not be included if none of the custom results apply.

​
dynamic_boosting_rule_id
integer

Id of applied dynamic boosting rule. This field will not be included if none of the dynamic boosting rules apply.

​
facets
(Term Facet Response · object | Range Facet Response · object)[]

Information about different groupings that can be made for certain fields in the search results.

Facet terms search response. Used to aggregate a field by their values.

​
query_name
string

In order to get the best possible results, Doofinder tries several types of querying. This is the type of the query Doofinder made to obtain these results.

​
results
Item · object[]
​
total
integer

Total number of items that can be fetched.