Introduction
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 signup to get started. We’ll get back to you with your user credentials.
This API and documentation is subject to modifications.
Getting Started
To be able to use/access this API you will need to be a verified developer, please signup to get started. We’ll get back to you with your user credentials.
Then, login with your user credentials.
Once you have logged in, you will get your
user_access_token. With this token, get your default Client we have created for you.Then, authenticate your Client to get your
client_access_token.Make your first visual search. You will be using your
client_access_tokenfrom above.
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,
- The current limit is 25 requests/minute.
Depending on your use case, 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 or incorrectly formatted, 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 format or JSON is invalid. |
401 |
Unauthorized - The API key is wrong. |
403 |
Forbidden - The specified resource is hidden for admins only. |
404 |
Not Found - The specified specified could not be found. |
405 |
Method Not Allowed - The request method is invalid for specified resource. |
408 |
Timeout - The request has timed out. |
409 |
Conflict Error - Duplicate resource prohibited. |
413 |
Entity Too Large - The request exceeds size limit. |
422 |
Validation Error - The request fails schema specifications. |
429 |
Too Many Requests - You have reached your request per minute limit. |
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 Response
{
"errors": [
{
"title": "Unauthorized",
"id": "3f649f325620e5ddfa66f98c3945a7f7",
"status": 401,
"code": 401,
"detail": "Authentication Error",
"meta": {
"timestamp": 1551820965551,
"datetime": "2019-03-05T21:22:45.551Z"
}
}
]
}
A failed request will return a list of error objects according to the JSON API Specification.
An error object MAY have the following properties:
| Attribute | Description |
|---|---|
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. |
id |
A unique identifier for this particular occurrence of the problem. |
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. |
detail |
A human-readable explanation specific to this occurrence of the problem. Like title, this field’s value can be localized. |
links |
A links object containing the following members. |
source |
An object containing references to the source of the error. |
meta |
An object containing non-standard information about the error. |
Objects
The object defintions to be aware of when working with Markable Lens API.
Catalog
Example: Catalog Object
{
"_type": "Catalog",
"_id": "catalog_id_1"
"schema": "product",
"size": 0,
"updated_at": "2019-03-07T22:06:51.885Z",
"name": "catalog-1",
"description": "my_first_catalog",
"created_at": "2019-03-07T22:06:51.859Z",
"access": "public",
"user": {
"_type": "User",
"_id": "user_id_1"
},
}
Schema: Catalog Object
{
"title": "Catalog",
"description": "A markable API catalog",
"type": "object",
"required": [
"schema",
"name",
"user"
],
"additionalProperties": false,
"properties": {
"_type": {
"type": "string",
"default": "Catalog",
"readOnly": true
},
"meta": {
"title": "Meta Information",
"description": "Meta data for model",
"type": "object"
},
"_id": {
"title": "ID",
"description": "Primary key",
"type": "string"
},
"schema": {
"title": "Schema",
"description": "Determines type of catalog",
"type": "string",
"enum": [
"product",
"style"
]
},
"name": {
"title": "Catalog name",
"description": "Catalog name without spaces",
"type": "string",
"pattern": "^[a-zA-Z0-9_-]{4,}$"
},
"description": {
"title": "Catalog description",
"description": "Description of the catalog",
"type": "string"
},
"access": {
"title": "Catalog Access",
"description": "Accessibility option of catalog",
"type": "string",
"enum": [
"public",
"private"
],
"default": "private"
},
"priority": {
"title": "Indexing priority",
"type": "integer",
"description": "Indexing priority of catalog",
"default": 0
},
"enabled": {
"title": "",
"type": "boolean",
"description": "",
"default": true
},
"user": {
"title": "User",
"description": "User account that created catalog",
"type": "object",
"required": [
"_id"
],
"properties": {
"_id": {
"title": "ID",
"description": "User ID",
"readOnly": true
}
}
},
"size": {
"title": "Size",
"description": "Catalog Size",
"type": "integer"
},
"status": {
"title": "Indexing Status",
"description": "catalog indexing status",
"type": "string",
"enum": [
"cv_active",
"nn_active",
"cv_pending",
"nn_pending",
"hold",
"successful"
]
},
"error": {
"title": "Error",
"description": "Indexing errors",
"type": "string",
"default": null
},
"created_at": {
"title": "Created At",
"description": "Catalog created at timestamp",
"type": "string",
"format": "date-time"
},
"updated_at": {
"title": "Updated At",
"description": "Catalog updated at timestamp",
"type": "string",
"format": "date-time"
},
"deleted_at": {
"title": "Deleted At",
"description": "Catalog deleted at timestamp",
"type": [
"string",
"null"
],
"format": "date-time"
},
"indexing_started_at": {
"title": "Indexing started at",
"description": "Catalog indexing start timestamp",
"type": "object",
"properties": {
"cv": {
"title": "cv indexing started at",
"description": "time cv indexing started",
"type": [
"string",
"null"
],
"format": "date-time"
},
"nn": {
"title": "nn indexing started at",
"description": "time nn indexing start",
"type": [
"string",
"null"
],
"format": "date-time"
}
}
},
"indexing_ended_at": {
"title": "Indexing ended at",
"description": "Catalog indexing end timestamp",
"type": "object",
"properties": {
"cv": {
"title": "cv indexing ended at",
"description": "time cv indexing ended",
"type": [
"string",
"null"
],
"format": "date-time"
},
"nn": {
"title": "nn indexing ended at",
"description": "time nn indexing ended",
"type": [
"string",
"null"
],
"format": "date-time"
}
}
}
}
}
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 custom defined catalogs.
| Attribute | Type | Description |
|---|---|---|
_type |
string |
Object type |
meta |
object |
Meta Information |
_id |
string |
A unique identifier |
schema |
string |
The schema used for catalog’s items: product or style |
name |
string |
A custom name for the catalog |
description |
string |
A custom description |
access |
string |
Catalog accecssibility: public or private |
priority |
integer |
Indexing queue priority |
enabled |
boolean |
Catalog indexing flag |
user |
object |
Catalog owner reference |
size |
integer |
Number or items in catalog |
status |
string |
Catalog indexing status |
error |
string |
Indexing Errors |
created_at |
string (date-time) |
Creation of date/time. |
updated_at |
string (date-time) |
Updated date/time |
deleted_at |
string (date-time) |
Deleted date/time |
indexing_started_at |
object |
Indexing operation start date/time |
indexing_ended_at |
object |
Indexing oepration end date/time |
Catalog Item
Example: Catalog Item Object
{
"_id": "catalogitem-1",
"images": [
{
"uri": "https://image_url_1.jpg",
"_type": "Image",
"status": "pending",
"error": null
},
{
"uri": "https://image_url_2.jpg",
"_type": "Image",
"status": "pending",
"error": null
},
],
"data": {
"stock": true,
"name": "product name",
"gender": "women",
"price": 200,
"brand": "new brand",
"vendor": "new vendor",
"country": "US",
"sku": "2153608405:sweaters",
"url": "https://productpage.com",
"category": "sweaters",
},
"category": {
"name": "sweaters",
"id": "sweaters"
},
"_type": "CatalogItem",
"created_at": "2019-03-11T20:41:35.105Z",
"updated_at": "2019-03-11T20:41:35.106Z",
"status": "cv_pending",
"catalog": {
"_type": "Catalog",
"_id": "1",
"name": "catalog-1"
},
"schema": "product",
"fingerprint": "580498c0f46e206f13a8ed8ebfb3595a"
}
Schema: Catalog Item Object (Product)
{
"title": "Catalog Item",
"description": "A markable API product catalog item",
"type": "object",
"properties": {
"meta": {
"title": "Meta Information",
"description": "Meta data for model",
"type": "object"
},
"_type": {
"type": "string",
"default": "CatalogItem"
},
"_id": {
"title": "ID",
"description": "Primary key",
"type": "string"
},
"fingerprint": {
"title": "Fingerprint",
"description": "Unique catalaog item hash",
"type": "string"
},
"schema": {
"title": "Schema",
"description": "Determines type of catalog",
"type": "string",
"enum": [
"product",
"style"
],
"default": "product"
},
"schema_version": {
"title": "Schema Version",
"description": "Version",
"type": "string",
"default": "null"
},
"catalog": {
"title": "Catalog",
"description": "Catalog to which item belogs to",
"type": "object",
"properties": {
"_type": {
"type": "string",
"default": "Catalog"
},
"_id": {
"title": "ID",
"description": "Catalog ID"
},
"name": {
"title": "Name",
"description": "Catalog name",
"type": "string"
}
},
"required": [
"_id",
"name"
]
},
"images": {
"title": "Images",
"description": "Images in catalog item",
"type": "array",
"minItems": 1,
"maxItems": 100,
"uniqueItems": true,
"items": {
"$ref": "#/definitions/image"
}
},
"category": {
"title": "Category",
"description": "Catalog Item Category",
"type": [
"string",
"null"
],
"default": "null"
},
"attributes": {
"title": "Attributes",
"description": "Catalog Item Attributes",
"type": [
"object",
"null"
]
},
"data": {
"title": "Data",
"description": "Catalog item data properties",
"type": "object",
"properties": {
"id": {
"title": "ID",
"description": "Catalog Item ID",
"type": "string"
},
"url": {
"title": "URL",
"description": "Catalog Item URL",
"type": "string",
"pattern": "^(http://?|https://?|wss://?|ftp://|data:image?)"
},
"sku": {
"title": "SKU",
"description": "Catalog Item Stock Keeping Unit",
"type": "string"
},
"description": {
"title": "Description",
"description": "Catalog Item Description",
"type": "string"
},
"name": {
"title": "Name",
"description": "Catalog Item Name",
"type": "string"
},
"brand": {
"title": "Brand",
"description": "Catalog Item Brand",
"type": "string"
},
"vendor": {
"title": "Vendor",
"description": "Catalog Item Vendor",
"type": "string"
},
"category": {
"title": "Category",
"description": "Normalized Catalog Item Category",
"type": "string"
},
"gender": {
"title": "Gender",
"description": "Catalog Item Gender",
"enum": [
"men",
"women",
"unisex"
]
},
"color": {
"title": "Color",
"description": "Catalog Item Color",
"type": "string"
},
"price": {
"title": "Price",
"description": "Catalog Item Price",
"type": "number"
},
"currency": {
"title": "Currency",
"description": "Catalog Item Currency",
"type": "string",
"default": "USD"
}
},
"required": [
"url"
],
"additionalProperties": true
},
"status": {
"title": "Status",
"description": "Catalog Item Indexing Status",
"type": "string",
"enum": [
"cv_pending",
"nn_pending",
"successful",
"nodetections",
"failed"
]
},
"error": {
"title": "Error",
"description": "Errors produced during indexing",
"type": "object",
"default": "null"
},
"failed_count": {
"title": "Data",
"description": "Catalog item data properties",
"type": "object",
"properties": {
"cv": {
"type": "integer",
"default": 0
},
"nn": {
"type": "integer",
"default": 0
}
}
},
"created_at": {
"title": "Created At",
"description": "Catalog Item created at timestamp",
"type": "string",
"format": "date-time"
},
"updated_at": {
"title": "Updated At",
"description": "Catalog Item updated timestamp",
"type": "string",
"format": "date-time"
},
"indexed_started_at": {
"title": "Indexed Start At",
"description": "Catalog Item indexing start timestamp",
"type": "object",
"properties": {
"cv": {
"type": "string",
"format": "date-time"
},
"nn": {
"type": "string",
"format": "date-time"
}
}
},
"indexed_ended_at": {
"title": "Indexed End At",
"description": "Catalog item indexing end timestamp",
"type": "object",
"properties": {
"cv": {
"type": "string",
"format": "date-time"
},
"nn": {
"type": "string",
"format": "date-time"
}
}
}
},
"additionalProperties": false,
"if": {
"properties": {
"schema": {
"enum": [
"product"
]
}
},
"required": [
"schema"
]
},
"then": {
"required": [
"category",
"images",
"data"
]
},
"else": {
"required": [
"images",
"data"
]
},
"definitions": {
"image": {
"title": "Image",
"description": "Image",
"type": "object",
"properties": {
"_type": {
"type": "string",
"default": "Image"
},
"_id": {
"title": "Upload ID",
"type": "string"
},
"hash": {
"title": "Hash",
"description": "Unique image hash",
"type": "string"
},
"uri": {
"title": "URI",
"description": "Image URI",
"type": "string",
"pattern": "^(http://?|https://?|wss://?|ftp://|data:image?)"
},
"width": {
"title": "Width",
"description": "Image width",
"type": [
"number",
"null"
],
"default": null,
"minimum": 0
},
"height": {
"title": "Height",
"description": "Image height",
"type": [
"number",
"null"
],
"default": null,
"minimum": 0
},
"thumbnail": {
"title": "Thumbnail",
"description": "Thumbnail Upload",
"type": "object",
"properties": {
"uri": {
"title": "Thumbnail URI",
"type": "string",
"pattern": "^(http://?|https://?)"
},
"width": {
"title": "Width",
"description": "Image width",
"type": [
"number",
"null"
],
"default": null,
"minimum": 0
},
"height": {
"title": "Height",
"description": "Image height",
"type": [
"number",
"null"
],
"default": null,
"minimum": 0
}
}
},
"snapshot": {
"title": "Snapshot",
"type": "object",
"properties": {
"uri": {
"title": "URI",
"type": "string",
"pattern": "^(http://?|https://?)"
},
"path": {
"title": "Path",
"type": "string",
"pattern": "^file://"
}
}
},
"status": {
"title": "Image Indexing Status",
"type": "string",
"enum": [
"pending",
"error",
"success"
]
},
"error": {
"title": "Error",
"description": "Indexing errors",
"type": [
"object",
"null"
]
},
"stats": {
"title": "Statistics",
"description": "Image processing statistics",
"type": "object"
},
"model": {
"title": "Model",
"description": "Image model used in detection",
"type": "string"
},
"detections": {
"title": "Detections",
"description": "Image cv detections",
"type": "array",
"items": {
"$ref": "#/definitions/detection"
}
}
},
"required": [
"uri"
],
"additionalProperties": false
},
"detection": {
"title": "Detection",
"description": "Detected item",
"type": "object",
"properties": {
"_id": {
"title": "ID",
"description": "Detection ID",
"type": "string"
},
"bounding_box": {
"title": "Bounding Box",
"description": "Detection bounding box specifications",
"type": "object",
"properties": {
"x": {
"title": "X-coordinate",
"description": "bounding box x coordinate",
"type": "integer"
},
"y": {
"title": "Y-coordinate",
"description": "bounding box y coordinate",
"type": "integer"
},
"width": {
"title": "Width",
"description": "bounding box width",
"type": "integer"
},
"height": {
"title": "Height",
"description": "bounding box height",
"type": "integer"
}
},
"required": [
"x",
"y",
"width",
"height"
],
"additionalProperties": false
},
"category": {
"title": "Category",
"description": "Detected category",
"type": "string"
},
"score": {
"title": "Score",
"description": "Detection confidence",
"type": "number",
"minimum": 0,
"maximum": 1
},
"attributes": {
"title": "Attributes",
"description": "Detection attributes",
"type": "array",
"items": {
"$ref": "#/definitions/attribute"
}
},
"feature": {
"type": "object",
"title": "Feature Vector",
"description": "Detection Feature Vectors",
"properties": {
"hash": {
"title": "Hash",
"description": "MD5 Hash of Feature Vectors",
"type": "string",
"minLength": 32
},
"vector": {
"title": "Vector",
"description": "Detection Feature Vectors",
"type": "array",
"minLength": 128,
"maxItems": 128
}
},
"required": [
"hash",
"vector"
]
}
},
"required": [
"bounding_box",
"category",
"score",
"feature"
],
"additionalProperties": false
},
"attribute": {
"title": "Attribute",
"description": "Detection Attribute Type",
"type": "object",
"properties": {
"name": {
"title": "Name",
"description": "Attribute Name",
"type": "string",
"minLength": 1
},
"values": {
"title": "Values",
"description": "Attribute Values",
"type": "array",
"items": {
"title": "Value",
"description": "Label and Score",
"type": "object",
"properties": {
"value": {
"title": "Value",
"description": "Attribute Value Label",
"type": "string",
"minLength": 1
},
"score": {
"title": "Score",
"description": "Attribute Confidence Score",
"type": "number",
"minimum": 0,
"maximum": 1
}
}
}
}
},
"required": [
"name",
"value",
"score"
],
"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).
| Attribute | Type | Description |
|---|---|---|
_type |
string |
Object type |
meta |
object |
Meta Information |
_id |
string |
A unique identifier |
fingerprint |
string |
Unique catalog item hash |
schema |
string |
The schema used for catalog’s items: product or style |
schema_version |
string |
Schema Version Tag |
catalog |
object |
Catalog reference |
images |
array |
Visual representation of this item |
category |
string |
Taxonomic classification of item |
data |
object |
Custom - semantic representation of item |
status |
string |
Indexing status of item cv_pending, nn_pending, successful, nodetections, failed |
error |
object |
Errors produced during indexing operations |
failed_count |
object |
Count of failures during indexing operations |
created_at |
string (date-time) |
Creation date/time |
updated_at |
string (date-time) |
Updated date/time |
indexing_started_at |
object |
Indexing operation start date/time |
indexing_ended_at |
object |
Indexing oepration end date/time |
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": {
"user_id": "1",
"created_at": "2019-03-11T20:39:41.998Z",
"deleted_at": null,
"type": "Token",
"updated_at": "2019-03-11T20:39:42.010Z",
"access_token": "5c86c78e059dc998f2c80278",
"expires_at": "2024-03-09T20:39:41.998Z"
}
}
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": {
"name": "Developer at Client",
"website": "http://client.website.com",
"role": "user",
"email": "developer@client.com",
"company": "company_name",
"created_at": "2019-03-11T20:39:34.690Z",
"type": "User",
"updated_at": "2019-03-11T20:39:34.781Z",
"user_id": "user_id_1",
"clients": [
{
"client_secret": "client_secret_1",
"user_id": "user_id_1",
"domain": "http://localhost",
"created_at": "2019-03-11T20:39:34.789Z",
"type": "Client",
"updated_at": "2019-03-11T20:39:34.801Z",
"client_id": "client_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": {
"user_id": "user_id_1",
"client_id": "client_id_1",
"scope": "default",
"created_at": "2019-03-11T20:40:12.710Z",
"type": "Token",
"updated_at": "2019-03-11T20:40:12.723Z",
"access_token": "5c86c7ac1fa31898e65269fc",
"expires_at": "2024-03-09T20:40:12.710Z"
}
}
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 
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 can be a list of products sold online in a retail store. Each CatalogItem in the catalog contains images, category, a url that links to the product at the store, and gender associated associated with the item, e.g, men, women, unisex.
Style Catalogs
Style catalogs, however, are free form catalogs with just images and a designated gender. Style catalogs for example, can be comprised of a list of street images.
Example: Catalog Object
{
"_type": "Catalog",
"_id": "catalog_id_1",
"schema": "product",
"name": "catalog_name_1",
"description": "My product catalog",
"size": 5,
"access": "public",
"created_at": "2018-12-06T22:11:51.391Z",
"updated_at": "2019-03-09T03:09:17.309Z",
"user": {
"_type": "User",
"_id": "user_id_1"
},
},
{
"_type": "Catalog",
"_id": "catalog_id_2",
"schema": "style",
"name": "catalog_name_2",
"description": "My style catalog",
"size": 10,
"access": "public",
"created_at": "2018-12-06T22:11:51.391Z",
"updated_at": "2019-03-09T03:09:17.309Z",
"user": {
"_type": "User",
"_id": "user_id_1"
},
},
Schema: Catalog Object
{
"title": "Catalog",
"description": "A markable API catalog",
"type": "object",
"required": [
"schema",
"name",
"user"
],
"additionalProperties": false,
"properties": {
"_type": {
"type": "string",
"default": "Catalog",
"readOnly": true
},
"meta": {
"title": "Meta Information",
"description": "Meta data for model",
"type": "object"
},
"_id": {
"title": "ID",
"description": "Primary key",
"type": "string"
},
"schema": {
"title": "Schema",
"description": "Determines type of catalog",
"type": "string",
"enum": [
"product",
"style"
]
},
"name": {
"title": "Catalog name",
"description": "Catalog name without spaces",
"type": "string",
"pattern": "^[a-zA-Z0-9_-]{4,}$"
},
"description": {
"title": "Catalog description",
"description": "Description of the catalog",
"type": "string"
},
"access": {
"title": "Catalog Access",
"description": "Accessibility option of catalog",
"type": "string",
"enum": [
"public",
"private"
],
"default": "private"
},
"priority": {
"title": "Indexing priority",
"type": "integer",
"description": "Indexing priority of catalog",
"default": 0
},
"enabled": {
"title": "",
"type": "boolean",
"description": "",
"default": true
},
"user": {
"title": "User",
"description": "User account that created catalog",
"type": "object",
"required": [
"_id"
],
"properties": {
"_id": {
"title": "ID",
"description": "User ID",
"readOnly": true
}
}
},
"size": {
"title": "Size",
"description": "Catalog Size",
"type": "integer"
},
"status": {
"title": "Indexing Status",
"description": "catalog indexing status",
"type": "string",
"enum": [
"cv_active",
"nn_active",
"cv_pending",
"nn_pending",
"hold",
"successful"
]
},
"error": {
"title": "Error",
"description": "Indexing errors",
"type": "string",
"default": null
},
"created_at": {
"title": "Created At",
"description": "Catalog created at timestamp",
"type": "string",
"format": "date-time"
},
"updated_at": {
"title": "Updated At",
"description": "Catalog updated at timestamp",
"type": "string",
"format": "date-time"
},
"deleted_at": {
"title": "Deleted At",
"description": "Catalog deleted at timestamp",
"type": [
"string",
"null"
],
"format": "date-time"
},
"indexing_started_at": {
"title": "Indexing started at",
"description": "Catalog indexing start timestamp",
"type": "object",
"properties": {
"cv": {
"title": "cv indexing started at",
"description": "time cv indexing started",
"type": [
"string",
"null"
],
"format": "date-time"
},
"nn": {
"title": "nn indexing started at",
"description": "time nn indexing start",
"type": [
"string",
"null"
],
"format": "date-time"
}
}
},
"indexing_ended_at": {
"title": "Indexing ended at",
"description": "Catalog indexing end timestamp",
"type": "object",
"properties": {
"cv": {
"title": "cv indexing ended at",
"description": "time cv indexing ended",
"type": [
"string",
"null"
],
"format": "date-time"
},
"nn": {
"title": "nn indexing ended at",
"description": "time nn indexing ended",
"type": [
"string",
"null"
],
"format": "date-time"
}
}
}
}
}
| Attribute | Type | Description |
|---|---|---|
_type |
string |
Object type |
meta |
object |
Meta Information |
_id |
string |
A unique identifier |
schema |
string |
The schema used for catalog’s items: product or style |
name |
string |
A custom name for the catalog |
description |
string |
A custom description |
access |
string |
Catalog accecssibility: public or private |
priority |
integer |
Indexing queue priority |
enabled |
boolean |
Catalog indexing flag |
user |
object |
Catalog owner reference |
size |
integer |
Number or items in catalog |
status |
string |
Catalog indexing status |
error |
string |
Indexing Errors |
created_at |
string (date-time) |
Creation of date/time. |
updated_at |
string (date-time) |
Updated date/time |
deleted_at |
string (date-time) |
Deleted date/time |
indexing_started_at |
object |
Indexing operation start date/time |
indexing_ended_at |
object |
Indexing oepration end date/time |
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",
"access": "public"
}
}
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",
"access": "public"
}
}
'
Example: Response
{
"data": {
"_type": "Catalog",
"_id": "catalog_id_1"
"schema": "product",
"name": "catalog_1",
"description": "My new catalog",
"size": 0,
"access": "public",
"created_at": "2019-03-11T20:40:36.726Z",
"updated_at": "2019-03-11T20:40:36.753Z",
"user": {
"_type": "User",
"_id": "user_id_1"
},
}
}
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
Example: Request
PUT https://catalog.markable.ai/catalogs/catalog_id_1 HTTP/1.1
Authorization: Bearer 123abc
{
"data": {
"name": "new_name_1",
"description": "Revised catalog description"
}
}
curl -X PUT https://catalog.markable.ai/catalogs/catalog_id_1 \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer 123abc' \
-d '
{
"data": {
"name": "new_name_1",
"description": "Revised catalog description"
}
}
'
Example: Response
{
"data": {
"_type": "Catalog",
"_id": "catalog_id_1"
"schema": "product",
"name": "new_name_1",
"description": "Revised catalog description",
"size": 0,
"access": "public",
"created_at": "2019-03-11T20:40:36.726Z",
"updated_at": "2019-03-11T20:40:36.753Z",
"user": {
"_type": "User",
"_id": "user_id_1"
},
}
}
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
Example: Request
DELETE https://catalog.markable.ai/catalogs/catalog_id_1 HTTP/1.1
Authorization: Bearer 123abc
curl -X DELETE https://catalog.markable.ai/catalogs/catalog_id_1 \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer 123abc'
Example: Response
{
"data": {
"_type": "Catalog",
"_id": "catalog_id_1",
"schema": "product",
"name": "new_name_1",
"description": "Revised catalog description",
"size": 0,
"access": "public",
"created_at": "2019-03-11T20:40:36.726Z",
"updated_at": "2019-03-11T20:41:35.129Z",
"user": {
"_type": "User",
"_id": "user_id_1"
}
}
}
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
Example: Request
GET https://catalog.markable.ai/catalogs/catalog_id_1 HTTP/1.1
Authorization: Bearer 123abc
curl -X GET https://catalog.markable.ai/catalogs/catalog_id_1 \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer 123abc'
Example: Response
{
"data": {
"_id": "catalog_id_1",
"_type": "Catalog",
"schema": "product",
"name": "catalog_1",
"description": "My new catalog",
"size": 0,
"access": "public",
"created_at": "2019-03-12T00:19:33.448Z",
"updated_at": "2019-03-12T00:19:33.478Z",
"user": {
"_type": "User",
"_id": "user_id_1"
}
}
}
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 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": [
{
"_id": "catalog_id_1",
"_type": "Catalog",
"schema": "product",
"name": "product_catalog",
"description": "catalog_2",
"size": 0,
"access": "public",
"created_at": "2019-03-12T00:19:33.448Z",
"updated_at": "2019-03-12T00:19:33.478Z",
"user": {
"_type": "User",
"_id": "user_id_1"
}
},
{
"_id": "catalog_id_2",
"_type": "Catalog",
"schema": "style",
"name": "style_catalog",
"description": "style catalog",
"size": 0,
"access": "private",
"created_at": "2019-03-12T00:22:02.002Z",
"updated_at": "2019-03-12T00:22:02.030Z",
"user": {
"_type": "User",
"_id": "user_id_1"
}
}
]
}
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
Query Parameters
| Parameter | Description |
|---|---|
limit |
The limit of items to return (defaults to 50). |
skip |
The skip of items to return. |
Catalog Stats
Catalog statistics explaning
- Status: How many of your catalogItems are indexed, with statuses
pending,errorandsuccess - Category: Spread of categories of your catalog
- Gender: Spread of gender in the catalog.
nullbeing that we default towomen.
Example: Request
GET https://catalog.markable.ai/catalogs/catalog_id_1/stats HTTP/1.1
Authorization: Bearer 123abc
curl -X GET https://catalog.markable.ai/catalogs/catalog_id_1/stats \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer 123abc'
Example: Response
{
"data": {
"category": [
{
"_id": "skirts",
"total": 1
},
{
"_id": "glasses",
"total": 1
},
{
"_id": "jeans",
"total": 1
},
{
"_id": "overalls",
"total": 1
},
{
"_id": "tanks_camis",
"total": 1
}
],
"status": [
{
"_id": "error",
"total": 1
},
{
"_id": "ok",
"total": 1
},
{
"_id": "pending",
"total": 1
}
],
"gender": [
{
"_id": "men",
"total": 1
},
{
"_id": "women",
"total": 1
}
],
"errors": [
{
"_id": null,
"total": 1
}
],
"catalog": {
"_type": "Catalog",
"_id": "catalog_id_1",
"schema": "product",
"name": "product_catalog",
"description": "My product catalog",
"size": 10,
"access": "private",
"created_at": "2018-12-06T22:11:51.391Z",
"updated_at": "2019-03-02T17:40:40.728Z",
"user": {
"_type": "User",
"_id": "user_id_1"
},
}
}
}
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 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": [
{
"_id": "catalog_id_1",
"_type": "Catalog",
"schema": "product",
"size": 0,
"updated_at": "2019-03-12T00:19:33.478Z",
"name": "product_catalog",
"description": "catalog_2",
"created_at": "2019-03-12T00:19:33.448Z",
"access": "public",
"user": {
"_type": "User",
"_id": "user_id_1"
}
},
{
"_id": "catalog_id_4",
"_type": "Catalog",
"schema": "style",
"size": 0,
"updated_at": "2019-03-12T00:22:02.030Z",
"name": "style_catalog_4",
"description": "style catalog 4",
"created_at": "2019-03-12T00:22:02.002Z",
"access": "public",
"user": {
"_type": "User",
"_id": "user_id_2"
}
}
]
}
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 
The Catalog Item Object
Example: Catalog Item Object
{
"_id": "catalogitem-1",
"images": [
{
"uri": "https://image_url_1.jpg",
"_type": "Image",
"status": "pending",
"error": null
},
{
"uri": "https://image_url_2.jpg",
"_type": "Image",
"status": "pending",
"error": null
},
],
"data": {
"url": "https://productpage.com",
"gender": "female",
"age_group": "adults",
"stock": true,
"name": "product name",
"price": 200,
"brand": "new brand",
"vendor": "new vendor",
"country": "US",
"sku": "2153608405:sweaters",
"category": "sweaters",
},
"category": {
"name": "sweaters",
"id": "sweaters"
},
"_type": "CatalogItem",
"created_at": "2019-03-11T20:41:35.105Z",
"updated_at": "2019-03-11T20:41:35.106Z",
"status": "cv_pending",
"catalog": {
"_type": "Catalog",
"_id": "1",
"name": "catalog-1"
},
"schema": "product",
"fingerprint": "580498c0f46e206f13a8ed8ebfb3595a"
}
Schema: Catalog Item Object (Product)
{
"title": "Catalog Item",
"description": "A markable API product catalog item",
"type": "object",
"properties": {
"meta": {
"title": "Meta Information",
"description": "Meta data for model",
"type": "object"
},
"_type": {
"type": "string",
"default": "CatalogItem"
},
"_id": {
"title": "ID",
"description": "Primary key",
"type": "string"
},
"fingerprint": {
"title": "Fingerprint",
"description": "Unique catalaog item hash",
"type": "string"
},
"schema": {
"title": "Schema",
"description": "Determines type of catalog",
"type": "string",
"enum": [
"product",
"style"
],
"default": "product"
},
"schema_version": {
"title": "Schema Version",
"description": "Version",
"type": "string",
"default": "null"
},
"catalog": {
"title": "Catalog",
"description": "Catalog to which item belogs to",
"type": "object",
"properties": {
"_type": {
"type": "string",
"default": "Catalog"
},
"_id": {
"title": "ID",
"description": "Catalog ID"
},
"name": {
"title": "Name",
"description": "Catalog name",
"type": "string"
}
},
"required": [
"_id",
"name"
]
},
"images": {
"title": "Images",
"description": "Images in catalog item",
"type": "array",
"minItems": 1,
"maxItems": 100,
"uniqueItems": true,
"items": {
"$ref": "#/definitions/image"
}
},
"category": {
"title": "Category",
"description": "Catalog Item Category",
"type": [
"string",
"null"
],
"default": "null"
},
"attributes": {
"title": "Attributes",
"description": "Catalog Item Attributes",
"type": [
"object",
"null"
]
},
"data": {
"title": "Data",
"description": "Catalog item data properties",
"type": "object",
"properties": {
"id": {
"title": "ID",
"description": "Catalog Item ID",
"type": "string"
},
"url": {
"title": "URL",
"description": "Catalog Item URL",
"type": "string",
"pattern": "^(http://?|https://?|wss://?|ftp://|data:image?)"
},
"sku": {
"title": "SKU",
"description": "Catalog Item Stock Keeping Unit",
"type": "string"
},
"description": {
"title": "Description",
"description": "Catalog Item Description",
"type": "string"
},
"name": {
"title": "Name",
"description": "Catalog Item Name",
"type": "string"
},
"brand": {
"title": "Brand",
"description": "Catalog Item Brand",
"type": "string"
},
"vendor": {
"title": "Vendor",
"description": "Catalog Item Vendor",
"type": "string"
},
"category": {
"title": "Category",
"description": "Normalized Catalog Item Category",
"type": "string"
},
"gender": {
"title": "Gender",
"description": "Catalog Item Gender",
"enum": [
"male",
"female",
"unisex"
]
},
"age_group": {
"title": "Gender",
"description": "Catalog Item Gender",
"enum": [
"children",
"adults",
"toddlers"
]
},
"color": {
"title": "Color",
"description": "Catalog Item Color",
"type": "string"
},
"price": {
"title": "Price",
"description": "Catalog Item Price",
"type": "number"
},
"currency": {
"title": "Currency",
"description": "Catalog Item Currency",
"type": "string",
"default": "USD"
}
},
"required": [
"url",
"gender",
"age_group"
],
"additionalProperties": true
},
"status": {
"title": "Status",
"description": "Catalog Item Indexing Status",
"type": "string",
"enum": [
"cv_pending",
"nn_pending",
"successful",
"nodetections",
"failed"
]
},
"error": {
"title": "Error",
"description": "Errors produced during indexing",
"type": "object",
"default": "null"
},
"failed_count": {
"title": "Data",
"description": "Catalog item data properties",
"type": "object",
"properties": {
"cv": {
"type": "integer",
"default": 0
},
"nn": {
"type": "integer",
"default": 0
}
}
},
"created_at": {
"title": "Created At",
"description": "Catalog Item created at timestamp",
"type": "string",
"format": "date-time"
},
"updated_at": {
"title": "Updated At",
"description": "Catalog Item updated timestamp",
"type": "string",
"format": "date-time"
},
"indexed_started_at": {
"title": "Indexed Start At",
"description": "Catalog Item indexing start timestamp",
"type": "object",
"properties": {
"cv": {
"type": "string",
"format": "date-time"
},
"nn": {
"type": "string",
"format": "date-time"
}
}
},
"indexed_ended_at": {
"title": "Indexed End At",
"description": "Catalog item indexing end timestamp",
"type": "object",
"properties": {
"cv": {
"type": "string",
"format": "date-time"
},
"nn": {
"type": "string",
"format": "date-time"
}
}
}
},
"additionalProperties": false,
"if": {
"properties": {
"schema": {
"enum": [
"product"
]
}
},
"required": [
"schema"
]
},
"then": {
"required": [
"category",
"images",
"data"
]
},
"else": {
"required": [
"images",
"data"
]
},
"definitions": {
"image": {
"title": "Image",
"description": "Image",
"type": "object",
"properties": {
"_type": {
"type": "string",
"default": "Image"
},
"_id": {
"title": "Upload ID",
"type": "string"
},
"hash": {
"title": "Hash",
"description": "Unique image hash",
"type": "string"
},
"uri": {
"title": "URI",
"description": "Image URI",
"type": "string",
"pattern": "^(http://?|https://?|wss://?|ftp://|data:image?)"
},
"width": {
"title": "Width",
"description": "Image width",
"type": [
"number",
"null"
],
"default": null,
"minimum": 0
},
"height": {
"title": "Height",
"description": "Image height",
"type": [
"number",
"null"
],
"default": null,
"minimum": 0
},
"thumbnail": {
"title": "Thumbnail",
"description": "Thumbnail Upload",
"type": "object",
"properties": {
"uri": {
"title": "Thumbnail URI",
"type": "string",
"pattern": "^(http://?|https://?)"
},
"width": {
"title": "Width",
"description": "Image width",
"type": [
"number",
"null"
],
"default": null,
"minimum": 0
},
"height": {
"title": "Height",
"description": "Image height",
"type": [
"number",
"null"
],
"default": null,
"minimum": 0
}
}
},
"snapshot": {
"title": "Snapshot",
"type": "object",
"properties": {
"uri": {
"title": "URI",
"type": "string",
"pattern": "^(http://?|https://?)"
},
"path": {
"title": "Path",
"type": "string",
"pattern": "^file://"
}
}
},
"status": {
"title": "Image Indexing Status",
"type": "string",
"enum": [
"pending",
"error",
"success"
]
},
"error": {
"title": "Error",
"description": "Indexing errors",
"type": [
"object",
"null"
]
},
"stats": {
"title": "Statistics",
"description": "Image processing statistics",
"type": "object"
},
"model": {
"title": "Model",
"description": "Image model used in detection",
"type": "string"
},
"detections": {
"title": "Detections",
"description": "Image cv detections",
"type": "array",
"items": {
"$ref": "#/definitions/detection"
}
}
},
"required": [
"uri"
],
"additionalProperties": false
},
"detection": {
"title": "Detection",
"description": "Detected item",
"type": "object",
"properties": {
"_id": {
"title": "ID",
"description": "Detection ID",
"type": "string"
},
"bounding_box": {
"title": "Bounding Box",
"description": "Detection bounding box specifications",
"type": "object",
"properties": {
"x": {
"title": "X-coordinate",
"description": "bounding box x coordinate",
"type": "integer"
},
"y": {
"title": "Y-coordinate",
"description": "bounding box y coordinate",
"type": "integer"
},
"width": {
"title": "Width",
"description": "bounding box width",
"type": "integer"
},
"height": {
"title": "Height",
"description": "bounding box height",
"type": "integer"
}
},
"required": [
"x",
"y",
"width",
"height"
],
"additionalProperties": false
},
"category": {
"title": "Category",
"description": "Detected category",
"type": "string"
},
"score": {
"title": "Score",
"description": "Detection confidence",
"type": "number",
"minimum": 0,
"maximum": 1
},
"attributes": {
"title": "Attributes",
"description": "Detection attributes",
"type": "array",
"items": {
"$ref": "#/definitions/attribute"
}
},
"feature": {
"type": "object",
"title": "Feature Vector",
"description": "Detection Feature Vectors",
"properties": {
"hash": {
"title": "Hash",
"description": "MD5 Hash of Feature Vectors",
"type": "string",
"minLength": 32
},
"vector": {
"title": "Vector",
"description": "Detection Feature Vectors",
"type": "array",
"minLength": 128,
"maxItems": 128
}
},
"required": [
"hash",
"vector"
]
}
},
"required": [
"bounding_box",
"category",
"score",
"feature"
],
"additionalProperties": false
},
"attribute": {
"title": "Attribute",
"description": "Detection Attribute Type",
"type": "object",
"properties": {
"name": {
"title": "Name",
"description": "Attribute Name",
"type": "string",
"minLength": 1
},
"values": {
"title": "Values",
"description": "Attribute Values",
"type": "array",
"items": {
"title": "Value",
"description": "Label and Score",
"type": "object",
"properties": {
"value": {
"title": "Value",
"description": "Attribute Value Label",
"type": "string",
"minLength": 1
},
"score": {
"title": "Score",
"description": "Attribute Confidence Score",
"type": "number",
"minimum": 0,
"maximum": 1
}
}
}
}
},
"required": [
"name",
"value",
"score"
],
"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 either Product or Style. Catalog items are organized by catalogs.
Note
- Internally, the uniqueness of a catalogItem depends on the imageURL(s), gender and the markable category (fingerprint).
- Use the
datakey below to add free form information about the CatalogItem. data.url,data.gender,data.age_group, is required.dataalso supports optional fields likebrand,color,vendor&sku.
| Attribute | Type | Description |
|---|---|---|
_type |
string |
Object type |
meta |
object |
Meta Information |
_id |
string |
A unique identifier |
fingerprint |
string |
Unique catalog item hash |
schema |
string |
The schema used for catalog’s items: product or style |
schema_version |
string |
Schema Version Tag |
catalog |
object |
Catalog reference |
images |
array |
Visual representation of this item |
category |
string |
Taxonomic classification of item |
data |
object |
Custom - semantic representation of item |
status |
string |
Indexing status of item cv_pending, nn_pending, successful, nodetections, failed |
error |
object |
Errors produced during indexing operations |
failed_count |
object |
Count of failures during indexing operations |
created_at |
string (date-time) |
Creation date/time |
updated_at |
string (date-time) |
Updated date/time |
indexing_started_at |
object |
Indexing operation start date/time |
indexing_ended_at |
object |
Indexing oepration end date/time |
Auto Categorize a CatalogItem
The following feature attempts to predict the Markable category based on textual information.
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",
"gender": "male",
"age_group": "adults",
"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",
"gender": "male",
"age_group": "adults",
"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": "hhttps://example.com/products/1/b.png"
}
],
"data": {
"url": "https://example.com/product/shoes.html",
"gender": "male",
"age_group": "adults",
"name": "A shoe product",
"description": "This is a fantastic shoe product",
"categoryInfo": "Some relevant information about category"
},
"category": {
"name": "shoes",
"id": "shoes"
}
}
}
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
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" : "female",
"age_group": "adults"
"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" : "female",
"age_group": "adults",
"vendor" : "vendor",
"stock" : true,
"price" : 30,
"currency" : "USD"
}
}
}
'
Example: Response
{
"data": {
"images": [
{
"uri": "https://example.com/products/1/a.png",
"_type": "Image",
"status": "pending",
"error": null
},
{
"uri": "https://example.com/products/1/b.png",
"_type": "Image",
"status": "pending",
"error": null
}
],
"data": {
"url": "https://example.com/product/page.html",
"id": "external-id-1",
"name" : "A great awesome product",
"brand" : "Brand",
"color" : "green",
"gender" : "female",
"age_group": "adults"
"vendor" : "vendor",
"stock" : true,
"price" : 30,
"currency" : "USD"
},
"category": {
"name": "glasses",
"id": "glasses"
},
"_type": "CatalogItem",
"created_at": "2019-03-12T21:22:04.345Z",
"updated_at": "2019-03-12T21:22:04.345Z",
"status": "cv_pending",
"catalog": {
"_type": "Catalog",
"_id": "1",
"name": "catalog1"
},
"schema": "product",
"fingerprint": "uniqueID",
"_id": "item-1"
}
}
Example: Request (with thumbnail generation option)
POST https://catalog.markable.ai/catalogs/catalog-1/items HTTP/1.1
Authorization: Bearer 123abc
{
"data": {
"options": { "transform": true, "width": 100, "height": 100 },
"images": [
{
"uri": "https://example.com/products/2/a.png"
},
{
"uri": "https://example.com/products/2/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" : "female",
"age_group": "adults"
"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": {
"options": { "transform": true, "width": 100, "height": 100 },
"images": [
{
"uri": "https://example.com/products/2/a.png"
},
{
"uri": "https://example.com/products/2/b.png"
}
],
"category": {
"name": "shoes"
}
"data": {
"url": "https://example.com/product/shoes.html",
"gender": "female",
"age_group": "adults",
"name": "A shoe product",
"description": "This is a fantastic shoe product",
"categoryInfo": "Some relevant information about category",
}
}
}
'
Example: Response
{
"data": {
"images": [
{
"_type": "Image",
"_id": "1",
"uri": "https://example.com/products/2/a.png",
"width": null,
"height": null,
"status": "pending",
"error": null
},
{
"_type": "Image",
"_id": "2",
"uri": "https://example.com/products/2/b.png",
"width": null,
"height": null,
"status": "pending",
"error": null
}
],
"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",
"gender": "female",
"age_group": "adults"
},
"category": {
"name": "shoes",
"id": "shoes"
},
"_type": "CatalogItem",
"created_at": "2019-03-12T21:58:43.099Z",
"updated_at": "2019-03-12T21:58:43.100Z",
"status": "cv_pending",
"catalog": {
"_type": "Catalog",
"_id": "catalog_id_1",
"name": "catalog1"
},
"schema": "product",
"fingerprint": "uniqueID",
"_id": "item-2"
}
}
Create a new catalog item in your catalog that will eventually get indexed.
- There is an option to pass
data.genderfor gender search if needed. By default, we assignfemaleas gender - There is an option to pass
data.age_group. By default, we assignadultsas age_group data.url,data.gender, anddata.age_groupare mandatory.
Indexing
- We index the products and update the status of every image on a catalog item. Status are either
success,errorandpending. Catalog item images start atpendingstatus. - The image width and height will be appended to each image object after successful indexing.
- If we detect errors with indexing, we expose information on why in the
images.errorobject.
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
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": {
"images": [
{
"_type": "Image",
"_id": "image1",
"uri": "https://example.com/products/2/a.png",
"width": null,
"height": null,
"status": "pending",
"error": null
},
{
"_type": "Image",
"_id": "image2",
"uri": "https://example.com/products/2/b.png",
"width": null,
"height": null,
"status": "pending",
"error": null
}
],
"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",
"gender": "female",
"age_group": "adults"
},
"category": {
"name": "shoes",
"id": "shoes"
},
"_type": "CatalogItem",
"created_at": "2019-03-12T21:58:43.099Z",
"updated_at": "2019-03-12T21:58:43.100Z",
"status": "cv_pending",
"catalog": {
"_type": "Catalog",
"_id": "catalog_id_1",
"name": "catalog1"
},
"schema": "product",
"fingerprint": "uniqueID",
"_id": "item-2"
}
}
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
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": {
"_id": "item_id_3",
"schema_version": "v1.0.0",
"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",
"gender": "female",
"age_group": "adults",
},
"fingerprint": "uniqueID",
"failed_count": {
"cv": 0
},
"updated_at": "2019-03-13T00:20:44.589Z",
"schema": "product",
"images": [
{
"uri": "https://example.com/products/3/a.png",
"status": "ok",
"width": 853,
"height": 853,
"error": null,
}
],
"status": "nn_pending",
"error": null,
"catalog": {
"_id": "catalog_id_1"
},
"indexing_ended_at": {
"cv": "2019-03-08T22:45:05.195159+00:00"
},
"created_at": "2018-09-04T20:40:26.225Z",
"indexing_started_at": {
"cv": "2019-03-08T21:15:47.358115+00:00"
}
}
}
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 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": [
{
"_id": "item-1",
"images": [
{
"uri": "https://agreatproductimage/a.jpg",
"_type": "Image",
"_id": "uniqueID",
"thumbnail": {
"uri": "https://markable/thumbnail/product/a.jpeg",
"width": 75,
"height": 100
},
"status": "ok",
"error": null,
"width": 1000,
"height": 1334,
},
{
"uri": "https://agreatproductimage/b.jpg",
"_type": "Image",
"_id": "uniqueID",
"thumbnail": {
"uri": "https://markable/thumbnail/product/b.jpeg",
"width": 75,
"height": 100
},
"status": "ok",
"error": null,
"width": 1000,
"height": 1334,
},
{
"uri": "https://agreatproductimage/c.jpg",
"_type": "Image",
"_id": "uniqueID",
"thumbnail": {
"uri": "https://markable/thumbnail/product/c.jpeg",
"width": 75,
"height": 100
},
"status": "ok",
"error": null,
"width": 1000,
"height": 1334,
}
],
"data": {
"id": "external-id",
"sku": "external-sku",
"name": "product name",
"url": "https://example.com/product.html",
"color": "blue",
"gender": "women",
"description": "Product description",
"category": "Shoulder Bags",
"stock": true,
"price": 80,
"currency": "US"
},
"category": {
"name": "handbags",
"id": "handbags"
},
"_type": "CatalogItem",
"created_at": "2019-03-07T11:00:17.101Z",
"updated_at": "2019-03-13T18:05:07.337Z",
"status": "nn_pending",
"catalog": {
"_id": "catalog_id_1"
},
"schema": "product",
"fingerprint": "uniqueID",
"indexing_started_at": {
"cv": "2019-03-09T21:07:29.548721+00:00"
},
"indexing_ended_at": {
"cv": "2019-03-09T21:07:38.005306+00:00"
},
"error": null,
"failed_count": {
"cv": 0
}
},
{
"_id": "item-2",
"images": [
{
"uri": "https://anothergreatproductimage/a.jpg",
"_type": "Image",
"_id": "uniqueID",
"thumbnail": {
"uri": "https://markable/thumbnail/anotherproduct/a.jpeg",
"width": 75,
"height": 100
},
"status": "ok",
"error": null,
"width": 1000,
"height": 1334,
},
{
"uri": "https://anothergreatproductimage/b.jpg",
"_type": "Image",
"_id": "uniqueID",
"thumbnail": {
"uri": "https://markable/thumbnail/anotherproduct/b.jpeg",
"width": 75,
"height": 100
},
"status": "ok",
"error": null,
"width": 1000,
"height": 1334,
},
{
"uri": "https://anothergreatproductimage/c.jpg",
"_type": "Image",
"_id": "uniqueID",
"thumbnail": {
"uri": "https://markable/thumbnail/anotherproduct/c.jpeg",
"width": 75,
"height": 100
},
"status": "ok",
"error": null,
"width": 1000,
"height": 1334,
}
],
"data": {
"id": "external-id",
"sku": "external-sku",
"name": "product name",
"url": "https://example.com/anotherproduct.html",
"color": "blue",
"gender": "women",
"description": "Product description",
"category": "Shoes",
"stock": true,
"price": 80,
"currency": "US"
},
"category": {
"name": "shoes",
"id": "shoes"
},
"_type": "CatalogItem",
"created_at": "2019-03-07T11:00:18.421Z",
"updated_at": "2019-03-13T18:05:07.382Z",
"status": "nn_pending",
"catalog": {
"_id": "catalog_id_1"
},
"schema": "product",
"fingerprint": "uniqueID",
"indexing_started_at": {
"cv": "2019-03-09T21:07:29.550073+00:00"
},
"indexing_ended_at": {
"cv": "2019-03-09T21:07:39.090980+00:00"
},
"error": null,
"failed_count": {
"cv": 0
}
}
]
}
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 20). |
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.
We support
.jpg,.jpeg,.pngMinimum image size =
100pxMaximum image size =
5000pxMaximum image memory size =
10485760b
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": {
"bags": [
"handbags",
"clutches",
"backpacks",
"messengerbags"
],
"footwear": [
"boots",
"shoes",
"sandals",
"slippers"
],
"fullbody": [
"rompers",
"overalls",
"dresses",
"jumpsuits"
],
"glasses": [
"glasses"
],
"headwear": [
"beanieknitcaps",
"baseballcaps",
"berets",
"sunhats_cowboyhats"
],
"humans": [
"humans"
],
"jewelry_watches": [
"watches"
],
"lowerbody": [
"shorts",
"jeans",
"skirts",
"leggings",
"pants"
],
"upperbody": [
"vests",
"buttondowns",
"blouses",
"tees",
"suitcoats_blazers",
"tanks_camis",
"sweaters",
"tunics",
"longsleeveshirts",
"coats_jackets",
"hoodies",
"henleys",
"cardigans",
"polos"
],
"upperbody_accessories": [
"scarves_wraps",
"ties"
]
}
}
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": {
"backpacks": [
"color",
"pattern"
],
"baseballcaps": [
"color",
"pattern"
],
"beanieknitcaps": [
"color",
"pattern"
],
"berets": [
"color",
"pattern"
],
"blouses": [
"closing_style",
"collar_type",
"color",
"pattern",
"sleeve_length",
"upper_hemline"
],
"boots": [
"color",
"heel_height",
"heel_type",
"pattern",
"shaft_height",
"toe_style"
],
"buttondowns": [
"closing_style",
"collar_type",
"color",
"pattern",
"sleeve_length",
"upper_hemline"
],
"cardigans": [
"closing_style",
"collar_type",
"color",
"pattern",
"sleeve_length",
"upper_hemline"
],
"clutches": [
"color",
"pattern"
],
"coats_jackets": [
"closing_style",
"collar_type",
"color",
"pattern",
"sleeve_length",
"upper_hemline"
],
"dresses": [
"closing_style",
"collar_type",
"color",
"dress_types",
"pattern",
"sleeve_length",
"upper_hemline"
],
"glasses": [
"color",
"pattern"
],
"handbags": [
"color",
"pattern"
],
"henleys": [
"closing_style",
"collar_type",
"color",
"pattern",
"sleeve_length",
"upper_hemline"
],
"hoodies": [
"closing_style",
"collar_type",
"color",
"pattern",
"sleeve_length",
"upper_hemline"
],
"humans": [
"gender"
],
"jeans": [
"color",
"jeans_fit",
"jeans_type",
"lower_hemline",
"pattern"
],
"jumpsuits": [
"closing_style",
"collar_type",
"color",
"pattern",
"sleeve_length",
"upper_hemline"
],
"leggings": [
"color",
"lower_hemline",
"pattern"
],
"longsleeveshirts": [
"closing_style",
"collar_type",
"color",
"pattern",
"sleeve_length",
"upper_hemline"
],
"messengerbags": [
"color",
"pattern"
],
"overalls": [
"closing_style",
"collar_type",
"color",
"pattern",
"sleeve_length",
"upper_hemline"
],
"pants": [
"color",
"lower_hemline",
"pattern"
],
"polos": [
"closing_style",
"collar_type",
"color",
"pattern",
"sleeve_length",
"upper_hemline"
],
"rompers": [
"closing_style",
"collar_type",
"color",
"pattern",
"sleeve_length",
"upper_hemline"
],
"sandals": [
"color",
"heel_height",
"heel_type",
"pattern",
"shaft_height",
"toe_style"
],
"scarves_wraps": [
"color",
"pattern"
],
"shoes": [
"color",
"heel_height",
"heel_type",
"pattern",
"shaft_height",
"toe_style"
],
"shorts": [
"color",
"lower_hemline",
"pattern"
],
"skirts": [
"color",
"lower_hemline",
"pattern",
"skirt_type"
],
"slippers": [
"color",
"heel_height",
"heel_type",
"pattern",
"shaft_height",
"toe_style"
],
"suitcoats_blazers": [
"closing_style",
"collar_type",
"color",
"pattern",
"sleeve_length",
"upper_hemline"
],
"sunhats_cowboyhats": [
"color",
"pattern"
],
"sweaters": [
"closing_style",
"collar_type",
"color",
"pattern",
"sleeve_length",
"upper_hemline"
],
"tanks_camis": [
"closing_style",
"collar_type",
"color",
"pattern",
"sleeve_length",
"upper_hemline"
],
"tees": [
"closing_style",
"collar_type",
"color",
"pattern",
"sleeve_length",
"upper_hemline"
],
"ties": [
"color",
"pattern"
],
"tunics": [
"closing_style",
"collar_type",
"color",
"pattern",
"sleeve_length",
"upper_hemline"
],
"vests": [
"closing_style",
"collar_type",
"color",
"pattern",
"sleeve_length",
"upper_hemline"
],
"watches": [
"color",
"pattern"
]
}
}
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 
Our Product Search returns the most visually relevant images in your product schema catalog.
The Product Search Query Object
Example: Product Search Query Object (defaults to auto detect gender)
{
"data": {
"image_uri": "https://example.com/images/1.png",
"catalogs": [
{
"name": "catalog-name-1"
},
{
"name": "catalog-name-2"
}
]
}
}
Example: Product Search Query Object With Gender Specific Results
{
"data": {
"gender": ["female"],
"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": {
"gender": ["male"],
"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": {
"relevance": 90
"attributes": 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 | Either ['male'], ['female'], ['unisex'] or any combination can be provided in the request to limit all results to specified gender. If no gender field is provided, we will automatically detect gender and return detected gender based results. If gender is not detected, results will return closest matching items irrespective of gender. |
catalogs |
Array<Catalog> | List of product catalogs (public or private) included in the visual search scope. Accounts can be updated with Default catalogs to perform search without explicitly specifying the catalog name or ID. |
options |
Object | A list of options that we support. Currently we support the options below |
Options for Search
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 | Automatically detect gender and return detected gender based results. Note that this option defaults to true if gender is not specified in the request, and false if gender is provided. |
attributes |
Boolean | Return attributes for every catalogItem, for both the searched input image and the images in the results. Note that this option will introduce a few 100ms in search. There is no guarantee that the attributes will be common between the input image and the result images; however, its highly likely that they will be. |
human_detection |
Boolean | Return bounding boxes for human detections. Default is false. |
centerness_filter |
Boolean | Applies heuristics to return detections and results from the center of an image. Default is false. |
return_specific_nn_match |
Boolean | When a catalog item contains multiple images of the product or item, this option will only return the specific image selected by similarity search. Default is false. |
family_search |
Boolean | Searches similar items in related taxanomy groups. Default is true. |
unique_products |
Boolean | Returns only one product in catalogs where a product image is used in multiple products. Default is false. |
commission_ranking |
Object | Return nearest neighbor results sorted by highest commission value when available. |
commission_ranking: enabled |
Boolean | Will activate ranking by commission value. Default is true when commission_ranking option is passed. |
commission_ranking: max_items_ranked |
Number | Number of items ranked by commission value. The remaining results are sorted by similiarty score. |
commission_ranking: max_items_returned |
Number | Number of results to return. This setting overrides limit settings in Lens API. |
Beta Options for Search
| Attribute | Type | Description |
|---|---|---|
attributes_only |
Boolean | Will return detections and atttributes for input image. This option will not perform similarity search. |
Product Search
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": ["male"],
"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": ["male"],
"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={ "gender": ["female"] , "catalogs": [{ "name": "catalog-name-1" }] }'
Example: Response
{
"meta": {
"image": {
"uri": "http://www.somefashion.com/image.jpg",
"width": 1365,
"height": 2048
},
"stats": {
"cv_detection": 2065,
"nn_search": 199,
"db_queries": 292
},
"catalogs": {
"requested": [
"catalog_id_1"
],
"searched": [
"catalog_id_1"
]
},
"gender": [
"auto-detect"
],
"options": {
"limit": 30,
"relevance": 50,
"attributes": false,
"auto_detect_gender": false,
"human_detection": false
}
},
"data": [
{
"_type": "SearchResult",
"_id": "uniqueID",
"score": 0.9995391368865967,
"category": {
"_type": "Category",
"_id": "humans",
"name": "humans"
},
"bounding_box": {
"_type": "BoundingBox",
"x": 367.3973388671875,
"y": 66.24256896972656,
"width": 609.6744995117188,
"height": 1876.552230834961
},
"gender": [
"female"
],
"matches": []
},
{
"_type": "SearchResult",
"_id": "uniqueID",
"score": 0.9929601550102234,
"category": {
"_type": "Category",
"_id": "handbags",
"name": "handbags"
},
"bounding_box": {
"_type": "BoundingBox",
"x": 367.1494140625,
"y": 1231.869140625,
"width": 182.40740966796875,
"height": 332.765380859375
},
"gender": [
"female"
],
"matches": [
{
"_type": "product",
"_id": "uniqueID",
"score": "0.902",
"images": [
{
"uri": "https://handbag/image.jpg",
"_type": "Image",
"_id": "uniqueID",
"thumbnail": {
"uri": "https://thumbnail.jpeg",
"width": 75,
"height": 100
},
"status": "ok",
"error": null,
"width": 1000,
"height": 1334,
}
],
"data": {
"id": "any custom data",
"name": "custom product name"
"url": "link_to_product_page",
},
"catalog": {
"_type": "Catalog",
"_id": "catalog_id_1",
"name": null
},
"created_at": "2019-03-14T13:50:04.134Z",
"updated_at": "2019-03-14T13:50:04.134Z"
},
{
"_type": "product",
"_id": "uniqueID",
"score": "0.899",
"images": [
{
"uri": "https://handbag/image2.jpg",
"_type": "Image",
"_id": "uniqueID",
"thumbnail": {
"uri": "https://thumbnail2.jpeg",
"width": 75,
"height": 100
},
"status": "ok",
"error": null,
"width": 1000,
"height": 1334,
}
],
"data": {
"id": "any custom data",
"name": "custom product name",
"url": "link_to_product_page",
},
"catalog": {
"_type": "Catalog",
"_id": "catalog_id_1",
"name": null
},
"created_at": "2019-03-14T13:50:04.134Z",
"updated_at": "2019-03-14T13:50:04.134Z"
},
]
},
{
"_type": "SearchResult",
"_id": "uniqueID",
"score": 0.9856816530227661,
"category": {
"_type": "Category",
"_id": "coats_jackets",
"name": "coats_jackets"
},
"bounding_box": {
"_type": "BoundingBox",
"x": 408.2473449707031,
"y": 325.932373046875,
"width": 560.6332702636719,
"height": 736.38623046875
},
"gender": [
"female"
],
"matches": [
{
"_type": "product",
"_id": "uniqueID",
"score": "0.924",
"images": [
{
"uri": "https://jacket/image.jpg",
"_type": "Image",
"_id": "uniqueID",
"thumbnail": {
"uri": "https://thumbnail.jpeg",
"width": 75,
"height": 100
},
"status": "ok",
"error": null,
"width": 1000,
"height": 1334,
},
],
"data": {
"id": "any custom data",
"name": "custom product name"
},
"catalog": {
"_type": "Catalog",
"_id": "catalog_id_1",
"name": null
},
"created_at": "2019-03-14T13:50:04.138Z",
"updated_at": "2019-03-14T13:50:04.138Z"
},
{
"_type": "product",
"_id": "uniqueID",
"score": "0.924",
"images": [
{
"uri": "https://jacket/image2.jpg",
"_type": "Image",
"_id": "uniqueID",
"thumbnail": {
"uri": "https://thumbnail2.jpeg",
"width": 75,
"height": 100
},
"status": "ok",
"error": null,
"width": 1000,
"height": 1334,
},
],
"data": {
"id": "any custom data",
"name": "custom product name",
"url": "link_to_product_page",
},
"catalog": {
"_type": "Catalog",
"_id": "catalog_id_1",
"name": null
},
"created_at": "2019-03-14T13:50:04.138Z",
"updated_at": "2019-03-14T13:50:04.138Z"
},
]
},
]
}
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. |
How to Wear It Search 
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.
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": "style-catalog-name-1"
},
{
"name": "style-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 | Either ['male'], ['female'], ['unisex'] or any combination can be provided in the request to limit all results to specified gender. If no gender field is provided, we will automatically detect gender and return detected gender based results. If gender is not detected, results will return closest matching items irrespective of gender. |
catalogs |
Array<Catalog> | List of style catalogs (public or private) included in the visual search scope. Accounts can be updated with Default catalogs to perform search without explicitly specifying the catalog name or ID. |
options |
Object | A list of options that we support. Currently we support the options below |
Options for Search
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 | Automatically detect gender and return detected gender based results. Note that this option defaults to true if gender is not specified in the request, and false if gender is provided. |
attributes |
Boolean | Return attributes for every catalogItem, for both the searched input image and the images in the results. Note that this option will introduce a few 100ms in search. There is no guarantee that the attributes will be common between the input image and the result images; however, its highly likely that they will be. |
human_detection |
Boolean | Return bounding boxes for human detections. Default is false. |
centerness_filter |
Boolean | Applies heuristics to return detections and results from the center of an image. Default is false. |
return_specific_nn_match |
Boolean | When a catalog item contains multiple images of the product or item, this option will only return the specific image selected by similarity search. Default is false. |
family_search |
Boolean | Searches similar items in related taxanomy groups. Default is true. |
unique_products |
Boolean | Returns only one product in catalogs where a product image is used in multiple products. Default is false. |
HTWI Search
Example: How to Wear it with
styleCatalog Names
POST https://catalog.markable.ai/image/search/style HTTP/1.1
Authorization: Bearer 123abc
{
"data": {
"image_uri": "http://i.com/1.png",
"catalogs": [
{
"name": "style-catalog-name-1"
},
{
"name": "style-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": "style-catalog-name-1"
},
{
"name": "style-catalog-name-2"
}
]
}
}
'
Example: How to Wear it with
styleCatalogs 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
styleCatalogs 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": ["male"],
"catalogs": [
{
"name": "style-catalog-name-1"
},
{
"name": "style-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": ["male", "female"],
"catalogs": [
{
"name": "style-catalog-name-1"
},
{
"name": "style-catalog-name-2"
}
]
}
}
'
Example: Multipart How to Wear it with
styleCatalogs (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": "style-catalog-name-1" }] }'
Example: Response
{
"meta": {
"image": {
"uri": "http://www.somefashion.com/image.jpg",
"width": 1848,
"height": 885
},
"stats": {
"cv_detection": 3919,
"nn_search": 240,
"db_queries": 195
},
"catalogs": {
"requested": [
"style_catalog_id_1"
],
"searched": [
"style_catalog_id_1"
]
},
"gender": [
"auto-detect"
],
"options": {
"limit": 30,
"relevance": 50,
"attributes": false,
"auto_detect_gender": false,
"human_detection": false
}
},
"data": [
{
"_type": "SearchResult",
"_id": "uniqueID",
"score": 0.8623029589653015,
"category": {
"_type": "Category",
"_id": "shoes",
"name": "shoes"
},
"bounding_box": {
"_type": "BoundingBox",
"x": 0,
"y": 0,
"width": 1846.52392578125,
"height": 851.519287109375
},
"gender": [
"female",
"unisex"
],
"matches": [
{
"_type": "style",
"_id": "uniqueID",
"score": "0.911",
"images": [
{
"height": 960,
"error": null,
"status": "ok",
"uri": "https://somestylephoto/image.jpg",
"width": 626,
"thumbnail": {
"uri": "https://thumbnail.jpeg",
"width": 65,
"height": 100
}
}
],
"data": {
"id": "any custom data",
"name": "custom product name",
"url": "link_to_style_image_page",
},
"catalog": {
"_type": "Catalog",
"_id": "style_catalog_id_1",
"name": null
},
"created_at": "2019-03-14T15:57:57.669Z",
"updated_at": "2019-03-14T15:57:57.669Z"
},
{
"_type": "style",
"_id": "uniqueID",
"score": "0.908",
"images": [
{
"error": null,
"height": 744,
"width": 935,
"status": "ok",
"uri": "https://somestylephoto2/image.jpg",
"thumbnail": {
"uri": "https://thumbnail.jpeg",
"width": 100,
"height": 80
}
}
],
"data": {
"id": "any custom data",
"name": "custom product name",
"url": "link_to_style_image_page",
},
"catalog": {
"_type": "Catalog",
"_id": "style_catalog_id_1",
"name": null
},
"created_at": "2019-03-14T15:57:57.669Z",
"updated_at": "2019-03-14T15:57:57.669Z"
},
]
}
]
}
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.
We support
.jpg,.jpeg,.pngMinimum image size =
100pxMaximum image size =
6000pxMaximum image memory size =
10485760bMinimum & Maximum image size ratio = [
0.4, 2.5]
Video Search
Moment API 
Our Video Product Search returns the most visually relevant products for pre-processed static videos.
The Video Search Query Object
Example: Video Search Query Object
{
"uri": "https://example.com/videos/1.mp4",
}
A Video Search Query (object) defines a visual search query for a video.
| Attribute | Type | Description |
|---|---|---|
uri |
String | A valid video URI. required |
force |
Boolean | Re-indexes a previously processed video |
options |
Object | A list of options that we support. Currently we support the options below |
Example: Video Search Query Object with Options
{
"uri": "https://example.com/videos/1.mp4",
"options": {
"limit": 15
"relevance": 0.80
"family_search": true
"deduplication": true
"human_detection": false
"specific_match": false
"catalogs": [
{
"name": "catalog_example",
}
],
"track": [0,30]
"seek": 0
"precision": 1
"framesPerSecond": 5
}
}
Options for Search
These options give you the flexibility to control how our visual search is performed.
| Attribute | Type | Description |
|---|---|---|
limit |
Number | Maximum number of result matches to return per detection. Default 15 |
relevance |
Number | Similarity confidence of results. Default .80. This takes precedence over limit |
family_search |
Boolean | Searches similar items in related taxanomy groups. Default is true. |
deduplication |
Boolean | Returns only one product in catalogs where a product image is used in multiple products. Default is true. |
human_detection |
Boolean | Return bounding boxes for human detections. Default is false. |
specific_match |
Boolean | When a catalog item contains multiple images of the product, this option will only return the specific image selected by similarity search. |
attributes |
Boolean | Return merged attributes for tracks. Default is false. |
seek |
Number | The timestamp at which search query is performed. |
track |
Array | The timestamp relative to seek timestamp. Both seek and track values will be used to calculate an absolute timestamp for which detections are tracked and merged during search operations. |
precision |
Number | The number used to round “seek” and “track” to a human readable number. Default value is 1 |
framesPerSecond |
Number | The number of frames per second at which the video is pre-processed. Default and Max value is 5 |
catalogs |
Array | List of product catalogs (public or private) included in the visual search scope. Accounts can be updated with Default catalogs to perform search without explicitly specifying the catalog name or ID. |
Search
Example: Request
POST http://video.markable.ai/video/search?page=0&pageLimit=2 HTTP/1.1
Authorization: Bearer 123abc
{
"data": {
"uri": "https://example.com/videos/1.mp4",
}
}
Example: Request Force Options
POST http://video.markable.ai/video/search?page=0&pageLimit=2 HTTP/1.1
Authorization: Bearer 123abc
{
"data": {
"uri": "https://example.com/videos/1.mp4",
"force": true
}
}
curl -X POST http://video.markable.ai/video/search?page=0&pageLimit=2 \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer 123abc' \
-d '
{
"data": {
"uri": "https://example.com/videos/1.mp4",
}
}
'
Example: Response - Pending Indexing, Force
"meta": {
"service": {
"name": "markable-video-service",
"version": "2.1.1",
"environment": "production"
},
"request": {
"protocol": "http",
"method": "POST",
"url": "/video/search?page=0&pageLimit=30",
"route": "/video/search",
"params": {},
"query": {
"page": "0",
"pageLimit": "30"
}
},
"pagination": {
"page": 0,
"pageBy": "index",
"pageLimit": 30,
"pageFrom": 0,
"pageTo": 30,
"pageSize": 30
},
"catalogs": {
"requested": [
"exmaple"
],
"searched": [],
"rejected": [
"exmaple"
]
},
"track": {
"trackStartAtTime": 0,
"trackEndAtTime": 30,
"trackStartAtIndex": 0,
"trackEndAtIndex": 90,
"trackSize": 90,
"precision": 1,
"seek": 0
},
"statuses": [
{
"type": "VideoJobStatus",
"step": "config",
"startedAt": 1585669803256,
"endedAt": 1585669803385,
"completed": 1,
"total": 1,
"unit": "configurations",
"status": 1,
"elapsedTime": 129,
"eachTime": 129,
"elapsedTimeString": "00:00:00.129",
"eachTimeString": "00:00:00.129",
"totalTime": 129,
"totalTimeString": "00:00:00.129"
},
{
"type": "VideoJobStatus",
"step": "meta",
"startedAt": 1585669803994,
"endedAt": 1585669806193,
"completed": 1,
"total": 1,
"unit": "metas",
"status": 1,
"elapsedTime": 2199,
"eachTime": 2199,
"elapsedTimeString": "00:00:02.199",
"eachTimeString": "00:00:02.199",
"totalTime": 2199,
"totalTimeString": "00:00:02.199"
},
{
"type": "VideoJobStatus",
"step": "download",
"startedAt": 1585669806275,
"endedAt": 1585669850566,
"completed": 553283420,
"total": 553283420,
"unit": "bytes",
"status": 1,
"elapsedTime": 44291,
"eachTime": 0.0000800511969073644,
"elapsedTimeString": "00:00:44.291",
"eachTimeString": "00:00:00.000",
"fingerprint": "b6a941d11dea83c84fb23c143aa4ebaa",
"totalTime": 44291,
"rate": 12492005.599331694,
"totalTimeString": "00:00:44.291"
},
{
"type": "VideoJobStatus",
"step": "snapshot",
"startedAt": 1585670660247,
"endedAt": 1585671758487,
"completed": 7945,
"total": 7945,
"unit": "frames",
"status": 1,
"elapsedTime": 1098240,
"eachTime": 138.23033354310888,
"elapsedTimeString": "00:18:18.240",
"eachTimeString": "00:00:00.138",
"totalTime": 1098240,
"rate": 7.234302156177156,
"totalTimeString": "00:18:18.240"
},
{
"_type": "VideoJobStatus",
"type": "VideoJobStatus",
"step": "cv",
"startedAt": 1585670673768,
"endedAt": 1586210046233,
"total": 7945,
"unit": "frames",
"completed": 7945,
"elapsedTime": 539372465,
"totalTime": 539372465,
"eachTime": 67888.29011957206,
"rate": 0.01473008081715851,
"elapsedTimeString": "05:49:32.465",
"eachTimeString": "00:01:07.888",
"totalTimeString": "05:49:32.465",
"status": 1
},
{
"type": "VideoJobStatus",
"step": "track",
"startedAt": 1586880237515,
"endedAt": 1586880237650,
"total": 90,
"completed": 90,
"unit": "frames",
"status": 1,
"elapsedTime": 135,
"eachTime": 1.5,
"totalTime": 135,
"elapsedTimeString": "00:00:00.135",
"eachTimeString": "00:00:00.001",
"totalTimeString": "00:00:00.135"
},
{
"type": "VideoJobStatus",
"step": "nn",
"startedAt": 1586880237673,
"endedAt": 1586880237707,
"total": 1,
"completed": 1,
"unit": "neighbors",
"status": 1,
"elapsedTime": 34,
"eachTime": 34,
"totalTime": 34,
"elapsedTimeString": "00:00:00.034",
"eachTimeString": "00:00:00.034",
"totalTimeString": "00:00:00.034"
},
{
"type": "VideoJobStatus",
"step": "db",
"startedAt": 1586880237710,
"endedAt": 1586880237710,
"total": 1,
"completed": 1,
"unit": "lookup",
"status": 1,
"elapsedTime": 0,
"eachTime": 0,
"totalTime": 0,
"elapsedTimeString": "00:00:00.000",
"eachTimeString": "00:00:00.000",
"totalTimeString": "00:00:00.000"
}
],
"exists": {
"configure": true,
"meta": true,
"download": true,
"snapshot": true,
"cv": true,
"track": true,
"nn": true,
"db": true
},
"state": {
"configure": {
"started": true,
"ended": true,
"succeeded": true,
"failed": false
},
"meta": {
"started": true,
"ended": true,
"succeeded": true,
"failed": false
},
"download": {
"started": true,
"ended": true,
"succeeded": true,
"failed": false
},
"snapshot": {
"started": true,
"ended": true,
"succeeded": true,
"failed": false
},
"cv": {
"started": true,
"ended": true,
"succeeded": true,
"failed": false
},
"track": {
"started": true,
"ended": true,
"succeeded": true,
"failed": false
},
"nn": {
"started": true,
"ended": true,
"succeeded": true,
"failed": false
},
"db": {
"started": true,
"ended": true,
"succeeded": true,
"failed": false
}
},
"enqueued": false,
"job": {
"_id": "5e8366ab611d5f001019d663",
"url": "https://example_video.mp4",
"created_at": "2020-03-31T15:50:03.470Z",
"updated_at": "2020-04-06T21:54:06.245Z",
"_type": "Video",
"uri": "https://example_video.mp4",
"options": {
"fingerprint": "b6a941d11dea83c84fb23c143aa4ebaa",
"framesPerSecond": 3,
"catalogs": [
{
"name": "exmaple_catalog"
}
]
}
},
"jobs": {
"pending": [],
"successful": [],
"failed": []
}
},
Example: Response - Fully indexed video with product results
{
"meta" : {"...."},
"data": [
{
"_type": "Frame",
"_id": "frame-26869006b3e9634223a9afd4a2dfc66b-0",
"index": 0,
"timestamp": 0,
"image": {
"_type": "Image",
"uri": "//localhost:1331/video/cache/uri-qa.markable.ai-a266ffad969fabefaa353b12bf732a93/catalogs-383808cdc34b010f04681287c74cb1af.fps-5/process/03.snapshot/raw/fps5-000001.png",
"width": 450,
"height": 800
},
"results": [
{
"_type": "SearchResult",
"_id": "result-frame-26869006b3e9634223a9afd4a2dfc66b-0-track-jeans_0",
"score": 0.9925562739372253,
"category": {
"_type": "Category",
"_id": "jeans",
"name": "jeans"
},
"bounding_box": {
"_type": "BoundingBox",
"_id": "bbox-45444c02571893d7d953d11b20477a13",
"x": 295.3294372558594,
"y": 365.76226806640625,
"width": 78.07376098632812,
"height": 203.5692138671875
},
"track": {
"_type": "Track",
"_id": "track-jeans_0",
"id": "track-jeans_0",
"index": 0,
"score": 0.9925562739372253,
"feature_hash": "22bba171c21c8dcd116415fc7267918f"
},
"matches": [
{
"_type": "CatalogItem",
"_id": "5deec3ee13ee690011eb124b",
"schema": "product",
"score": 0.9323215675354004,
"neighbor": {
"vector_hash": "e6bcad8f0230fb72b3046cc979e7dc55",
"score": 0.9323215675354004,
"catalog": "catalog1",
"category": "jeans",
"gender": "female",
"view": null,
"age_group": null,
"related_matches_id": null
},
"catalog": {
"_type": "Catalog",
"_id": "5de959fd0306310059298f44",
"name": "catalog1"
},
"images": [
{
"_type": "Image",
"_id": null,
"uri": "http://product-1.jpg",
"width": 1200,
"height": 1200
}
],
"data": {
"id": "6918341855521355924",
"sku": "6918341855521355924",
"name": "product",
"url": "http://product_webite.html",
"category": "jeans",
"gender": "female",
"age_group": "adults",
"stock": true,
"price": 499,
"sale_price": "228",
"currency": "USD"
},
"created_at": "2019-12-09T22:00:14.193Z",
"updated_at": "2019-12-12T01:50:38.925Z"
},
{
"_type": "CatalogItem",
"_id": "5def550be78030004ea89dfc",
"schema": "product",
"score": 0.9317789363861084,
"neighbor": {
"vector_hash": "72acce7d42dc18a87eaf857f179d71c8",
"score": 0.9317789363861084,
"catalog": "catalog2",
"category": "jeans",
"gender": "female",
"view": null,
"age_group": null,
"related_matches_id": null
},
"catalog": {
"_type": "Catalog",
"_id": "5dee896c2f767a004be741ab",
"name": "catalog2"
},
"images": [
{
"_type": "Image",
"_id": null,
"uri": "http://product-2.jpg",
"width": 800,
"height": 800
}
],
"data": {
"id": "592775994152",
"sku": "592775994152",
"name": "product2",
"url": "https://product_webite.html",
"category": "womens jeans",
"gender": "female",
"stock": true,
"currency": "USD",
"price": 98,
"age_group": "adults"
},
"created_at": "2019-12-10T08:19:23.403Z",
"updated_at": "2019-12-10T08:33:23.444Z"
},
{
"_type": "CatalogItem",
"_id": "5defe65e994eea0055aed1bc",
"schema": "product",
"score": 0.9316892147064209,
"neighbor": {
"vector_hash": "13562f2d63a24af8f5c4600d1f983e49",
"score": 0.9316892147064209,
"catalog": "catalog1",
"category": "jeans",
"gender": "female",
"view": null,
"age_group": null,
"related_matches_id": null
},
"catalog": {
"_type": "Catalog",
"_id": "5de959fd0306310059298f44",
"name": "catalog1"
},
"images": [
{
"_type": "Image",
"_id": null,
"uri": "http://product-3.jpg",
"width": 1200,
"height": 1200
}
],
"data": {
"id": "2164494563",
"sku": "2164494563",
"name": "product3",
"url": "http://product_webite.html",
"category": "jeans",
"gender": "female",
"age_group": "adults",
"stock": true,
"price": 828,
"sale_price": "579",
"currency": "USD"
},
"created_at": "2019-12-10T18:39:26.178Z",
"updated_at": "2019-12-12T01:53:42.366Z"
}
]
},
{
"_type": "SearchResult",
"_id": "result-frame-26869006b3e9634223a9afd4a2dfc66b-0-track-tees_1",
"score": 0.9778891801834106,
"category": {
"_type": "Category",
"_id": "tees",
"name": "tees"
},
"bounding_box": {
"_type": "BoundingBox",
"_id": "bbox-5a3c6a15b0b46bac1b2d547faa4bbd20",
"x": 287.39361572265625,
"y": 264.7693176269531,
"width": 104.07992553710938,
"height": 108.3822021484375
},
"track": {
"_type": "Track",
"_id": "track-tees_1",
"id": "track-tees_1",
"index": 1,
"score": 0.9778891801834106,
"feature_hash": "150d2db2669692c0bfcce36418e390d8"
},
"matches": [
{
"_type": "CatalogItem",
"_id": "5def55c65d131500236a2e5a",
"schema": "product",
"score": 0.9225725936889648,
"neighbor": {
"vector_hash": "ba0cf49508dd1e114f741ef5723652d1",
"score": 0.9225725936889648,
"catalog": "catalog2",
"category": "tees",
"gender": "female",
"view": null,
"age_group": null,
"related_matches_id": null
},
"catalog": {
"_type": "Catalog",
"_id": "5dee896c2f767a004be741ab",
"name": "catalog2"
},
"images": [
{
"_type": "Image",
"_id": null,
"uri": "http://product-1.jpg",
"width": 800,
"height": 800
}
],
"data": {
"id": "566798857134",
"sku": "566798857134",
"name": "product1",
"url": "http://product_webite.html"
"category": "Women s tanks camis",
"gender": "female",
"stock": true,
"price": 49,
"currency": "USD",
"age_group": "adults"
},
"created_at": "2019-12-10T08:22:30.148Z",
"updated_at": "2019-12-12T03:58:30.015Z"
},
{
"_type": "CatalogItem",
"_id": "5defdf48994eea0055ae95db",
"schema": "product",
"score": 0.9119216156005859,
"neighbor": {
"vector_hash": "06e2c32a5aa7c0a9d85633a45701bb3c",
"score": 0.9119216156005859,
"catalog": "catalog1",
"category": "tees",
"gender": "female",
"view": null,
"age_group": null,
"related_matches_id": null
},
"catalog": {
"_type": "Catalog",
"_id": "5de959fd0306310059298f44",
"name": "catalog1"
},
"images": [
{
"_type": "Image",
"_id": null,
"uri": "http://product-2.jpg",
"width": 1200,
"height": 1200
}
],
"data": {
"id": "2156283988",
"sku": "2156283988",
"name": "Product2",
"url": "https://product_webite.html",
"category": "tees",
"gender": "female",
"age_group": "adults",
"stock": true,
"price": 339,
"sale_price": "118",
"currency": "USD"
},
"created_at": "2019-12-10T18:09:12.117Z",
"updated_at": "2019-12-10T23:05:16.949Z"
},
{
"_type": "CatalogItem",
"_id": "5defdc67956117002ff8d6ee",
"schema": "product",
"score": 0.9104684257507324,
"neighbor": {
"vector_hash": "3ea97b55cbd5a9abb7adcc440357855a",
"score": 0.9104684257507324,
"catalog": "catalog3",
"category": "tees",
"gender": "female",
"view": null,
"age_group": null,
"related_matches_id": null
},
"catalog": {
"_type": "Catalog",
"_id": "5de96225cce3a80031e3c875",
"name": "catalog3"
},
"images": [
{
"_type": "Image",
"_id": null,
"uri": "https://product-3.jpg",
"width": 300,
"height": 375
}
],
"data": {
"id": "847941004700",
"sku": "3082046",
"name": "Product3",
"url": "https://product_webite.html",
"color": "jet black",
"category": "Women",
"gender": "female",
"age_group": "adults",
"stock": true,
"price": 29,
"brand": "Ingrid & Isabel",
"currency": "USD"
},
"created_at": "2019-12-10T17:56:55.811Z",
"updated_at": "2019-12-11T20:43:18.609Z"
}
]
}
]
}
]
}
Search a video - detect and retreive products based on visual features/similarity.
HTTP Request
POST https://video.markable.ai/video/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
| Parameter | Type | Description |
|---|---|---|
page |
integer | Default value is 0 |
pageLimit |
integer | Frame results per page. Default value is 5 |
Body
| Attribute | Type | Description |
|---|---|---|
data |
VideoSearchQuery | A valid video search object. |
Video Constraints
We have constraints on video we search on.
- We support static video