Navbar
Logo retina
http shell

Introduction

welcome

Welcome to the official documentation for Markable Lens API - for developers. This serves as a guide for developers integrate with Markable’s visual search platform API, illustrated using API specifications and API integration code examples.

To be able to use/access this API you will need to be a verified developer, please request a free trial to get started. We’ll get back to you with your user credentials.

This API and documentation is currently in private beta - subject for modifications.

Getting Started

To be able to use/access this API you will need to be a verified developer, please request a free trial to get started. We’ll contact you with your user credentials. If you have your credentials from us in hand already, please follow the steps below.

  1. Then, login with your user credentials.

  2. Once you have logged in, you will get your user_access_token. With this token, get your default client we have created for you.

  3. Then, authenticate your Client to get your client_access_token.

  4. Make your first visual search. You will be using your client_access_token from above.

This API and documentation is currently in private beta - subject for modifications.

Versioning

The platform behind Markable Lens API is continuesly being improved for stability, accuracy, and new features. We may introduce changes with bugs, so to minimize the impact for our integrated users/partners the API will be versioned.

Currently the API is in private beta and the versioning process is not being implemented, but as soon as we move into public beta the versioning will be in place.

Rate Limits

For have fair usage of our APIs, we have enforced rate limits to the number of search results one can perform per minute. For each client,

Depending on your use casel, you can get in touch to have your limits increased.

Errors

Markable uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error due to information provided (e.g., a required parameter was omitted, a catalog item operation failed, etc.), and codes in the 5xx range indicate an error with our servers.

HTTP Error Codes

Code Description
400 Bad Request - The request is invalid.
401 Unauthorized - The API key is wrong.
403 Forbidden - The specified resource is hidden for admins only.
404 Not Found - The specified could not be found.
405 Method Not Allowed - The request method is invalid for specified resource.
406 Not Acceptable - The request format that isn’t valid JSON.
429 Too Many Requests - You have reached the default request limit. (This can be adjusted depending on needs.)
500 Internal Server Error - We had a problem with our server. Please try again later.
503 Service Unavailable - We’re temporarially offline for maintanance. Please try again later.

The Error Object

Example: Error Object

{
    "_type": "Error",
    "id": "abc",
    "code": 400,
    "detail": "Something went wrong."
}

Example: Error Response

{
    "errors": [
        {
            "_type": "Error",
            "id": "abc",
            "code": 400,
            "detail": "Something went wrong."
        }
    ]
}

A failed request will return a list of error objects according to the JSON API Specification.

An error object MAY have the following members:

Attribute Description
id A unique identifier for this particular occurrence of the problem.
links A links object containing the following members.
status The HTTP status code applicable to this problem, expressed as a string value.
code An application-specific error code, expressed as a string value.
title A short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization.
detail A human-readable explanation specific to this occurrence of the problem. Like title, this field’s value can be localized.
source An object containing references to the source of the error.
meta A meta object containing non-standard meta-information about the error.

Objects

The object defintions to be aware of when working with Markable Lens API.

catalog_icon Catalog

Example: Catalog Object

{
    "_type": "Catalog",
    "_id": "1",
    "size": 5,
    "name": "catalog-1",
    "description": "My first catalog",
    "schema": "product",
    "created_at": "2017-01-01T00:00:00Z",
    "updated_at": "2017-01-01T00:00:00Z"
}

Schema: Catalog Object

{
    "$schema": "http://json-schema.org/draft-04/schema",
    "type": "object",
    "description": "Catalog",
    "required": [
        "name",
        "schema"
    ],
    "properties": {
        "_type": {
            "type": "string",
            "readOnly": true,
            "default": "Catalog"
        },
        "_id": {
            "type": "string",
            "readOnly": true
        },
        "size": {
            "type": "integer",
            "minimum": 0,
            "readOnly": true
        },
        "user": {
            "type": "object",
            "description": "User",
            "properties": {
                "_type": {
                    "type": "string",
                    "readOnly": true,
                    "default": "User"
                },
                "_id": {
                    "type": "string",
                    "readOnly": true
                }
            }
        },
        "name": {
            "type": "string"
        },
        "description": {
            "type": "string"
        },
        "schema": {
            "type": "string",
            "enum": [
                "product"
            ],
            "default": "product"
        },
        "created_at": {
            "type": "string",
            "format": "date-time",
            "readOnly": true
        },
        "updated_at": {
            "type": "string",
            "format": "date-time",
            "readOnly": true
        }
    },
    "additionalProperties": false
}

A Catalog defines a catalog/group of visual objects/items (e.g. products), that can be indexed and visually searched within images and videos using visual similarity - based on the associated image(s). For us to be able to find what you looking for in your images/videos the items (exact or similar) must be known to Markable‘s visual search engine, either using existing catalogs or your customly defined catalogs.

Attribute Type Description
_type String Type. read-only
_id String A unique identifier. read-only
size Integer Number or items in this catalog. read-only
name String A custom unique name.
description String A custom description.
schema String The schema to be used for this catalog’s items.
Can be: product.
created_at Date Creation date/time. read-only
updated_at Date Updated date/time. read-only

catalog-item_icon Catalog Item

Example: Catalog Item Object

{
    "_type": "CatalogItem",
    "_id": "item-1",
    "schema": "product",
    "catalog": {
        "_type": "Catalog",
        "_id": "1",
        "name": "catalog-1"
    },
    "images": [
        {
            "_type": "Image",
            "_id": "1",
            "uri": "https://markable.ai/data/products/dress/1.png",
            "width": 100,
            "height": 100
        },
        {
            "_type": "Image",
            "_id": "2",
            "uri": "https://markable.ai/data/products/dress/2.png",
            "width": 100,
            "height": 100
        }
    ],
    "category": {
      "_type": "Category",
      "_id": "1",
      "name": "dress"
    }
    "data": {
        "id": "external-id-1",
        "url": "external-url-1",
        "foo": "bar"
    },
    "created_at": "2017-01-01T00:00:00Z",
    "updated_at": "2017-01-01T00:00:00Z"
}

Schema: Catalog Item Object (Product)

{
    "$schema": "http://json-schema.org/draft-04/schema",
    "type": "object",
    "description": "CatalogItem",
    "required": [
        "catalog",
        "images",
        "data"
    ],
    "properties": {
        "_type": {
            "type": "string",
            "readOnly": true,
            "default": "CatalogItem"
        },
        "_id": {
            "type": "string",
            "readOnly": true
        },
        "schema": {
            "type": "string",
            "readOnly": true,
            "default": "product"
        },
        "catalog": {
            "type": "object",
            "description": "Catalog",
            "properties": {
                "_type": {
                    "type": "string",
                    "readOnly": true,
                    "default": "Catalog"
                },
                "_id": {
                    "type": "string"
                },
                "name": {
                    "type": "string"
                }
            }
        },
        "images": {
            "type": "array",
            "items": {
                "type": "object",
                "description": "Image",
                "required": [
                    "uri"
                ],
                "properties": {
                    "_type": {
                        "type": "string",
                        "readOnly": true,
                        "default": "Image"
                    },
                    "_id": {
                        "type": "string",
                        "readOnly": true
                    },
                    "uri": {
                        "anyOf": [
                            {
                                "type": "string",
                                "format": "uri"
                            },
                            {
                                "type": "string",
                                "format": "byte"
                            }
                        ]
                    },
                    "width": {
                        "type": "integer",
                        "minimum": 0,
                        "readOnly": true
                    },
                    "height": {
                        "type": "integer",
                        "minimum": 0,
                        "readOnly": true
                    }
                },
                "additionalProperties": false
            },
            "minItems": 1,
            "uniqueItems": true
        },
        "category": {
            "type": "object",
            "description": "Category",
            "properties": {
                "_type": {
                    "type": "string",
                    "readOnly": true,
                    "default": "Category"
                },
                "_id": {
                    "type": "string"
                },
                "name": {
                    "type": "string"
                }
            }
        },
        "data": {
            "type": "object",
            "additionalProperties": true
        },
        "created_at": {
            "type": "string",
            "format": "date-time",
            "readOnly": true
        },
        "updated_at": {
            "type": "string",
            "format": "date-time",
            "readOnly": true
        }
    },
    "additionalProperties": false
}

A Catalog Item defines an visual object/item (e.g. product), that can be indexed and visually searched within images and videos using visual similarity - based on the associated image(s). Catalog items can be defined as different types of objects, but currently only Product.

Attribute Type Description
_type String Type. read-only
_id String An unique identifier. read-only
catalog Catalog Reference to catalog containing this item.
images Array<Image> List of images - visual representation of this item (object).
category Category Category - taxonomic classification of item (object).
data Object Custom data - semantic representation of this item (object).
created_at Date Creation date/time. read-only
updated_at Date Updated date/time. read-only

image_icon Image

An Image defines an image per definition.

Example: Image Object

{
    "_type": "Image",
    "_id": "image-1",
    "uri": "https://example.com/images/1.png",
    "width": 100,
    "height": 100
}

Schema: Image Object

{
    "$schema": "http://json-schema.org/draft-04/schema",
    "type": "object",
    "description": "Image",
    "required": [
        "uri"
    ],
    "properties": {
        "_type": {
            "type": "string",
            "readOnly": true,
            "default": "Image"
        },
        "_id": {
            "type": "string",
            "readOnly": true
        },
        "uri": {
            "anyOf": [
                {
                    "type": "string",
                    "format": "uri"
                },
                {
                    "type": "string",
                    "format": "byte"
                }
            ]
        },
        "width": {
            "type": "integer",
            "minimum": 0,
            "readOnly": true
        },
        "height": {
            "type": "integer",
            "minimum": 0,
            "readOnly": true
        }
    },
    "additionalProperties": false
}
Attribute Type Description
_type String Type. read-only
_id String An unique identifier. read-only
uri String A valid image URI.
content_type String Image content type. read-only
width Integer Image width in pixels. read-only
height Integer Image height in pixels. read-only

category_icon Category

An Image defines a category per definition.

Example: Category Object

{
    "_type": "Category",
    "_id": "1",
    "name": "dress"
}

Schema: Category Object

{
    "$schema": "http://json-schema.org/draft-04/schema",
    "type": "object",
    "description": "Category",
    "required": [
        "name"
    ],
    "properties": {
        "_type": {
            "type": "string",
            "readOnly": true,
            "default": "Category"
        },
        "_id": {
            "type": "string",
            "readOnly": true
        },
        "name": {
            "type": "string"
        },
        "created_at": {
            "type": "string",
            "format": "date-time",
            "readOnly": true
        },
        "updated_at": {
            "type": "string",
            "format": "date-time",
            "readOnly": true
        }
    },
    "additionalProperties": false
}
Attribute Type Description
_type String Type. read-only
_id String An unique identifier. read-only
name String A custom unique name.

bounding-box_icon Bounding Box

An Bounding Box defines an rectangular area (within an image) which contains a visually detected object.

Example: Bounding Box Object

{
    "_type": "BoundingBox",
    "_id": "1",
    "_score": 0.70,
    "_category": {
        "_type": "Category",
        "_id": "1",
        "name": "dress"
    },
    "x": 0,
    "y": 0,
    "width": 10,
    "height": 10
}

Schema: Bounding Box Object

{
    "$schema": "http://json-schema.org/draft-04/schema",
    "type": "object",
    "description": "BoundingBox",
    "required": [
        "x",
        "y",
        "width",
        "height"
    ],
    "properties": {
        "_type": {
            "type": "string",
            "readOnly": true,
            "default": "BoundingBox"
        },
        "_id": {
            "type": "string",
            "readOnly": true
        },
        "_score": {
            "type": "number",
            "minimum": 0,
            "maximum": 1,
            "multipleOf": 0.01,
            "readOnly": true
        },
        "x": {
            "type": "number",
            "minimum": 0,
            "default": 0
        },
        "y": {
            "type": "number",
            "minimum": 0,
            "default": 0
        },
        "width": {
            "type": "number",
            "minimum": 10
        },
        "height": {
            "type": "number",
            "minimum": 10
        }
    },
    "additionalProperties": false
}
Attribute Type Description
_type String Type. read-only
_id String An unique identifier. read-only
_score Float Confidence score of the classification.
_category Category Category - taxonomic classification of bounding box content (object).
x Float Bounding box offset x coordinate in pixels. read-only
y Float Bounding box offset y coordinate in pixels. read-only
width Float Bounding box offset width in pixels. read-only
height Float Bounding box offset height in pixels. read-only

Authentication

To access Markable Lens API you will need to be a registered developer, if you are not already you need to signup and get verified first.

User

Once you have your user account setup, (ie) your email and password ready, you can get your user_access_token.

These user access tokens can be further used to create Clients. Clients have access tokens of their own.

Example: User Credentials Object

{
    "email": "developer@client.com",
    "password": "password"
}

User Authentication

Example: Request

POST https://auth.markable.ai/auth/user/authorize HTTP/1.1
{
    "data": {
        "email": "developer@client.com",
        "password": "password"
    }
}
curl -X POST https://auth.markable.ai/auth/user/authorize \
-H 'Content-Type: application/json' \
-d '
{
    "data": {
        "email": "developer@client.com",
        "password": "password"
    }
}
'

Example: Response with User Access Token

{
    "data": {
        "access_token": "usertoken123abc"
    }
}

Create authorization (authentication token) for a user.

HTTP Request

POST https://auth.markable.ai/auth/user/authorize

HTTP Headers

Standard

Query Parameters

None

Body

Attribute Type Description
data UserCredentials A valid user credentials object.

Get User and Client

This request gives you user information and further the default client we have created for you. Note that scopes are a concern of tokens and not clients.

GET https://auth.markable.ai/auth/users/ HTTP/1.1
Authorization: Bearer usertoken123abc
curl -X GET https://auth.markable.ai/auth/users/ \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer usertoken123abc'

Example: Response

{
    "data": {
        "type": "User",
        "name": "Developer at Client",
        "email": "developer@client.com",
        "user_id": "user_id_1",
        "clients": [
            {
                "type": "Client",
                "client_id": "client_id_1",
                "client_secret": "client_secret_1",
                "user_id": "user_id_1"
            }
        ]
    }
}

HTTP Request

GET https://auth.markable.ai/auth/users

HTTP Headers

Header Description
Authorization HTTP Bearer Token for authorizing the request.

Format is Bearer :user_access_token, where user_access_token is given by Authentication. required

Client Authentication

To start out with, we have created a default client for you as a user.

For the Lens API, you will be using your client acccess token with every request.

The Client Credentials Object

Example: Client Credentials Object

{
  "client_id": "client_id_1",
  "client_secret": "client_secret_1",
  "scope": "default"
}

The Client Credentials (object) refers to an object that holds your Markable Lens API credentials, i.e. key token (client_id) and secret token (client_secret). These credentials will be available to any verified developer.

Attribute Description
client_id Client ID - i.e. “API key”. required
client_secret Client secret - i.e. “API secret”. required
scope The scope of how the client can be used. Currently ['default', 'search']

Example: Request

POST https://auth.markable.ai/auth/client/authorize HTTP/1.1
{
  "data": {
    "client_id": "client_id_1",
    "client_secret": "client_secret_1",
    "scope": "default"
  }
}
curl -X POST https://auth.markable.ai/auth/client/authorize \
-H 'Content-Type: application/json' \
-d '
{
  "data": {
    "client_id": "client_id_1",
    "client_secret": "client_secret_1",
    "scope": "default"
  }
}
'

Example: Request for Search only tokens that can be Published

POST https://auth.markable.ai/auth/client/authorize HTTP/1.1
{
  "data": {
    "client_id": "client_id_1",
    "client_secret": "client_secret_1",
    "scope": "search"
  }
}
curl -X POST https://auth.markable.ai/auth/client/authorize \
-H 'Content-Type: application/json' \
-d '
{
  "data": {
    "client_id": "client_id_1",
    "client_secret": "client_secret_1",
    "scope": "search"
  }
}
'

Example: Response Client Access Token

{
    "data": {
      "access_token": "clienttoken123"
    }
}

Create authorization (authentication token) for a client.

Security

With the search scope, the resulting client access tokens can be published on the web and will only allow you to do searches. The default tokens on the other hand allow all operations.

HTTP Request

POST https://auth.markable.ai/auth/client/authorize

HTTP Headers

Standard

Query Parameters

None

Body

Attribute Type Description
data ClientCredentials A valid client credentials object.

Catalogs Catalogs

catalog_icon The Catalog Object

A Catalog (object) defines a catalog/group of visual items (e.g. products), that can be indexed and visually searched within images and videos using visual similarity - based on the associated image(s). For us to be able to find what you looking for in your images/videos the items (exact or similar) must be known to Markable‘s visual search engine, either using existing catalogs or your customly defined catalogs.

Catalogs can be of two different schemas; product and style.

Product Catalogs

Product catalogs are a reflection of a list of products sold online in a retail store for example. Each CatalogItem in a product catalog beside images, have a category, a url that you can find the product in and gender associated with it.

Style Catalogs

Style catalogs, however, are free form catalogs with just images and a designated gender. Style catalogs are a list of street images

Example: Catalog Object

{
    "_type": "Catalog",
    "schema": "product",
    "_id": "catalog-id-1",
    "size": 5,
    "name": "catalog-name-1",
    "description": "My first catalog",
    "created_at": "2017-01-01T00:00:00Z",
    "updated_at": "2017-01-01T00:00:00Z"
}
{
    "_type": "Catalog",
    "schema": "style",
    "_id": "catalog-id-2",
    "size": 10,
    "name": "catalog-name-2",
    "description": "My first style catalog",
    "created_at": "2017-01-01T00:00:00Z",
    "updated_at": "2017-01-01T00:00:00Z"
}

Schema: Catalog Object

{
    "$schema": "http://json-schema.org/draft-04/schema",
    "type": "object",
    "description": "Catalog",
    "required": [
        "name",
        "schema"
    ],
    "properties": {
        "_type": {
            "type": "string",
            "readOnly": true,
            "default": "Catalog"
        },
        "_id": {
            "type": "string",
            "readOnly": true
        },
        "size": {
            "type": "integer",
            "minimum": 0,
            "readOnly": true,
            "description": "The number of items in this catalog"
        },
        "user": {
            "type": "object",
            "description": "User",
            "properties": {
                "_type": {
                    "type": "string",
                    "readOnly": true,
                    "default": "User"
                },
                "_id": {
                    "type": "string",
                    "readOnly": true
                }
            }
        },
        "name": {
            "type": "string"
        },
        "description": {
            "type": "string"
        },
        "schema": {
            "enum": ["product", "style"],
            "default": "product"
        },
        "created_at": {
            "type": "string",
            "format": "date-time",
            "readOnly": true
        },
        "updated_at": {
            "type": "string",
            "format": "date-time",
            "readOnly": true
        }
    },
    "additionalProperties": false
}
Attribute Type Description
_type String Type. read-only
_id String A unique identifier. read-only
size Integer Number or items in this catalog. read-only
name String A custom unique name.
description String A custom description.
schema String The schema to be used for this catalog’s items.
Can be: product or style.
created_at Date Creation date/time. read-only
updated_at Date Updated date/time. read-only

create-catalog_icon Create catalog

Example: Request

POST https://catalog.markable.ai/catalogs HTTP/1.1
Authorization: Bearer 123abc
{
    "data": {
        "name": "catalog-1",
        "description": "My first catalog",
        "schema": "product"
    }
}
curl -X POST https://catalog.markable.ai/catalogs \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer 123abc' \
-d '
{
    "data": {
        "name": "catalog-1",
        "description": "My first catalog",
        "schema": "product"
    }
}
'

Example: Response

{
    "data": {
        "_type": "Catalog",
        "_id": "1",
        "size": 0,
        "user": {
            "_type": "User",
            "_id": "1"
        },
        "name": "catalog-1",
        "description": "My first catalog",
        "schema": "product",
        "created_at": "2017-01-01T00:00:00.001Z",
        "updated_at": "2017-01-01T00:00:00.001Z"
    }
}

Create a new catalog.

HTTP Request

POST https://catalog.markable.ai/catalogs

HTTP Headers

Header Description
Authorization HTTP Bearer Token for authorizing the request.

Format is Bearer :access_token, where access_token is given by Authentication. required

Route

None

Body

Attribute Type Description
data Catalog A valid catalog object.

update-catalog_icon Update catalog

Example: Request

PUT https://catalog.markable.ai/catalogs/catalog-1 HTTP/1.1
Authorization: Bearer 123abc
{
    "data": {
        "name": "catalog-1",
        "description": "My first catalog"
    }
}
curl -X PUT https://catalog.markable.ai/catalogs/catalog-1 \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer 123abc' \
-d '
{
    "data": {
        "name": "catalog-1",
        "description": "My first catalog"
    }
}
'

Example: Response

{
    "data": {
        "_type": "Catalog",
        "_id": "1",
        "user": {
            "_type": "User",
            "_id": "1"
        },
        "name": "catalog-1",
        "description": "My first catalog",
        "schema": "product",
        "created_at": "2017-01-01T00:00:00.001Z",
        "updated_at": "2017-01-01T00:00:00.001Z"
    }
}

Update an existing catalog.

HTTP Request

PUT https://catalog.markable.ai/catalogs/:catalogId

HTTP Headers

Header Description
Authorization HTTP Bearer Token for authorizing the request.

Format is Bearer :access_token, where access_token is given by Authentication. required

Route

Parameter Description
catalogId The ID of the catalog. required

Body

Attribute Type Description
data Catalog A valid catalog object.

delete-catalog_icon Delete catalog

Example: Request

DELETE https://catalog.markable.ai/catalogs/catalog-1 HTTP/1.1
Authorization: Bearer 123abc
curl -X DELETE https://catalog.markable.ai/catalogs/catalog-1 \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer 123abc'

Example: Response

{
    "data": {}
}

Delete an existing catalog.

HTTP Request

DELETE https://catalog.markable.ai/catalogs/:catalogId

HTTP Headers

Header Description
Authorization HTTP Bearer Token for authorizing the request.

Format is Bearer :access_token, where access_token is given by Authentication. required

Route

Parameter Description
catalogId The ID of the catalog. required

get-catalog-objects_icon Get catalog

Example: Request

GET https://catalog.markable.ai/catalogs/catalog-1 HTTP/1.1
Authorization: Bearer 123abc
curl -X GET https://catalog.markable.ai/catalogs/catalog-1 \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer 123abc'

Example: Response

{
    "data": {
        "_type": "Catalog",
        "_id": "1",
        "size": 0,
        "user": {
            "_type": "User",
            "_id": "1"
        },
        "name": "catalog-1",
        "description": "My first catalog",
        "schema": "product",
        "created_at": "2017-01-01T00:00:00.001Z",
        "updated_at": "2017-01-01T00:00:00.001Z"
    }
}

Get an existing catalog.

HTTP Request

GET https://catalog.markable.ai/catalogs/:catalogId

HTTP Headers

Header Description
Authorization HTTP Bearer Token for authorizing the request.

Format is Bearer :access_token, where access_token is given by Authentication. required

Route

Parameter Description
catalogId The ID of the catalog. required

list-catalog-objects_icon List catalogs

Example: Request

GET https://catalog.markable.ai/catalogs HTTP/1.1
Authorization: Bearer 123abc
curl -X GET https://catalog.markable.ai/catalogs \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer 123abc'

Example: Response

{
    "data": [
        {
            "_type": "Catalog",
            "_id": "1",
            "size": 0,
            "user": {
                "_type": "User",
                "_id": "1"
            },
            "name": "catalog-1",
            "description": "My first catalog",
            "schema": "product",
            "created_at": "2017-01-01T00:00:00.001Z",
            "updated_at": "2017-01-01T00:00:00.001Z"
        },
        {
            "_type": "Catalog",
            "_id": "2",
            "size": 0,
            "user": {
                "_type": "User",
                "_id": "1"
            },
            "name": "catalog-2",
            "description": "My second catalog",
            "schema": "product",
            "created_at": "2017-01-01T00:00:00.001Z",
            "updated_at": "2017-01-01T00:00:00.001Z"
        }
    ]
}

Get all existing catalogs.

HTTP Request

GET https://catalog.markable.ai/catalogs

HTTP Headers

Header Description
Authorization HTTP Bearer Token for authorizing the request.

Format is Bearer :access_token, where access_token is given by Authentication. required

Route

None

get-catalog-objects_icon Catalog Stats

Catalog statistics explaning

Example: Request

GET https://catalog.markable.ai/catalogs/catalog-1/stats HTTP/1.1
Authorization: Bearer 123abc
curl -X GET https://catalog.markable.ai/catalogs/catalog-1/stats \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer 123abc'

Example: Response

{
    "data": {
        "size": 4,
        "category": [
            {
                "_id": "shirts",
                "total": 1
            },
            {
                "_id": "skirts",
                "total": 1
            },
            {
                "_id": "dresses",
                "total": 2
            }
        ],
        "status": [
            {
                "_id": "pending",
                "total": 4
            }
        ],
        "gender": [
            {
                "_id": null,
                "total": 4
            }
        ]
    }
}

Stats for an existing catalog.

HTTP Request

GET https://catalog.markable.ai/catalogs/:catalogId/stats

HTTP Headers

Header Description
Authorization HTTP Bearer Token for authorizing the request.

Format is Bearer :access_token, where access_token is given by Authentication. required

Route

Parameter Description
catalogId The ID of the catalog. required

list-catalog-objects_icon List public catalogs

Example: Request

GET https://catalog.markable.ai/catalogs/public HTTP/1.1
Authorization: Bearer 123abc
curl -X GET https://catalog.markable.ai/catalogs/public \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer 123abc'

Example: Response

{
  "data": [
        {
            "_type": "Catalog",
            "_id": "1",
            "size": 0,
            "user": {
                "_type": "User",
                "_id": "1"
            },
            "name": "catalog-1-public",
            "description": "My first public catalog",
            "schema": "product",
            "created_at": "2017-01-01T00:00:00.001Z",
            "updated_at": "2017-01-01T00:00:00.001Z"
        },
        {
            "_type": "Catalog",
            "_id": "2",
            "size": 0,
            "user": {
                "_type": "User",
                "_id": "2"
            },
            "name": "catalog-2-public",
            "description": "My second public catalog",
            "schema": "product",
            "created_at": "2017-01-01T00:00:00.001Z",
            "updated_at": "2017-01-01T00:00:00.001Z"
        }
    ]
}

Get all existing catalogs.

HTTP Request

GET https://catalog.markable.ai/catalogs/public

HTTP Headers

Header Description
Authorization HTTP Bearer Token for authorizing the request.

Format is Bearer :access_token, where access_token is given by Authentication. required

Query Parameters

None

Catalog Items Catalog-items

catalog-items-objects_icon The Catalog Item Object

Example: Catalog Item Object

{
    "_type": "CatalogItem",
    "_id": "item-1",
    "schema": "product",
    "catalog": {
        "_type": "Catalog",
        "_id": "1",
        "name": "catalog-1"
    },
    "images": [
        {
            "_type": "CatalogItem",
            "_id": "1",
            "schema": "product",
            "uri": "https://markable.ai/data/products/dress/1.png",
            "width": 100,
            "height": 100
        },
        {
            "_type": "Image",
            "_id": "2",
            "uri": "https://markable.ai/data/products/dress/2.png",
            "width": 100,
            "height": 100
        }
    ],
    "category": {
        "_type": "Category",
        "_id": "1",
        "name": "dress"
    },
    "data": {
        "url": "https://example.com/product/page.html",
        "id": "external-id-1",
        "foo": "bar",
        "name" : "A great awesome product",
        "brand" : "Brand",
        "color" : "green",
        "gender" : "women",
        "vendor" : "vendor",
        "stock" : true,
        "price" : 30,
        "currency" : "USD"
    },
    "created_at": "2017-01-01T00:00:00Z",
    "updated_at": "2017-01-01T00:00:00Z"
}

Schema: Catalog Item Object (Product)

{
    "$schema": "http://json-schema.org/draft-04/schema",
    "type": "object",
    "description": "CatalogItem",
    "required": [
        "catalog",
        "images",
        "data"
    ],
    "properties": {
        "_type": {
            "type": "string",
            "readOnly": true,
            "default": "CatalogItem"
        },
        "_id": {
            "type": "string",
            "readOnly": true
        },
        "schema": {
            "type": "string",
            "readOnly": true,
            "default": "product"
        },
        "catalog": {
            "type": "object",
            "description": "Catalog",
            "properties": {
                "_type": {
                    "type": "string",
                    "readOnly": true,
                    "default": "Catalog"
                },
                "_id": {
                    "type": "string"
                },
                "name": {
                    "type": "string"
                }
            }
        },
        "images": {
            "type": "array",
            "items": {
                "type": "object",
                "description": "Image",
                "required": [
                    "uri"
                ],
                "properties": {
                    "_type": {
                        "type": "string",
                        "readOnly": true,
                        "default": "Image"
                    },
                    "_id": {
                        "type": "string",
                        "readOnly": true
                    },
                    "uri": {
                        "anyOf": [
                            {
                                "type": "string",
                                "format": "uri"
                            },
                            {
                                "type": "string",
                                "format": "byte"
                            }
                        ]
                    },
                    "status": {
                        "enum": ["pending", "error", "success"]
                    },
                    "error": {
                        "type": ["object", "null"]
                    },
                    "width": {
                        "type": "integer",
                        "minimum": 0,
                        "readOnly": true
                    },
                    "height": {
                        "type": "integer",
                        "minimum": 0,
                        "readOnly": true
                    }
                },
                "additionalProperties": false
            },
            "minItems": 1,
            "uniqueItems": true
        },
        "category": {
            "type": "object",
            "description": "Category",
            "properties": {
                "_type": {
                    "type": "string",
                    "readOnly": true,
                    "default": "Category"
                },
                "_id": {
                    "type": "string"
                },
                "name": {
                    "type": "string"
                }
            }
        },
        "data": {
            "type": "object",
            "properties": {
                "url": {
                    "type": "string",
                },
                "gender": {
                    "enum": ["men", "women", "unisex"],
                    "default": "women"
                },
                "name": {
                    "type": "string",
                },
                "id": {
                    "type": "string"
                },
                "sku": {
                    "type": "string"
                },
                "vendor": {
                    "type": "string"
                },
                "brand": {
                    "type": "string"
                },
                "price": {
                    "type": "number"
                },
                "currency": {
                    "type": "string"
                },
                "color": {
                    "type": "string"
                },
                "description": {
                    "type": "string"
                }
            },
            "additionalProperties": true,
            "required": ["url"]
        },
        "created_at": {
            "type": "string",
            "format": "date-time",
            "readOnly": true
        },
        "updated_at": {
            "type": "string",
            "format": "date-time",
            "readOnly": true
        }
    },
    "additionalProperties": false
}

A Catalog Item (object) defines an visual item (e.g. product), that can be indexed and visually searched within images and videos using visual similarity - based on the associated image(s). Catalog items can be defined as different types of objects, but currently only Product. Catalog items are organized by catalogs.

Note

Attribute Type Description
_type String Type. read-only
_id String An unique identifier. read-only
catalog Catalog Reference to catalog containing this item.
images Array<Image> List of images - visual representation of this item (object).
category Category Category - taxonomic classification of item (object).
data Object Custom data - semantic representation of this item (object).
created_at Date Creation date/time. read-only
updated_at Date Updated date/time. read-only

Auto Categorize a CatalogItem

Note that our feature where we try to predict the Markable category based on textual information is currently in alpha.

Example: Request

POST https://catalog.markable.ai/category HTTP/1.1
Authorization: Bearer 123abc
{
    "data": {
        "images": [
            {
                "uri": "https://example.com/products/1/a.png"
            },
            {
                "uri": "https://example.com/products/1/b.png"
            }
        ],
        "data": {
            "url": "https://example.com/product/shoes.html",
            "name": "A shoe product",
            "description": "This is a fantastic shoe product",
            "categoryInfo": "Some relevant information about category"
        }
    }
}
curl -X POST https://catalog.markable.ai/category \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer 123abc' \
-d '
{
    "data": {
        "images": [
            {
                "uri": "https://example.com/products/1/a.png"
            },
            {
                "uri": "https://example.com/products/1/b.png"
            }
        ],
        "data": {
            "url": "https://example.com/product/shoes.html",
            "name": "A shoe product",
            "description": "This is a fantastic shoe product",
            "categoryInfo": "Some relevant information about category"
        }
    }
}
'

Example: Response

{
    "data": {
        "images": [
            {
                "uri": "https://example.com/products/1/a.png"
            },
            {
                "uri": "https://example.com/products/1/b.png"
            }
        ],
        "category": {
            "name": "shoes"
        },
        "data": {
            "url": "https://example.com/product/shoes.html",
            "name": "A shoe product",
            "description": "This is a fantastic shoe product",
            "categoryInfo": "Some relevant information about category"
        }
    }
}

Given an item without a category, we try and figure out what the the Supported Markable category is based on the textual information you provide. Its best to run this call with as much textual information as possible in the freeform data key. The response can be directly used to create a catalog item

HTTP Request

POST https://catalog.markable.ai/category

HTTP Headers

Header Description
Authorization HTTP Bearer Token for authorizing the request.

Format is Bearer :access_token, where access_token is given by Authentication. required

create-catalog-item_icon Create catalog item

Example: Request (with gender being optional)

POST https://catalog.markable.ai/catalogs/catalog-1/items HTTP/1.1
Authorization: Bearer 123abc
{
    "data": {
        "images": [
            {
                "uri": "https://example.com/products/1/a.png"
            },
            {
                "uri": "https://example.com/products/1/b.png"
            }
        ],
        "category": {
            "name": "glasses"
        },
        "data": {
            "url": "https://example.com/product/page.html",
            "id": "external-id-1",
            "name" : "A great awesome product",
            "brand" : "Brand",
            "color" : "green",
            "gender" : "women",
            "vendor" : "vendor",
            "stock" : true,
            "price" : 30,
            "currency" : "USD"
        }
    }
}
curl -X POST https://catalog.markable.ai/catalogs/catalog-1/items \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer 123abc' \
-d '
{
    "data": {
        "images": [
            {
                "uri": "https://example.com/products/1/a.png"
            },
            {
                "uri": "https://example.com/products/1/b.png"
            }
        ],
        "category": {
            "name": "glasses"
        }
        "data": {
            "url": "https://example.com/product/page.html",
            "id": "external-id-1",
            "name" : "A great awesome product",
            "brand" : "Brand",
            "color" : "green",
            "gender" : "women",
            "vendor" : "vendor",
            "stock" : true,
            "price" : 30,
            "currency" : "USD"
        }
    }
}
'

Example: Response

{
    "data": {
        "_type": "CatalogItem",
        "_id": "item-1",
        "schema": "product",
        "catalog": {
            "_type": "Catalog",
            "_id": "1",
            "name": "catalog-1"
        },
        "images": [
            {
                "_type": "Image",
                "_id": "1",
                "uri": "https://example.com/products/1/a.png",
                "width": 200,
                "height": 300,
                "status": "success",
                "error": null,
                "attributes": {
                    "shoes": [
                        {
                            "score": 0.7574759125709534,
                            "name": "color",
                            "value": "white"
                        },
                        {
                            "score": 0.3870239555835724,
                            "name": "pattern",
                            "value": "polka dot"
                        }
                    ]
                },
                "bounding_boxes": {
                    "shoes": [
                        {
                            "y": 49.69390106201172,
                            "x": 233.58139038085938,
                            "height": 577.4708938598633,
                            "width": 419.4363098144531
                        }
                    ]
                }
            },
            {
                "_type": "Image",
                "_id": "2",
                "uri": "https://example.com/products/1/b.png",
                "width": 200,
                "height": 300,
                "status": "success",
                "error": null,
                "attributes": {
                    "skirts": [
                        {
                            "score": 0.7574759125709534,
                            "name": "color",
                            "value": "white"
                        },
                        {
                            "score": 0.3870239555835724,
                            "name": "pattern",
                            "value": "polka dot"
                        }
                    ]
                },
                "bounding_boxes": {
                    "skirts": [
                        {
                            "y": 49.69390106201172,
                            "x": 233.58139038085938,
                            "height": 577.4708938598633,
                            "width": 419.4363098144531
                        }
                    ]
                }
            }
        ],
        "category": {
          "_type": "Category",
          "_id": "1",
          "name": "glasses"
      },
        "data": {
            "url": "https://example.com/product/page.html",
            "id": "external-id-1",
            "name" : "A great awesome product",
            "brand" : "Brand",
            "color" : "green",
            "gender" : "women",
            "vendor" : "vendor",
            "stock" : true,
            "price" : 30,
            "currency" : "USD"
        },
        "created_at": "2017-01-01T00:00:00.001Z",
        "updated_at": "2017-01-01T00:00:00.001Z"
    }
}

Create a new catalog item.

Create a new catalogItem in your catalog that will eventually get indexed.

HTTP Request

POST https://catalog.markable.ai/catalogs/:catalogId/items

HTTP Headers

Header Description
Authorization HTTP Bearer Token for authorizing the request.

Format is Bearer :access_token, where access_token is given by Authentication. required

Route

Parameter Description
catalogId The ID of the catalog. required

Body

Attribute Type Description
data CatalogItem A valid catalog item object.

delete-catalog-item_icon Delete catalog item

Example: Request

DELETE https://catalog.markable.ai/catalogs/catalog-1/items/item-1 HTTP/1.1
Authorization: Bearer 123abc
curl -X DELETE https://catalog.markable.ai/catalogs/catalog-1/items/item-1 \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer 123abc'

Example: Response

{
    "data": {
        "_type": "CatalogItem",
        "_id": "item-1",
        "schema": "product",
        "catalog": {
            "_type": "Catalog",
            "_id": "1",
            "name": "catalog-1"
        },
        "images": [
            {
                "_type": "Image",
                "_id": "1",
                "uri": "https://example.com/products/1/a.png",
                "width": 200,
                "height": 300
            },
            {
                "_type": "Image",
                "_id": "2",
                "uri": "https://example.com/products/1/b.png",
                "width": 200,
                "height": 300
            }
        ],
        "category": {
          "_type": "Category",
          "_id": "1",
          "name": "glasses"
      },
        "data": {
            "url": "https://example.com/product/page.html",
            "id": "external-id-1",
            "foo": "bar"
        },
        "created_at": "2017-01-01T00:00:00.001Z",
        "updated_at": "2017-01-01T00:00:00.001Z"
    }
}

Delete an existing catalog item.

HTTP Request

DELETE https://catalog.markable.ai/catalogs/:catalogId/items/:itemId

HTTP Headers

Header Description
Authorization HTTP Bearer Token for authorizing the request.

Format is Bearer :access_token, where access_token is given by Authentication. required

Route

Parameter Description
catalogId The ID of the catalog. required
itemId The ID of the catalog item. required

get-catalog-item_icon Get catalog item

Example: Request

GET https://catalog.markable.ai/catalogs/catalog-1/items/item-1 HTTP/1.1
Authorization: Bearer 123abc
curl -X GET https://catalog.markable.ai/catalogs/catalog-1/items/item-1 \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer 123abc'

Example: Response

{
    "data": {
        "_type": "CatalogItem",
        "_id": "item-1",
        "schema": "product",
        "catalog": {
            "_type": "Catalog",
            "_id": "1",
            "name": "catalog-1"
        },
        "images": [
            {
                "_type": "Image",
                "_id": "1",
                "uri": "https://example.com/products/1/a.png",
                "width": 200,
                "height": 300
            },
            {
                "_type": "Image",
                "_id": "2",
                "uri": "https://example.com/products/1/b.png",
                "width": 200,
                "height": 300
            }
        ],
        "category": {
          "_type": "Category",
          "_id": "1",
          "name": "glasses"
      },
        "data": {
            "url": "https://example.com/product/page.html",
            "id": "external-id-1",
            "foo": "bar"
        },
        "created_at": "2017-01-01T00:00:00.001Z",
        "updated_at": "2017-01-01T00:00:00.001Z"
    }
}

Get an existing catalog item.

HTTP Request

GET https://catalog.markable.ai/catalogs/:catalogId/items/:itemId

HTTP Headers

Header Description
Authorization HTTP Bearer Token for authorizing the request.

Format is Bearer :access_token, where access_token is given by Authentication. required

Route

Parameter Description
catalogId The ID of the catalog. required
itemId The ID of the catalog item. required

Query parameters

Parameter Type Description
attributes Boolean Return attributes for every catalogItem

list-catalog-item_icon List catalog items

Example: Request

GET https://catalog.markable.ai/catalogs/catalog-1/items HTTP/1.1
Authorization: Bearer 123abc
curl -X GET https://catalog.markable.ai/catalogs/catalog-1/items \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer 123abc'

Example: Request with filters

GET https://catalog.markable.ai/catalogs/catalog-1/items?success=true&limit=50&skip=0&category=dresses HTTP/1.1
Authorization: Bearer 123abc
curl -X GET https://catalog.markable.ai/catalogs/catalog-1/items?success=true&limit=50&skip=0&category=dresses \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer 123abc'

Example: Response

{
    "data": [
        {
            "_type": "CatalogItem",
            "_id": "item-1",
            "schema": "product",
            "catalog": {
                "_type": "Catalog",
                "_id": "1",
                "name": "catalog-1"
            },
            "images": [
                {
                    "_type": "Image",
                    "_id": "1",
                    "uri": "https://example.com/products/1/a.png",
                    "width": 200,
                    "height": 300
                },
                {
                    "_type": "Image",
                    "_id": "2",
                    "uri": "https://example.com/products/1/b.png",
                    "width": 200,
                    "height": 300
                }
            ],
            "category": {
              "_type": "Category",
              "_id": "1",
              "name": "glasses"
          },
            "data": {
                "url": "https://company.xyz/external-product-id-1",
                "id": "external-id-1",
                "foo": "bar"
            },
            "created_at": "2017-01-01T00:00:00.001Z",
            "updated_at": "2017-01-01T00:00:00.001Z"
        },
        {
            "_type": "CatalogItem",
            "_id": "item-2",
            "schema": "product",
            "catalog": {
                "_type": "Catalog",
                "_id": "1",
                "name": "catalog-1"
            },
            "images": [
                {
                    "_type": "Image",
                    "_id": "1",
                    "uri": "https://example.com/products/1/a.png",
                    "width": 200,
                    "height": 300
                },
                {
                    "_type": "Image",
                    "_id": "2",
                    "uri": "https://example.com/products/1/b.png",
                    "width": 200,
                    "height": 300
                }
            ],
            "category": {
              "_type": "Category",
              "_id": "1",
              "name": "glasses"
          },
            "data": {
                "url": "https://company.xyz/external-product-id-2",
                "id": "external-id-2",
                "foo": "bar"
            },
            "created_at": "2017-01-01T00:00:00.001Z",
            "updated_at": "2017-01-01T00:00:00.001Z"
        }
    ]
}

Get all existing catalog items.

HTTP Request

GET https://catalog.markable.ai/catalogs/:catalogId/items

HTTP Headers

Header Description
Authorization HTTP Bearer Token for authorizing the request.

Format is Bearer :access_token, where access_token is given by Authentication. required

Query Parameters

Parameter Description
limit The limit of items to return (defaults to 10).
skip The skip of items to return.
success Set this value filter by success status
error Set this value filter by error status
pending Set this value filter by pending status
category The category of the items to filter by
attributes Boolean. Returns attributes for every catalogItem

Indexing

Indexing is how we make CatalogItems available for search and our way of representing images.

We have constraints on the image sizes we index.

  1. We support .jpg, .jpeg, .png, and .webp

  2. Minimum image size = 224 px

  3. Maximum image size = 3200 px

  4. Maximum image memory size = 2.5 * 1024 * 1024 mb

Indexing is different from Search for which the constraints are different.

Taxonomy

Markable’s taxonomy includes our supported categories and attributes.

Supported Categories

Example: Request

GET https://catalog.markable.ai/category HTTP/1.1
Authorization: Bearer 123abc
curl -X GET https://catalog.markable.ai/category \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer 123abc'

Example: Response

This is our current exhaustive list of supported categories.

{
    "data": [
        "backpacks",
        "baseballcaps",
        "beanieknitcaps",
        "berets",
        "blouses",
        "boots",
        "buttondowns",
        "cardigans",
        "clutches",
        "coats_jackets",
        "dresses",
        "glasses",
        "handbags",
        "henleys",
        "hoodies",
        "jeans",
        "jumpsuits",
        "leggings",
        "longsleeveshirts",
        "messengerbags",
        "overalls",
        "pants",
        "polos",
        "rompers",
        "sandals",
        "scarves_wraps",
        "shoes",
        "shorts",
        "skirts",
        "slippers",
        "suitcoats_blazers",
        "sunhats_cowboyhats",
        "sweaters",
        "tanks_camis",
        "tees",
        "ties",
        "tunics",
        "vests",
        "watches"
    ]
}

Markable’s supported categories.

HTTP Request

GET https://catalog.markable.ai/category

HTTP Headers

Header Description
Authorization HTTP Bearer Token for authorizing the request.

Format is Bearer :access_token, where access_token is given by Authentication. required

Supported Attributes

CatalogItems after indexing get assigend attributes, based on their category. Attributes can be of type color, pattern, sleeve length and more.

Example: Request

GET https://catalog.markable.ai/attributes HTTP/1.1
Authorization: Bearer 123abc
curl -X GET https://catalog.markable.ai/attributes \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer 123abc'

Example: Response

This is a snippet of our attributes.

{
    "data": {
        "belts": {
            "color": [
                "blue",
                "brown",
                "purple",
                "grey",
                "..."
            ],
            "pattern": [
                "cheetah/leopard print",
                "gingham",
                "checkered",
                "..."
            ]
        },
        "blouses_shirts": {
            "closing_style": [
                "multiple buttons/snaps",
                "no closures",
                "..."
            ],
            "collar_type": [
                "square neck",
                "mandarin collar",
                "puritan collar",
                "off-shoulder",
                "straight across/strapless",
                "..."
            ],
            "color": [
                "blue",
                "red",
                "..."
            ],
            "pattern": [
                "cheetah/leopard print",
                "floral",
                "tribal print",
                "..."
            ],
            "sleeve_length": [
                "sleeveless",
                "short/cap sleeve",
                "long (full sleeve)",
                "..."
            ]
        }
    }
}

Markable’s supported attributes per category.

HTTP Request

GET https://catalog.markable.ai/attributes

HTTP Headers

Header Description
Authorization HTTP Bearer Token for authorizing the request.

Format is Bearer :access_token, where access_token is given by Authentication. required

Image Search

We have two different kinds of search, Product and How to Wear it for images.

Product search, also often called Product Search or Product Search. Given an image, we find the most visually relevant images in your Catalog of schema product.

image-search_icon The Product Search Query Object

Example: Product Search Query Object

{
    "data": {
        "image_uri": "https://example.com/images/1.png",
        "catalogs": [
            {
                "name": "catalog-name-1"
            },
            {
                "name": "catalog-name-2"
            }
        ]
    }
}

Example: Product Search Query Object with Options

{
    "data": {
        "image_uri": "https://example.com/images/1.png",
        "catalogs": [
            {
                "name": "catalog-name-1"
            },
            {
                "name": "catalog-name-2"
            }
        ],
        "options": {
            "limit": 30,
            "relevance": 50
        }
    }
}

Example: Product Search Query Object with Attributes

{
    "data": {
        "image_uri": "https://example.com/images/1.png",
        "catalogs": [
            {
                "name": "catalog-name-1"
            },
            {
                "name": "catalog-name-2"
            }
        ],
        "options": {
            "attributes": true
        }
    }
}

Example: Product Search Query Object with Auto detect gender in the input image

{
    "data": {
        "image_uri": "https://example.com/images/1.png",
        "catalogs": [
            {
                "name": "catalog-name-1"
            },
            {
                "name": "catalog-name-2"
            }
        ],
        "options": {
            "auto_detect_gender": true
        }
    }
}

A Product Search Query (object) defines a visual search query for an image.

Attribute Type Description
image_uri String A valid image URI. required
gender Array ['men', 'women'] or a sub array of both. By default we return all gender results.
catalogs Array<Catalog> List of product catalogs (public or private) - which will be included the visual search scope.
options Object A list of options that we support. Currently we support the options below

These options give you the flexibility to control how our visual search is performed.

Attribute Type Description
limit Number Number of results to return. Default 30
relevance Number How relevant you want the results to be. Default 50. This takes precedence over limit
auto_detect_gender Boolean Auto detect gender in the input image to scope search to specific genders, takes precedence over gender above. Currently in alpha. Note that this does introduce a slow down of a few 100ms in search.
attributes Boolean Return attributes for every catalogItem, for both the searched input image and the images in the results. Note that this does introduce a slow down of a few 100ms in search. Secondly, there is no guarantee that the attributes will be common between the input image and the result images; however, its highly likely that they would be.

Example: Simple Image Search without Catalogs

POST https://catalog.markable.ai/image/search HTTP/1.1
Authorization: Bearer 123abc
{
    "data": {
        "image_uri": "http://i.com/1.png"
    }
}
curl -X POST https://catalog.markable.ai/image/search \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer 123abc' \
-d '
{
    "data": {
        "image_uri": "http://i.com/1.png"
    }
}
'

Example: Image Search with Catalogs Names (Preferred over IDS)

POST https://catalog.markable.ai/image/search HTTP/1.1
Authorization: Bearer 123abc
{
    "data": {
        "image_uri": "http://i.com/1.png",
        "catalogs": [
            {
                "name": "catalog-name-1"
            },
            {
                "name": "catalog-name-2"
            }
        ]
    }
}
curl -X POST https://catalog.markable.ai/image/search \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer 123abc' \
-d '
{
    "data": {
        "image_uri": "http://i.com/1.png",
        "catalogs": [
            {
                "name": "catalog-name-1"
            },
            {
                "name": "catalog-name-2"
            }
        ]
    }
}
'

Example: Image Search with Catalogs IDS

POST https://catalog.markable.ai/image/search HTTP/1.1
Authorization: Bearer 123abc
{
    "data": {
        "image_uri": "http://i.com/1.png",
        "catalogs": [
            {
                "_id": "catalog-id-1"
            },
            {
                "_id": "catalog-id-2"
            }
        ]
    }
}
curl -X POST https://catalog.markable.ai/image/search \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer 123abc' \
-d '
{
    "data": {
        "image_uri": "http://i.com/1.png",
        "catalogs": [
            {
                "_id": "catalog-id-1"
            },
            {
                "_id": "catalog-id-2"
            }
        ]
    }
}
'

Example: Simple Image Search with Catalogs and Gender

POST https://catalog.markable.ai/image/search HTTP/1.1
Authorization: Bearer 123abc
{
  "data": {
        "image_uri": "http://i.com/1.png",
        "gender": ["men"],
        "catalogs": [
            {
                "name": "catalog-name-1"
            },
            {
                "name": "catalog-name-2"
            }
        ]
    }
}
curl -X POST https://catalog.markable.ai/image/search \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer 123abc' \
-d '
{
    "data": {
        "image_uri": "http://i.com/1.png",
        "gender": ["men", "women"],
        "catalogs": [
            {
                "name": "catalog-name-1"
            },
            {
                "name": "catalog-name-2"
            }
        ]
    }
}
'

Example: Multipart Image Search with Catalogs (Alpha availability)

POST https://catalog.markable.ai/image/search HTTP/1.1
Authorization: Bearer 123abc
Content-Type: multipart/form-data; charset=utf-8;
... (See shell for a full example)
curl -X POST https://catalog.markable.ai/image/search \
-H 'Content-Type: multipart/form-data;' \
-H 'Authorization: Bearer 123abc' \
-F 'image=@/local/folder/1.png' \
-F 'data={ "catalogs": [{ "name": "catalog-name-1" }] }'

Example: Response

{
    "meta": {
        "image": {
            "width": 100,
            "height": 100,
            "uri": "http://i.com/1.png"
        },
        "stats": {
            "detection": 313,
            "extraction": 141,
            "search": 8,
            "image_download": 57
        },
    },
    "data": [
        {
            "type": "SearchResult",
            "category": {
                "_type": "Category",
                "_id": "shorts",
                "name": "shorts"
            },
            "bounding_box": {
                "_type": "BoundingBox",
                "y": 266,
                "x": 54,
                "height": 145,
                "width": 204
            },
            "score": 0.963,
            "matches": [
                {
                    "_type": "CatalogItem",
                    "_id": "5938629ec77b4a05f48f782a",
                    "score": 0.701,
                    "images": [
                        {
                            "uri": "http://i.com/result1.png",
                            "_type": "Image"
                        },
                        {
                            "uri": "http://i.com/result2.png",
                            "_type": "Image"
                        }
                    ],
                    "catalog": {
                        "_type": "Catalog",
                        "name": "catalog-name-1",
                        "_id": "catalog-id-1"
                    },
                    "data": {
                        "id": "any custom data",
                        "name": "custom product name"
                    },
                    "created_at": "2017-08-10T22:54:48.547Z",
                    "updated_at": "2017-08-10T22:54:48.547Z"
                },
                {
                    "_type": "CatalogItem",
                    "_id": "59386368c77b4a05fa8f7b06",
                    "score": 0.7,
                    "images": [
                        {
                            "uri": "http://i.com/result2.png",
                            "_type": "Image"
                        }
                    ],
                    "catalog": {
                        "_type": "Catalog",
                        "name": "catalog-name-1",
                        "_id": "catalog-id-1"
                    },
                    "data": {
                        "id": "any custom data",
                        "name": "custom product name"
                    },
                    "created_at": "2017-08-10T22:54:48.547Z",
                    "updated_at": "2017-08-10T22:54:48.547Z"
                }
            ]
        },
        {
            "type": "SearchResult",
            "category": {
                "_type": "Category",
                "_id": "sandals",
                "name": "sandals"
            },
            "bounding_box": {
                "_type": "BoundingBox",
                "y": 266,
                "x": 54,
                "height": 145,
                "width": 204
            },
            "score": 0.831,
            "matches": [
                {
                    "_type": "CatalogItem",
                    "_id": "5938629ec77b4a05f48f7821",
                    "score": 0.62,
                    "images": [
                        {
                            "uri": "http://i.com/result5.png",
                            "_type": "Image"
                        }
                    ],
                    "catalog": {
                        "_type": "Catalog",
                        "name": "catalog-name-2",
                        "_id": "catalog-id-2"
                    },
                    "data": {
                        "id": "any custom data",
                        "name": "custom product name"
                    },
                    "created_at": "2017-08-10T22:54:48.547Z",
                    "updated_at": "2017-08-10T22:54:48.547Z"
                },
                {
                    "_type": "CatalogItem",
                    "_id": "59386368c77b4a05fa8f7b02",
                    "score": 0.4,
                    "images": [
                        {
                            "uri": "http://i.com/result4.png",
                            "_type": "Image"
                        },
                        {
                            "uri": "http://i.com/result5.png",
                            "_type": "Image"
                        }
                    ],
                    "catalog": {
                        "_type": "Catalog",
                        "name": "catalog-name-2",
                        "_id": "catalog-id-2"
                    },
                    "data": {
                        "id": "any custom data",
                        "name": "custom product name"
                    },
                    "created_at": "2017-08-10T22:54:48.547Z",
                    "updated_at": "2017-08-10T22:54:48.547Z"
                }
            ]
        }
    ]
}

Search an image - detect and retreive products based on visual features/similarity.

HTTP Request

POST https://catalog.markable.ai/image/search

HTTP Headers

Header Description
Authorization HTTP Bearer Token for authorizing the request.

Format is Bearer :access_token, where access_token is given by Authentication. required

Query Parameters

None

Body

Attribute Type Description
data ImageSearchQuery A valid image search object.

Our How to Wear it search gives style results given a specific image. Its best if the searched image is a product image.

As an example, if you search with a shoe (a product image), results from your style catalog will be shown.

image-search_icon The How to Wear it Query Object

Example: How to Wear it Query Object

{
    "data": {
        "image_uri": "https://example.com/images/1.png",
        "catalogs": [
            {
                "name": "catalog-name-1"
            },
            {
                "name": "catalog-name-2"
            }
        ]
    }
}

A How to Wear it Query (object) defines a visual search query for an image.

Attribute Type Description
image_uri String A valid image URI. required
gender Array ['men', 'women'] or a sub array of both. By default we return all gender results.
catalogs Array<Catalog> List of style catalogs (public or private) - which will be included the visual search scope.
options Object A list of options that we support. Currently we support the options below

These options give you the flexibility to control how our visual search is performed.

Attribute Type Description
limit Number Number of results to return. Default 30
relevance Number How relevant you want the results to be. Default 50. This takes precedence over limit
auto_detect_gender Boolean Auto detect gender in the input image to scope search to specific genders, takes precedence over gender above. Currently in alpha. Note that this does introduce a slow down of a few 100ms in search.
attributes Boolean Return attributes for every catalogItem, for both the searched input image and the images in the results. Note that this does introduce a slow down of a few 100ms in search. Secondly, there is no guarantee that the attributes will be common between the input image and the result images; however, its highly likely that they would be.

Example: Simple How to Wear it without Catalogs

POST https://catalog.markable.ai/image/search/style HTTP/1.1
Authorization: Bearer 123abc
{
    "data": {
        "image_uri": "http://i.com/1.png"
    }
}
curl -X POST https://catalog.markable.ai/image/search/style \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer 123abc' \
-d '
{
    "data": {
        "image_uri": "http://i.com/1.png"
    }
}
'

Example: How to Wear it with style Catalogs Names (Preferred over IDS)

POST https://catalog.markable.ai/image/search/style HTTP/1.1
Authorization: Bearer 123abc
{
    "data": {
        "image_uri": "http://i.com/1.png",
        "catalogs": [
            {
                "name": "catalog-name-1"
            },
            {
                "name": "catalog-name-2"
            }
        ]
    }
}
curl -X POST https://catalog.markable.ai/image/search/style \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer 123abc' \
-d '
{
    "data": {
        "image_uri": "http://i.com/1.png",
        "catalogs": [
            {
                "name": "catalog-name-1"
            },
            {
                "name": "catalog-name-2"
            }
        ]
    }
}
'

Example: How to Wear it with style Catalogs IDS

POST https://catalog.markable.ai/image/search/style HTTP/1.1
Authorization: Bearer 123abc
{
    "data": {
        "image_uri": "http://i.com/1.png",
        "catalogs": [
            {
                "_id": "catalog-id-1"
            },
            {
                "_id": "catalog-id-2"
            }
        ]
    }
}
curl -X POST https://catalog.markable.ai/image/search/style \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer 123abc' \
-d '
{
    "data": {
        "image_uri": "http://i.com/1.png",
        "catalogs": [
            {
                "_id": "catalog-id-1"
            },
            {
                "_id": "catalog-id-2"
            }
        ]
    }
}
'

Example: Simple How to Wear it with style Catalogs and Gender

POST https://catalog.markable.ai/image/search/style HTTP/1.1
Authorization: Bearer 123abc
{
  "data": {
        "image_uri": "http://i.com/1.png",
        "gender": ["men"],
        "catalogs": [
            {
                "name": "catalog-name-1"
            },
            {
                "name": "catalog-name-2"
            }
        ]
    }
}
curl -X POST https://catalog.markable.ai/image/search/style \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer 123abc' \
-d '
{
    "data": {
        "image_uri": "http://i.com/1.png",
        "gender": ["men", "women"],
        "catalogs": [
            {
                "name": "catalog-name-1"
            },
            {
                "name": "catalog-name-2"
            }
        ]
    }
}
'

Example: Multipart How to Wear it with style Catalogs (Alpha availability)

POST https://catalog.markable.ai/image/search/style HTTP/1.1
Authorization: Bearer 123abc
Content-Type: multipart/form-data; charset=utf-8;
... (See shell for a full example)
curl -X POST https://catalog.markable.ai/image/search/style \
-H 'Content-Type: multipart/form-data;' \
-H 'Authorization: Bearer 123abc' \
-F 'image=@/local/folder/1.png' \
-F 'data={ "catalogs": [{ "name": "catalog-name-1" }] }'

Example: Response

{
    "meta": {
        "image": {
            "width": 100,
            "height": 100,
            "uri": "http://i.com/1.png"
        },
        "stats": {
            "detection": 313,
            "extraction": 141,
            "search": 8,
            "image_download": 57
        },
    },
    "data": [
        {
            "type": "StyleResult",
            "category": {
                "_type": "Category",
                "_id": "shorts",
                "name": "shorts"
            },
            "bounding_box": {
                "_type": "BoundingBox",
                "y": 266,
                "x": 54,
                "height": 145,
                "width": 204
            },
            "score": 0.963,
            "matches": [
                {
                    "_type": "CatalogItem",
                    "_id": "5938629ec77b4a05f48f782a",
                    "score": 0.701,
                    "images": [
                        {
                            "uri": "http://i.com/style/result1.png",
                            "_type": "Image"
                        },
                        {
                            "uri": "http://i.com/style/result2.png",
                            "_type": "Image"
                        }
                    ],
                    "catalog": {
                        "_type": "Catalog",
                        "name": "catalog-name-1",
                        "_id": "catalog-id-1"
                    },
                    "data": {
                        "id": "any custom data",
                        "gender": "women",
                        "detail": "custom style image details"
                    },
                    "created_at": "2017-08-10T22:54:48.547Z",
                    "updated_at": "2017-08-10T22:54:48.547Z"
                },
                {
                    "_type": "CatalogItem",
                    "_id": "59386368c77b4a05fa8f7b06",
                    "score": 0.7,
                    "images": [
                        {
                            "uri": "http://i.com/style/result2.png",
                            "_type": "Image"
                        }
                    ],
                    "catalog": {
                        "_type": "Catalog",
                        "name": "catalog-name-1",
                        "_id": "catalog-id-1"
                    },
                    "data": {
                        "id": "any custom data",
                        "gender": "women",
                        "detail": "custom style image details"
                    },
                    "created_at": "2017-08-10T22:54:48.547Z",
                    "updated_at": "2017-08-10T22:54:48.547Z"
                }
            ]
        },
        {
            "type": "StyleResult",
            "category": {
                "_type": "Category",
                "_id": "sandals",
                "name": "sandals"
            },
            "bounding_box": {
                "_type": "BoundingBox",
                "y": 266,
                "x": 54,
                "height": 145,
                "width": 204
            },
            "score": 0.831,
            "matches": [
                {
                    "_type": "CatalogItem",
                    "_id": "5938629ec77b4a05f48f7821",
                    "score": 0.62,
                    "images": [
                        {
                            "uri": "http://i.com/style/result5.png",
                            "_type": "Image"
                        }
                    ],
                    "catalog": {
                        "_type": "Catalog",
                        "name": "catalog-name-2",
                        "_id": "catalog-id-2"
                    },
                    "data": {
                        "id": "any custom data",
                        "gender": "women",
                        "detail": "custom style image details"
                    },
                    "created_at": "2017-08-10T22:54:48.547Z",
                    "updated_at": "2017-08-10T22:54:48.547Z"
                },
                {
                    "_type": "CatalogItem",
                    "_id": "59386368c77b4a05fa8f7b02",
                    "score": 0.4,
                    "images": [
                        {
                            "uri": "http://i.com/style/result4.png",
                            "_type": "Image"
                        },
                        {
                            "uri": "http://i.com/style/result5.png",
                            "_type": "Image"
                        }
                    ],
                    "catalog": {
                        "_type": "Catalog",
                        "name": "catalog-name-2",
                        "_id": "catalog-id-2"
                    },
                    "data": {
                        "id": "any custom data",
                        "gender": "women",
                        "detail": "custom style image details"
                    },
                    "created_at": "2017-08-10T22:54:48.547Z",
                    "updated_at": "2017-08-10T22:54:48.547Z"
                }
            ]
        }
    ]
}

Given a product image, find how it fits with different fashion styles. In specific, HTWI search returns results from a catalog of schema style.

HTTP Request

POST https://catalog.markable.ai/image/search/style

HTTP Headers

Header Description
Authorization HTTP Bearer Token for authorizing the request.

Format is Bearer :access_token, where access_token is given by Authentication. required

Query Parameters

None

Body

Attribute Type Description
data ImageSearchQuery A valid Image Search object.

Search Constraints

We have constraints on the input image we search on.

  1. We support .jpg, .jpeg, .png, and .webp

  2. Minimum image size = 100 px

  3. Maximum image size = 3200 px

  4. Maximum image memory size = 2.5 * 1024 * 1024 mb