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

{% embed url="<https://api.omnious.com/lens/v1.1/search>" %}

**Version 1.2: Recommended for new LENS users**

{% embed url="<https://api.omnious.com/lens/v1.2/search>" %}

## **POST /**

### **Request**

#### **Header**

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

#### **Body**

| **Name**           | **Type** | **Required** | **Description**                                                                                                                                                                                                                                       |
| ------------------ | -------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **i**mage          | 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            | <p>Requested image contents depending on type</p><p>if url: URL of the requested image</p><p>if base64: requested image encoded in base64<br><strong>A prefix is required for the base64 string. Please see below the chart for details.</strong></p> |
| limit              | Integer  | X            | <p>Maximum number of items to recommend</p><ul><li>default: 10</li><li>max: 500</li></ul>                                                                                                                                                             |
| weightColorFeature | String   | X            | <p>Weight of color to be reflected in recommendations</p><ul><li>default: MEDIUM</li><li><p>Selectable from the following values</p><ul><li>LOW</li><li>MEDIUM</li><li>HIGH</li></ul></li></ul>                                                       |
| showContext        | Bool     | X            | <p>Whether to display context information</p><ul><li>default: false</li></ul>                                                                                                                                                                         |
| showImageInfo      | Bool     | X            | <p>Whether to display image information</p><ul><li>default: false</li></ul>                                                                                                                                                                           |

{% hint style="info" %}
**Updating images with base64 type:**

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

#### 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)**

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

**Example 2. Search by URL (without context information)**

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

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

```javascript
{
  "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   | <p>returns null if no Error</p><p>If Error it takes the below format</p><ul><li>error.code: Error Code defined in the Error menu</li><li>error.message: Error Message</li></ul> |
| 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          | <p>Requested image contents depending on type</p><p>if url: URL of the requested image</p><p>if base64: requested image encoded in base64</p>                                                   |
| limit              | Integer         | <p>Maximum number of items to recommend</p><ul><li>default: 10</li><li>max: 500</li></ul>                                                                                                       |
| weightColorFeature | String          | <p>Weight of color to be reflected in recommendations</p><ul><li>default: MEDIUM</li><li><p>Selectable from the following values</p><ul><li>LOW</li><li>MEDIUM</li><li>HIGH</li></ul></li></ul> |
| showContext        | Bool            | <p>Whether to display context information</p><ul><li>default: false</li></ul>                                                                                                                   |
| showImageInfo      | Bool            | <p>Whether to display image information</p><ul><li>default: false</li></ul>                                                                                                                     |
| 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]       | <p>Bounding Area of the Detected Product. Takes values between 0\~1. Numbers are in the following order</p><p>\[top, left, width, height]</p><p><img src="https://669000487-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MhpVpDhKLV5QI-p1lmY%2Fuploads%2Fgit-blob-c0d04dc8b6d7b7d679784978a4cb93a994bcc8df%2FImage%20Area%20(1).png?alt=media" alt="" data-size="original"></p> |
| 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   | <p>Image information entered in Data Management API</p><p>(Detection information, Image URL)</p><p>null if showImageInfo is false</p> |
| 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)

```javascript
{
  "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)**

```javascript
{
  "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"
}
```
