Apsis Logo
API docs by Redocly

Visual Search Docs (1.0.0.)

API Support: apsis@arnia.com URL: https://apsis.ai/

Introduction

The Visual Search API is designed based on RESTful architecture, which allows for consistent and organized resource-oriented URLs. The API accepts raw application json bodies, and returns responses encoded in JSON format. In order to maintain standardization, the API follows HTTP response codes, authentication, and verbs.

Visual search uses images as the input query instead of text. It allows users to search for similar or related products, images, or information by simply uploading an image or taking a picture with their smartphone camera.

The technology behind visual search involves using advanced computer vision and machine learning algorithms to analyze and understand the visual attributes of the image, such as color, texture, shape, and patterns. The system then compares these attributes to a database of indexed images to identify the closest matches.

Visual Search enables users to discover products or information that they may not have been able to find through traditional text-based search, resulting in an enhanced user experience and improved engagement.

Visual Search Context

As a client looking to implement visual search technology, the first step is to carefully evaluate and select the most appropriate AI model for your specific product catalog. This involves understanding the unique characteristics and features of the products in your catalog, as well as the search behaviors of your target audience. By selecting the right AI model, you can ensure that your visual search solution accurately identifies and matches the visual attributes of your products, providing relevant and personalized search results to your customers. This helps to enhance their shopping experience and increase engagement with your brand.

The available search models (Contexts) you can choose to search are:

  • Fashion
  • Interior Design

Each product assortment (store) must have a separate Visual Search Index. In order to push documents and perform searches you need one API Key for each Index.

Authentication and Authorization Overview

API keys provide a secure and convenient way for client applications to access API services. When a client application is authorized to use an API, it is issued an API key that serves as a unique identifier for the application.

With the API Key, the client application can obtain a Bearer token that is used to authorize API calls. The Bearer token is a type of access token that is sent along with the API request to authenticate and authorize the request.

By using API keys and Bearer tokens, API providers can ensure that only authorized client applications can access their services, while also providing a convenient way for developers to integrate the API into their applications. This helps to improve security and reduce the risk of unauthorized access to sensitive data.

To use API keys, client applications must first be registered with the API provider and obtain the appropriate permissions. Once authorized, the client application can generate API keys and use them to obtain Bearer tokens, which can then be used to make authorized API calls.

To authorize API requests, a Bearer token must be obtained by following the authentication process. This token serves as a credential that validates the client's identity and grants access to the API. However, it is important to note that the token has an expiration time, after which subsequent API requests will be denied with a 401 response code. In such a scenario, the client must perform the authentication process again to obtain a new token that can be used to authorize future API requests. This ensures that only authorized clients can access the API and maintain the security and integrity of the system.

curl -X 'GET' \
  'https://auth.apsis.ai/api-keys/authenticate' \
  -H 'accept: application/json' \
  -H 'x-api-Key: xxxx-xxxx-xxxx-xxxx-xxxx' \
  -H 'secret: xxxxxxx'

Account

After registering an account, the admin interface will be available, and it can be used to create API Keys:

Create a new Api Key :

new api key

Save the generated Api Key and secret in your client configuration:

api-key-generated

Client Configuration

To effectively use the Visual Search API, certain values must be saved in the client configuration. These values are essential for the API to function properly and enable the client to interact with it. It is imperative that the client stores these values in their configuration settings to ensure smooth communication between their system and the Visual Search API. Failing to store these values can result in errors or incomplete functionality of the API.

Configuration

Scope

Example

Description

Visual Search Auth Url

Global

https://auth.apsis.ai

The authentication endpoint.

Visual Search Api Url

Global

https://api.apsis.ai

The search api endpoint.

Api Key

Store(Assortment)

 

The Api Key created on your apsis.ai account.

Api Secret

Store(Assortment)

 

The Secret created on your account.

Context

Store(Assortment)

fashion

The type of Visual Search model that fits the Assortment on your current Store.
One of fashion, furniture.

Api Keys

Obtain a JSON Web Token (JWT) by providing an API Key and Secret.

Retrieves a Api Keys resource.

Authorizations:
apiKey
header Parameters
x-api-Key
string
Example: 3dfc6522-5370-4fcb-a9ff-1474eac313cb

Api Key

secret
string
Example: f87e8f3937

Api Key Secret

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Test if the API Key and Secret are valid

Retrieves a Api Keys resource.

Authorizations:
apiKey
header Parameters
x-api-Key
string
Example: 3dfc6522-5370-4fcb-a9ff-1474eac313cb

Api Key

secret
string
Example: f87e8f3937

Api Key Secret

Responses

Response samples

Content type
application/json
{
  • "data": [ ]
}

Document Indexing

To enable efficient and accurate document indexing, we support document indexing based on feed data. A feed is a file that contains information about the products available on a client platform, such as an e-commerce website.

To be eligible for indexing, the feed must be publicly available and accessible to our indexing systems. It should contain links to product images, as well as their respective internal reference or product ID. This information allows us to create an index of the products, which can then be used to power visual search and other AI-driven features.

By indexing products based on feed data, we can ensure that our search results accurately reflect the products available on the client platform. This allows for more relevant and accurate search results for users, as well as a better user experience overall.

To get started with document indexing based on feed data, clients should ensure that their feed is properly formatted and accessible to our indexing systems. This may involve working with our technical team to ensure that the feed meets our requirements and specifications. Once the feed has been properly set up, our indexing systems can begin the process of creating an index of the available products.

→ Content example:

[
  {
    "path":"https://example.com/media/catalog/product/w/b/wb05-red-0.jpg",
    "meta":{
      "id":10
    }
  },
  {
    "path":"https://example.com/media/catalog/product/w/b/wb06-red-0.jpg",
    "meta":{
      "id":11
    }
  },
  {
    "path":"https://example.com/media/catalog/product/w/b/wb06-red-0_alt1.jpg",
    "meta":{
      "id":11
    }
  },
  {
    "path":"https://example.com/media/catalog/product/w/b/wb03-purple-0.jpg",
    "meta":{
      "id":12
    }
  },
  {
    "path":"https://example.com/media/catalog/product/w/b/wb07-brown-0.jpg",
    "meta":{
      "id":13
    }
  },
  {
    "path":"https://example.com/media/catalog/product/w/b/wb04-blue-0.jpg",
    "meta":{
      "id":14
    }
  },
  {
    "path":"https://example.com/media/catalog/product/u/g/ug06-lb-0.jpg",
    "meta":{
      "id":15
    }
  },
  {
    "path":"https://example.com/media/catalog/product/u/g/ug07-bk-0.jpg",
    "meta":{
      "id":16
    }
  },
  {
    "path":"https://example.com/media/catalog/product/u/g/ug07-bk-0_alt1.jpg",
    "meta":{
      "id":16
    }
  },
  {
    "path":"https://example.com/media/catalog/product/u/g/ug04-bk-0.jpg",
    "meta":{
      "id":17
    }
  },
  {
    "path":"https://example.com/media/catalog/product/u/g/ug02-bk-0.jpg",
    "meta":{
      "id":18
    }
  },
  {
    "path":"https://example.com/media/catalog/product/u/g/ug05-gr-0.jpg",
    "meta":{
      "id":19
    }
  }
]

Visual Search Index

Create or update your Visual Search Index.

Use this endpoint to register a new feed or refresh existing data with an update to your Visual Search Index. In order to receive file search results, at least one feed must be successfully indexed.

Please ensure that the feed always reflects the current version of the catalog that you want to expose via Visual Search. Note that partial or incremental updates are not currently supported.

Authorizations:
apiKey
Request Body schema: application/json
feedUrl
required
string <= 2083 characters

Your publicly available catalog feed url.

context
required
string
Enum: "fashion" "furniture"
  • fashion - the indexed articles are related to fashion and accessories.
  • furniture - the indexed articles are related to interior design.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "status": "true",
  • "error": "",
  • "data": {}
}

Retrieve a specific feed record based on feed identifier.

Use this endpoint to check the status and details of your feed.

Authorizations:
apiKey
path Parameters
id
required
integer
Example: 1

Unique identifier for the object.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

File Search

Creates a new file search based on the searched image content.

Creates a Files resource.

Authorizations:
apiKey
Request Body schema: application/json
fileName
required
string

Name of the image file.

base64Image
required
string

This is a string representation of an image file that has been encoded using the Base64 encoding scheme.

context
string
Enum: "fashion" "furniture"

This parameter is required for searches on demo data. For searches authorized by an API Key, the search context will be determined by the context of your index.

priority
any
Default: "default"
Enum: "default" "shape" "color"

This parameter is experimental and determines the weight given to specific attributes when comparing images for similarity.

Responses

Request samples

Content type
application/json
{
  • "fileName": "fileName.jpg",
  • "base64Image": "V+.jTj!",
  • "context": "fashion",
  • "priority": "default"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

This endpoint allows you to request the full, non-paginated Visual Search response.

The data property may be empty if no results are available yet.

Authorizations:
apiKey
path Parameters
id
required
string <uuid>
Example: 601670a3-4e01-4f85-b08f-771ddbed7bdf

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

This endpoint allows you to request a paginated Visual Search response.

The data property may be empty if no results are available yet.

Authorizations:
apiKey
path Parameters
id
required
string <uuid>
Example: 601670a3-4e01-4f85-b08f-771ddbed7bdf
page
required
integer >= 1
Default: 1
Example: 1

The page number to retrieve.

query Parameters
itemsPerPage
integer [ 1 .. 50 ]
Default: 10

This parameter represents the desired number of results per page.

includeFavourites
integer
Default: 0
Enum: 0 1
Example: includeFavourites=1

Whether to include Favourites resource details

poi
integer or null
Example: poi=1
The index from the poinOfInterest to be retrurned.
If not present, all keys will be returned'.
resizeProfile
string
Default: null
Value: "widget" 
Return resized image paths based on predefined profiles. Original image paths are returned as default.

Responses

Response samples

Content type
application/json
{
  • "status": true,
  • "error": "string",
  • "data": [],
  • "metadata": {
    }
}