<commit_before># ViSearch Python SDK

[<img src="https://travis-ci.org/visenze/visearch-sdk-python.svg">](https://travis-ci.org/visenze/visearch-sdk-python) [<img src="https://img.shields.io/pypi/v/visearch.svg">](https://pypi.python.org/pypi/visearch) [![CodeFactor](https://www.codefactor.io/repository/github/visenze/visearch-sdk-python/badge)](https://www.codefactor.io/repository/github/visenze/visearch-sdk-python)

----
## Table of Contents
 1. [Overview](#1-overview)
 2. [Setup](#2-setup)
 3. [Initialization](#3-initialization)
 4. [Indexing Images](#4-indexing-images)
      - 4.1 [Indexing Your First Images](#41-indexing-your-first-images)
      - 4.2 [Image with Metadata](#42-image-with-metadata)
      - 4.3 [Updating Images](#43-updating-images)
      - 4.4 [Removing Images](#44-removing-images)
      - 4.5 [Check Indexing Status](#44-check-indexing-status)
 5. [Solution APIs](#5-solution-apis)
      - 5.1 [Visually Similar Recommendations](#51-visually-similar-recommendations)
      - 5.2 [Search by Image](#52-search-by-image)
        - 5.2.1 [Selection Box](#521-selection-box)
        - 5.2.2 [Resizing Settings](#522-resizing-settings)
      - 5.3 [Search by Color](#53-search-by-color)
      - 5.4 [Multiproduct Search](#54-multiproduct-search)
 6. [Search Results](#6-search-results)
 7. [Advanced Search Parameters](#7-advanced-search-parameters)
      - 7.1 [Retrieving Metadata](#71-retrieving-metadata)
      - 7.2 [Filtering Results](#72-filtering-results)
      - 7.3 [Result Score](#73-result-score)
      - 7.4 [Automatic Object Recognition Beta](#74-automatic-object-recognition-beta)
 8. [Declaration](#8-declaration)

----

## 1. Overview
ViSearch is an API that provides accurate, reliable and scalable image search. ViSearch API provides endpoints that let developers index their images and perform image searches efficiently. ViSearch API can be easily integrated into your web and mobile applications. More details about ViSearch API can be found in the [documentation](http://www.visenze.com/docs/overview/introduction).

The ViSearch Python SDK is an open source software for easy integration of ViSearch Search API with your application server. It provides three search methods based on the ViSearch Search API - pre-indexed search, color search and upload search. The ViSearch Python SDK also provides an easy integration of the ViSearch Data API which includes data inserting and data removing. For source code and references, visit the github [repository](https://github.com/visenze/visearch-sdk-python).

* Supported on Python 2.7+ and 3.3+
 
## 2. Setup
To install visearch, simply:

```
$ pip install visearch
```

To upgrade visearch to latest version, simply:

```
$ pip install -U visearch
```

## 3. Initialization
To start using ViSearch API, initialize ViSearch client with your ViSearch API credentials. Your credentials can be found in [ViSearch Dashboard](https://dashboard.visenze.com):

```python
from visearch import client

access_key = 'your app access key'
secret_key = 'your app secret key'

api = client.ViSearchAPI(access_key, secret_key)
```
Please init ViSearch client in this way if you connect to another endpoint rather than default (https://visearch.visenze.com)
```python
api = client.ViSearchAPI(access_key, secret_key, host="https://custom-visearch.yourdomain.com")
```

## 4. Indexing Images


### 4.1 Indexing Your First Images

Built for scalability, ViSearch API enables fast and accurate searches on high volume of images. Before making your first image search, you need to prepare a list of images and index them into ViSearch by calling the /insert endpoint. Each image must have a unique identifier and a publicly downloadable URL. ViSearch will parallelly fetch your images from the given URLs, and index the downloaded for searching. After the image indexes are built, you can start searching for [similar images using the unique identifier](https://github.com/visenze/visearch-sdk-python/blob/master/README_md.md#51-pre-indexed-search), [using a color](https://github.com/visenze/visearch-sdk-python/blob/master/README_md.md#52-color-search), or [using another image](https://github.com/visenze/visearch-sdk-python/blob/master/README_md.md#53-upload-search).

To index your images, prepare a list of images and call the /insert endpoint. 

```python
# the list of images to be indexed
# the unique identifier of the image 'im_name', the publicly downloadable url of the image 'im_url'
images = [
    {'im_name': 'red_dress', 'im_url': 'http://mydomain.com/images/red_dress.jpg'},
    {'im_name': 'blue_dress', 'im_url': 'http://mydomain.com/images/blue_dress.jpg'}
]
# calls the /insert endpoint to index the image
response = api.insert(images)
```

 > Each ```insert``` call to ViSearch accepts a maximum of 100 images. We recommend indexing your images in batches of 100 for optimized image indexing speed.

### 4.2 Image with Metadata

Images usually come with descriptive text or numeric values as metadata, for example:
title, description, category, brand, and price of an online shop listing image
caption, tags, geo-coordinates of a photo.

ViSearch combines the power of text search with image search. You can index your images with metadata, and leverage text based query and filtering for even more accurate image search results, for example:
limit results within a price range
limit results to certain tags, and some keywords in the captions
For detailed reference for result filtering, see [Advanced Search Parameters](https://github.com/visenze/visearch-sdk-python/blob/master/README_md.md#7-advanced-search-parameters).

To index your images with metadata, first you need to configure the metadata schema in [ViSearch Dashboard](https://dashboard.visenze.com). You can add and remove metadata keys, and modify the metadata types to suit your needs.

Let's assume you have the following metadata schema configured:

| Name | Type | Searchable |
| ---- | ---- | ---------- |
| title | string | true |<commit_msg>Drop python 3.3, since latest request doesn't support well<commit_after># ViSearch Python SDK

[<img src="https://travis-ci.org/visenze/visearch-sdk-python.svg">](https://travis-ci.org/visenze/visearch-sdk-python) [<img src="https://img.shields.io/pypi/v/visearch.svg">](https://pypi.python.org/pypi/visearch) [![CodeFactor](https://www.codefactor.io/repository/github/visenze/visearch-sdk-python/badge)](https://www.codefactor.io/repository/github/visenze/visearch-sdk-python)

----
## Table of Contents
 1. [Overview](#1-overview)
 2. [Setup](#2-setup)
 3. [Initialization](#3-initialization)
 4. [Indexing Images](#4-indexing-images)
      - 4.1 [Indexing Your First Images](#41-indexing-your-first-images)
      - 4.2 [Image with Metadata](#42-image-with-metadata)
      - 4.3 [Updating Images](#43-updating-images)
      - 4.4 [Removing Images](#44-removing-images)
      - 4.5 [Check Indexing Status](#44-check-indexing-status)
 5. [Solution APIs](#5-solution-apis)
      - 5.1 [Visually Similar Recommendations](#51-visually-similar-recommendations)
      - 5.2 [Search by Image](#52-search-by-image)
        - 5.2.1 [Selection Box](#521-selection-box)
        - 5.2.2 [Resizing Settings](#522-resizing-settings)
      - 5.3 [Search by Color](#53-search-by-color)
      - 5.4 [Multiproduct Search](#54-multiproduct-search)
 6. [Search Results](#6-search-results)
 7. [Advanced Search Parameters](#7-advanced-search-parameters)
      - 7.1 [Retrieving Metadata](#71-retrieving-metadata)
      - 7.2 [Filtering Results](#72-filtering-results)
      - 7.3 [Result Score](#73-result-score)
      - 7.4 [Automatic Object Recognition Beta](#74-automatic-object-recognition-beta)
 8. [Declaration](#8-declaration)

----

## 1. Overview
ViSearch is an API that provides accurate, reliable and scalable image search. ViSearch API provides endpoints that let developers index their images and perform image searches efficiently. ViSearch API can be easily integrated into your web and mobile applications. More details about ViSearch API can be found in the [documentation](http://www.visenze.com/docs/overview/introduction).

The ViSearch Python SDK is an open source software for easy integration of ViSearch Search API with your application server. It provides three search methods based on the ViSearch Search API - pre-indexed search, color search and upload search. The ViSearch Python SDK also provides an easy integration of the ViSearch Data API which includes data inserting and data removing. For source code and references, visit the github [repository](https://github.com/visenze/visearch-sdk-python).

* Supported on Python 2.7+ and 3.4+
 
## 2. Setup
To install visearch, simply:

```
$ pip install visearch
```

To upgrade visearch to latest version, simply:

```
$ pip install -U visearch
```

## 3. Initialization
To start using ViSearch API, initialize ViSearch client with your ViSearch API credentials. Your credentials can be found in [ViSearch Dashboard](https://dashboard.visenze.com):

```python
from visearch import client

access_key = 'your app access key'
secret_key = 'your app secret key'

api = client.ViSearchAPI(access_key, secret_key)
```
Please init ViSearch client in this way if you connect to another endpoint rather than default (https://visearch.visenze.com)
```python
api = client.ViSearchAPI(access_key, secret_key, host="https://custom-visearch.yourdomain.com")
```

## 4. Indexing Images


### 4.1 Indexing Your First Images

Built for scalability, ViSearch API enables fast and accurate searches on high volume of images. Before making your first image search, you need to prepare a list of images and index them into ViSearch by calling the /insert endpoint. Each image must have a unique identifier and a publicly downloadable URL. ViSearch will parallelly fetch your images from the given URLs, and index the downloaded for searching. After the image indexes are built, you can start searching for [similar images using the unique identifier](https://github.com/visenze/visearch-sdk-python/blob/master/README_md.md#51-pre-indexed-search), [using a color](https://github.com/visenze/visearch-sdk-python/blob/master/README_md.md#52-color-search), or [using another image](https://github.com/visenze/visearch-sdk-python/blob/master/README_md.md#53-upload-search).

To index your images, prepare a list of images and call the /insert endpoint. 

``python
# the list of images to be indexed
# the unique identifier of the image 'im_name', the publicly downloadable url of the image 'im_url'
images = [
    {'im_name': 'red_dress', 'im_url': 'http://mydomain.com/images/red_dress.jpg'},
    {'im_name': 'blue_dress', 'im_url': 'http://mydomain.com/images/blue_dress.jpg'}
]
# calls the /insert endpoint to index the image
response = api.insert(images)
```

 > Each ```insert``` call to ViSearch accepts a maximum of 100 images. We recommend indexing your images in batches of 100 for optimized image indexing speed.

### 4.2 Image with Metadata

Images usually come with descriptive text or numeric values as metadata, for example:
title, description, category, brand, and price of an online shop listing image
caption, tags, geo-coordinates of a photo.

ViSearch combines the power of text search with image search. You can index your images with metadata, and leverage text based query and filtering for even more accurate image search results, for example:
limit results within a price range
limit results to certain tags, and some keywords in the captions
For detailed reference for result filtering, see [Advanced Search Parameters](https://github.com/visenze/visearch-sdk-python/blob/master/README_md.md#7-advanced-search-parameters).

To index your images with metadata, first you need to configure the metadata schema in [ViSearch Dashboard](https://dashboard.visenze.com). You can add and remove metadata keys, and modify the metadata types to suit your needs.

Let's assume you have the following metadata schema configured:

| Name | Type | Searchable |
| ---- | ---- | ---------- |
| title | string | true |
{'fraction_non_alphanumeric': 0.1113135663408978, 'fraction_numerical': 0.01755838992877257, 'mean_word_length': 4.333480565371024, 'pattern_counts': {'":': 0, '<': 7, '<?xml version=': 0, '>': 9, 'https://': 30, 'lorem ipsum': 0, 'www.': 6, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 7, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5573748', 'n_tokens_mistral': 3636, 'n_tokens_neox': 3374, 'n_words': 1246}