Camera Search API

Overview

Camera Search API provides similar product recommendations based on an input image.

Endpoint

We currently support two LENS API versions

Version 1.1:

https://api.omnious.com/lens/v1.1/searchapi.omnious.com

Version 1.2: Recommended for new LENS users

https://api.omnious.com/lens/v1.2/searchapi.omnious.com

POST /

Request

Header

Name	Description
Content-Type	application/json
x-api-key	API Key for authentication from Omnious [Required]

Body

Name	Type	Required	Description
image	object	O	Object containing image type and content depending on image type
image.type	String	O	Requested image type (url or base64)
image.content	String	O	Requested image contents depending on type if url: URL of the requested image if base64: requested image encoded in base64 A prefix is required for the base64 string. Please see below the chart for details.
limit	Integer	X	Maximum number of items to recommend default: 10 max: 500
weightColorFeature	String	X	Weight of color to be reflected in recommendations default: MEDIUM Selectable from the following values LOW MEDIUM HIGH
showContext	Bool	X	Whether to display context information default: false
showImageInfo	Bool	X	Whether to display image information default: false

---

Updating images with base64 type:

• Prefix "data:image/{image ext};base64," is required for base64 encoded string

base64 python code example

encoded = base64.b64encode(image_data).decode('ascii')
img2str'data:image/png;base64,{}'.format(encoded)

Request Example

Example 1. Search by Base64 (without context information)

{
  "image": {
    "type": "base64",
    "content": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVQYV2Poi5b8DwAEfwICWoNPegAAAABJRU5ErkJggg=="
  }
}

Example 2. Search by URL (without context information)

{
  "image": {
    "type": "url",
    "content": "http://imageserver.net/some/image.jpeg"
  }
}

Example 3. Search by Base64 (with context and image information)

{
  "image": {
    "type": "base64",
    "content": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVQYV2Poi5b8DwAEfwICWoNPegAAAABJRU5ErkJggg=="
  },
  "limit": 10,
  "weightColorFeature": "MEDIUM",
  "showContext": true,
  "showImageInfo": true
}

Response

Return recommended products in order of similarity.

HTTP Status Code

Code	Description
403	API KEY authentication related error
400	Input Data Validation related error
200	Success response with zero recommendation results
201	Success response with one or more recommendation results
500	Server error

Response Body

Name	Type	Description
status	String	“ok” if success
error	Object	returns null if no Error If Error it takes the below format error.code: Error Code defined in the Error menu error.message: Error Message
data	String	Please refer to the Response Data section below

Response Data

Name	Type	Description
image	object	Object containing the image type and content depending on image type
image.type	String	Requested image type (url or base64)
image.content	String	Requested image contents depending on type if url: URL of the requested image if base64: requested image encoded in base64
limit	Integer	Maximum number of items to recommend default: 10 max: 500
weightColorFeature	String	Weight of color to be reflected in recommendations default: MEDIUM Selectable from the following values LOW MEDIUM HIGH
showContext	Bool	Whether to display context information default: false
showImageInfo	Bool	Whether to display image information default: false
detection	Array	(Reserved) currently only returns null
results	Array of Object	Detected product recommendations

Response Data > Results

Name	Type	Description
id	String	The ID of the detected product.
category	String	Category Information about the detected Product
bbox	Array[4]	Bounding Area of the Detected Product. Takes values between 0~1. Numbers are in the following order [top, left, width, height]
recommendation	Array of Object	Please Refer to the Recommendation section Below

Category of Detected Products

Field	Description
SHOES	shoes
BAGS	bags
HATS	hats
GLASSES	glasses, sun-glasses
BELTS	belts
WATCHES	watch
TOPS	tops (blouses, shirts, knitwear, etc)
OUTWEARS	coats, jackets, jumpers, paddings, etc
SKIRTS	skirts
PANTS	pants
WHOLEBODIES	dresses, jumpsuits
JEWELRIES	jewelry (rings, necklaces, etc)
ACCESSORIES	accessories

Response Data > Results > Recommendation

Name	Type	Description
id	String	Product code to recommend
url	String	Recommended product information url
context	Object	Context information inserted in Data Management API
imageInfo	Object	Image information entered in Data Management API (Detection information, Image URL) null if showImageInfo is false
imageInfo.detection	String	Detection information of the product
imageInfo.content	String	The url of the product image used in the analysis

Example Response

Example 1. Search by Image URL

• context, imageInfo not included

• limit is set to 10 (default)

{
  "data": {
    "image": {
      "type": "url",
      "content": "http://imageserver.com/query/image.jpg"
    },
    "limit": 10,
    "detection": null,
    "weightColorFeature": "MEDIUM",
    "showContext": null,
    "showImageInfo": null,
    "results": [
      {
        "id": "0",
        "category": "TOPS",
        "bbox": [
          0.21605325,
          0.2837942,
          0.50699013,
          0.75328624
        ],
        "recommendation": [
          {
            "id": "MYzlj9KPsyQBtchdmIUa",
            "url": "http://shop.net/product/MYzlj9KPsyQBtchdmIUa",
            "context": null,
            "imageInfo": null
          },
          {
            "id": "MwTO7mcvtNgpAD32n0yq",
            "url": "http://shop.net/product/MwTO7mcvtNgpAD32n0yq",
            "context": null,
            "imageInfo": null
          },
          {
            "id": "YqTfcdOGZi90aP7Rk3oL",
            "url": "http://shop.net/product/YqTfcdOGZi90aP7Rk3oL",
            "context": null,
            "imageInfo": null
          },
          {
            "id": "BatjlcFOLvoz4q81Dhpm",
            "url": "http://shop.net/product/BatjlcFOLvoz4q81Dhpm",
            "context": null,
            "imageInfo": null
          },
          {
            "id": "w3lmJryV0nF8NSQxivBU",
            "url": "http://shop.net/product/w3lmJryV0nF8NSQxivBU",
            "context": null,
            "imageInfo": null
          },
          {
            "id": "hQM0yBHtA3LNFczsVCub",
            "url": "http://shop.net/product/hQM0yBHtA3LNFczsVCub",
            "context": null,
            "imageInfo": null
          },
          {
            "id": "bzKYuEjSMe94WDxXoT1I",
            "url": "http://shop.net/product/bzKYuEjSMe94WDxXoT1I",
            "context": null,
            "imageInfo": null
          },
          {
            "id": "xsoGLOj9HZUfrdlzpiCw",
            "url": "http://shop.net/product/xsoGLOj9HZUfrdlzpiCw",
            "context": null,
            "imageInfo": null
          },
          {
            "id": "fzZTe8qG4PbprYksw7uv",
            "url": "http://shop.net/product/fzZTe8qG4PbprYksw7uv",
            "context": null,
            "imageInfo": null
          },
          {
            "id": "VoTsF4iyvdPZaQK87nJl",
            "url": "http://shop.net/product/VoTsF4iyvdPZaQK87nJl",
            "context": null,
            "imageInfo": null
          }
        ]
      },
      {
        "id": "1",
        "category": "HATS",
        "bbox": [
          0.0036665350000000003,
          0.24149363000000001,
          0.42002466,
          0.35420066
        ],
        "recommendation": [
          {
            "id": "TF4q0gXPejJnMi1vWGyR",
            "url": "http://shop.net/product/TF4q0gXPejJnMi1vWGyR",
            "context": null,
            "imageInfo": null
          },
          {
            "id": "nk6LVh5aDq8tCN2BxcFu",
            "url": "http://shop.net/product/nk6LVh5aDq8tCN2BxcFu",
            "context": null,
            "imageInfo": null
          },
          {
            "id": "OB3pmA7xuzyrWktFUjML",
            "url": "http://shop.net/product/OB3pmA7xuzyrWktFUjML",
            "context": null,
            "imageInfo": null
          },
          {
            "id": "VQJcPAFB2asZODr9qyx8",
            "url": "http://shop.net/product/VQJcPAFB2asZODr9qyx8",
            "context": null,
            "imageInfo": null
          },
          {
            "id": "jQ0nX5dIZsTAKikWv7zL",
            "url": "http://shop.net/product/jQ0nX5dIZsTAKikWv7zL",
            "context": null,
            "imageInfo": null
          },
          {
            "id": "4ZlM2HQ3YDo7cBUAbd5W",
            "url": "http://shop.net/product/4ZlM2HQ3YDo7cBUAbd5W",
            "context": null,
            "imageInfo": null
          }
        ]
      }
    ]
  },
  "error": null,
  "status": "ok"
}

Example 2. Search by Base64 Encoding

• context, imageInfo field not included

• limit is set to 10 (default)

{
  "data": {
    "image": {
      "type": "base64",
      "content": null
    },
    "limit": 10,
    "detection": null,
    "weightColorFeature": "MEDIUM",
    "showContext": null,
    "showImageInfo": null,
    "results": [
      {
        "id": "0",
        "category": "TOPS",
        "bbox": [
          0.21605325,
          0.2837942,
          0.50699013,
          0.75328624
        ],
        "recommendation": [
          {
            "id": "MYzlj9KPsyQBtchdmIUa",
            "url": "http://shop.net/product/MYzlj9KPsyQBtchdmIUa",
            "context": null,
            "imageInfo": null
          },
          {
            "id": "MwTO7mcvtNgpAD32n0yq",
            "url": "http://shop.net/product/MwTO7mcvtNgpAD32n0yq",
            "context": null,
            "imageInfo": null
          },
          {
            "id": "YqTfcdOGZi90aP7Rk3oL",
            "url": "http://shop.net/product/YqTfcdOGZi90aP7Rk3oL",
            "context": null,
            "imageInfo": null
          },
          {
            "id": "BatjlcFOLvoz4q81Dhpm",
            "url": "http://shop.net/product/BatjlcFOLvoz4q81Dhpm",
            "context": null,
            "imageInfo": null
          },
          {
            "id": "w3lmJryV0nF8NSQxivBU",
            "url": "http://shop.net/product/w3lmJryV0nF8NSQxivBU",
            "context": null,
            "imageInfo": null
          },
          {
            "id": "hQM0yBHtA3LNFczsVCub",
            "url": "http://shop.net/product/hQM0yBHtA3LNFczsVCub",
            "context": null,
            "imageInfo": null
          },
          {
            "id": "bzKYuEjSMe94WDxXoT1I",
            "url": "http://shop.net/product/bzKYuEjSMe94WDxXoT1I",
            "context": null,
            "imageInfo": null
          },
          {
            "id": "xsoGLOj9HZUfrdlzpiCw",
            "url": "http://shop.net/product/xsoGLOj9HZUfrdlzpiCw",
            "context": null,
            "imageInfo": null
          },
          {
            "id": "fzZTe8qG4PbprYksw7uv",
            "url": "http://shop.net/product/fzZTe8qG4PbprYksw7uv",
            "context": null,
            "imageInfo": null
          },
          {
            "id": "VoTsF4iyvdPZaQK87nJl",
            "url": "http://shop.net/product/VoTsF4iyvdPZaQK87nJl",
            "context": null,
            "imageInfo": null
          }
        ]
      },
      {
        "id": "1",
        "category": "HATS",
        "bbox": [
          0.0036665350000000003,
          0.24149363000000001,
          0.42002466,
          0.35420066
        ],
        "recommendation": [
          {
            "id": "TF4q0gXPejJnMi1vWGyR",
            "url": "http://shop.net/product/TF4q0gXPejJnMi1vWGyR",
            "context": null,
            "imageInfo": null
          },
          {
            "id": "nk6LVh5aDq8tCN2BxcFu",
            "url": "http://shop.net/product/nk6LVh5aDq8tCN2BxcFu",
            "context": null,
            "imageInfo": null
          },
          {
            "id": "OB3pmA7xuzyrWktFUjML",
            "url": "http://shop.net/product/OB3pmA7xuzyrWktFUjML",
            "context": null,
            "imageInfo": null
          },
          {
            "id": "VQJcPAFB2asZODr9qyx8",
            "url": "http://shop.net/product/VQJcPAFB2asZODr9qyx8",
            "context": null,
            "imageInfo": null
          },
          {
            "id": "jQ0nX5dIZsTAKikWv7zL",
            "url": "http://shop.net/product/jQ0nX5dIZsTAKikWv7zL",
            "context": null,
            "imageInfo": null
          },
          {
            "id": "4ZlM2HQ3YDo7cBUAbd5W",
            "url": "http://shop.net/product/4ZlM2HQ3YDo7cBUAbd5W",
            "context": null,
            "imageInfo": null
          }
        ]
      }
    ]
  },
  "error": null,
  "status": "ok"
}