Skip to content

/image endpoint

Use the /image endpoint to search your collection for a sample image. Discover relevant content in your collection based on the information in your images.

The examples below require the example dataset.

Find images with similar content to the indexed image id:111.

http://localhost:8983/api/cores/my-collection/image?rank.by.id=111

Shortened response: 

{
  "responseHeader": {
    "status": 0,
    "QTime": 1
  },
  "response": {
    "numFound": 7,
    "start": 0,
    "maxScore": 1,
    "numFoundExact": true,
    "docs": [
      {
        "id": "111",
        "color_rerank": 2122542384654405000,
        "color_isolated": false,
        "color_palette_freq": [
          0.26054847,
          0.23869967,
          0.20905921,
          0.18613034,
          0.11200625
        ],
        "color_palette_hex": [
          "#343E1E",
          "#889191",
          "#66A5F6",
          "#8A8F58",
          "#4E6279"
        ],
        "color_names": [
          "green",
          "blue",
          "grey"
        ],
        "score": 1
      }
    ]
  }
}

Open Flow in browser

Suggest variants & alternatives

Automatically suggest similar variants or alternatives to a selected image on a detail page.

Example UI with search results

Imagine the selected image is id:123. Find the three most similar images to the indexed image id=123 and ignore the query image itself.

http://localhost:8983/api/cores/my-collection/image?
&fq=-id:123
&rank.by.id=123
&rows=3
Narrow down the suggestions with extra filters

You can easily restrict the suggested alternatives by adding further filter queries to your request (multiple fq params in one request are supported). For example

  • only suggest products from category living: fq=category:living or
  • only suggest higher-priced alternatives: fq=price:[100 TO *].

For automatic context setting, the concrete filter values should be taken from the document of the selected image.

Use web image to find similar products

You can easily use URLs of web images to search for similar products in your collection.

The query below searches for a Wilson basketball in your collection. 

http://localhost:8983/api/cores/my-collection/image?
&rank.by.url=https://docs.pixolution.io/assets/static/wilson-basketball.jpg

Open Flow in browser

As you can see in the results, Flow first returns identical products, then basketballs from different vendors, and finally other types of balls after there are no basketballs left in the collection. This is great because Flow automatically returns similar alternatives when the specific item is not available.

The query below searches for specific playing cards in your collection. 

http://localhost:8983/api/cores/my-collection/image?
&rank.by.url=https://docs.pixolution.io/assets/static/cards.jpg

Open Flow in browser

Upload local image as search input

Use a local image and upload it as base64 encoded value of rank.by.data parameter to search for similar content in your collection.

The following snippet loads the image and scales it down to thumbnail size in memory before uploading it to Flow. This has two advantages:

  1. Python Pillow package supports many more image formats than the Java runtime used by Flow. By converting the image to png before uploading, you can easily handle a wide range of formats.
  2. Downscaling the image before uploading significantly speeds up processing for high-resolution images by minimizing I/O and decoding times.
import requests
import base64
from PIL import Image
from io import BytesIO

IMG_PATH = "YOUR_IMAGE_PATH"
FLOW_URL = "http://localhost:8983/api/cores/my-collection"
# Load & scale to thumbnail size - HighRes images slow down IO tremendously
img = Image.open(IMG_PATH)
img.thumbnail((400, 400))
# encode as in-memory png
bytes = BytesIO()
img.save(bytes, format='PNG')
base64_image = base64.b64encode(bytes.getvalue()).decode('utf-8')
payload = {'rank.by.data': base64_image}
# set empty logParamsList= to avoid logging huge log messages when uploading base64 images as parameters
rsp = requests.post(FLOW_URL+"/image?logParamsList=", data=payload)
print(rsp.json())

base64 --wrap=0 YOUR_FILE_PATH | \
curl --data-urlencode "rank.by.data@-" \
--url 'http://localhost:8983/api/cores/my-collection/image?logParamsList='