NAV
cURL Python Node JavaScript

Introduction

Welcome to Lykdat Business API documentation. Our API gives you access to running Image searches against your own product catalog and our very own product catalog database.

Here's a typical flow of the order of steps to follow when reading this documentation.

  1. Create a Lykdat Business Account (If you haven't already). Ensure to verify your account via the verification email sent to you.
  2. Prepare your catalog import file
  3. Create your first Catalog, using the import file you created above
  4. Retrieve your API key
  5. Start using the API

Authentication

The Lykdat Business API uses API keys to allow users make requests to its URL endpoints. You will need to create a business account to have access to your unique API Key.

Once your API key is generated, you can then pass it to the body of your API requests as the field api_key. Please see the /search endpoint section for examples

Getting an API Key

After signing into you business account, navigate to the Settings > General page to get your api key. Click the Show button under the API key section, then click the Copy button to copy it.

Search API

With the Search API, you can execute image searches to search for apparel products from your product catalogs. The product catalogs you want to from ought to have been created with your account in the business account console`

Once you've created a catalog, you can now make requests to the Search API.

The base URL to the Search API is: https://cloudapi.lykdat.com/v1

The URL path to the search endpoint against your product catalog is: /search

The https://cloudapi.lykdat.com/v1/search endpoint only accepts POST requests.

Using the /search endpoint.

To make use of the /search endpoint, you have to make a POST request to https://cloudapi.lykdat.com/v1/search with the following fields as form data:

Parameters Description Required
api_key A unique code to enable you make a request to the /search endpoint. true
catalog_name The name of the product catalog you wish to search from. true
image An image file. Optional
image_url If you don't have an image file to search with, you can provide a URL to the image you wish to search with. This image URL must be publicly accessible on the internet. Optional

The variables api_key, catalog_name are both required. However, you can either send along the binary of your image via the image field, or send the public URL of your image via the image_url field.

Search with an image URL.

# using curl
  curl -X POST https://cloudapi.lykdat.com/v1/search
   -d "api_key=de1ba0c4eeb07bea7edcd0675fd167a2c10db850567ae94a14d974033571d76d&catalog_name=Summer collections&image_url=https://cdn.shopify.com/s/files/1/0293/9277/products/image.jpg"
# using python
import requests

url = "https://cloudapi.lykdat.com/v1/search"
payload = {
    "api_key": "de1ba0c4eeb07bea7edcd0675fd167a2c10db850567ae94a14d974033571d76d" , 
    "catalog_name": "Summer collections", 
    "image_url": "https://cdn.shopify.com/s/files/1/0293/9277/products/image.jpg"
}

response = requests.post(url, data=payload)
print(response.content)
// Using Javascript in browser
  var formdata = new FormData();
  formdata.append("api_key", "de1ba0c4eeb07bea7edcd0675fd167a2c10db850567ae94a14d974033571d76d");
  formdata.append("catalog_name", "Summer collections");
  formdata.append("image_url", "https://cdn.shopify.com/s/files/1/0293/9277/products/image.jpg");

  var requestOptions = {
    method: 'POST',
    body: formdata,
  };

  fetch("https://cloudapi.lykdat.com/v1/search", requestOptions)
    .then(response => response.text())
    .then(result => console.log(result))
    .catch(error => console.log('error', error));
// using nodejs
var axios = require('axios');
var FormData = require('form-data');
var data = new FormData();
data.append('api_key', 'de1ba0c4eeb07bea7edcd0675fd167a2c10db850567ae94a14d974033571d76d');
data.append('catalog_name', 'Summer collections');
data.append('image_url', 'https://cdn.shopify.com/s/files/1/0293/9277/products/image.jpg');

var config = {
  method: 'post',
  url: "https://cloudapi.lykdat.com/v1/search",
  data : data
};

axios(config)
.then(function (response) {
  console.log(JSON.stringify(response.data));
})
.catch(function (error) {
  console.log(error);
});
{
    "data": {
        "query_image": "https://storage.googleapis.com/bacillus/searchuploads/1627283491459559/092015ff64e27df92cf532967d512136",
        "result_groups": [
            {
                "average_score": 0.71673858,
                "detected_item": {
                    "area": 0.179244154135734,
                    "bouding_box": {
                        "bottom": 0.36405572,
                        "left": 0.2991862,
                        "right": 0.808006,
                        "top": 0.71633005
                    },
                    "detection_confidence": 0.9378656,
                    "name": "Swimwear"
                },
                "max_score": 2.15021574,
                "rank_score": 0.38541360152564136,
                "similar_products": [
                    {
                        "brand_name": "M&S",
                        "category": null,
                        "currency": "USD",
                        "gender": "female",
                        "id": "946c8fb8-2049-4bc3-b9a3-8f527c507379__CLO-29473856-2",
                        "images": {
                            "aHR0cHM6Ly9jZG4uc2hvcGlmeS5jb20vcy9maWxlcy8xLzAyOTMvOTI3Ny9wcm9kdWN0cy9GYXNoaW9uX05vdmFfMTEtMTYtMTctNTg4LkpQRz92PTE1NzE0MzgxMzk=": "https://storage.googleapis.com/bacillus/productimages/946c8fb8-2049-4bc3-b9a3-8f527c507379__CLO-29473856-2/ova_11-16-17-588.JPG"
                        },
                        "matching_image": "https://cdn.shopify.com/s/files/1/0293/9277/products/image.jpg",
                        "name": "Roma Cotton Rich Bootcut Jeans - Size 8 Tall",
                        "price": "29.5",
                        "reduced_price": null,
                        "score": 0.99582064,
                        "sub_category": null,
                        "url": "http://www.example.com/clothing/women/Roma-Cotton-Bootcut-Jeans/?extid=CLO-29473856",
                        "vendor": null
                    }
                ]
            }
        ]
    }
}

For you to search with an image URL you have to make a POST request to https://cloudapi.lykdat.com/v1/search with the following variables as form data:

POST https://cloudapi.lykdat.com/v1/search

Parameters Description Required
api_key A unique code to enable you make a request to the /search endpoint. true
catalog_name The name of the product catalog you wish to search from. true
image_url You don't have a image file to search with? fine you can provide a link to the image you wish to search for. true

Search with an image.

import requests

url = "https://cloudapi.lykdat.com/v1/search"
payload = {
    "api_key": "de1ba0c4eeb07bea7edcd0675fd167a2c10db850567ae94a14d974033571d76d" , 
    "catalog_name": "Summer collections", 
}
image_file = open('path/to/image.jpg', 'rb')

files=[
  ('image',('image.jpg', image_file, 'image/jpeg'))
]

response = requests.post(url, data=payload, files=files)
print(response.content)

// nodejs
var axios = require('axios');
var fs = require('fs')
var FormData = require('form-data');
var data = new FormData();
data.append('api_key', 'de1ba0c4eeb07bea7edcd0675fd167a2c10db850567ae94a14d974033571d76d');
data.append('catalog_name', 'Summer collections');
data.append('image', fs.createReadStream('image.jpg'));

var config = {
  method: 'post',
  url: "https://cloudapi.lykdat.com/v1/search",
  data : data
};

axios(config)
.then(function (response) {
  console.log(JSON.stringify(response.data));
})
.catch(function (error) {
  console.log(error);
});

The above command returns JSON structured like this:

{
    "data": {
        "query_image": "https://storage.googleapis.com/bacillus/searchuploads/1627283491459559/092015ff64e27df92cf532967d512136",
        "result_groups": [
            {
                "average_score": 0.71673858,
                "detected_item": {
                    "area": 0.179244154135734,
                    "bouding_box": {
                        "bottom": 0.36405572,
                        "left": 0.2991862,
                        "right": 0.808006,
                        "top": 0.71633005
                    },
                    "detection_confidence": 0.9378656,
                    "name": "Swimwear"
                },
                "max_score": 2.15021574,
                "rank_score": 0.38541360152564136,
                "similar_products": [
                    {
                        "brand_name": "M&S",
                        "category": null,
                        "currency": "USD",
                        "gender": "female",
                        "id": "946c8fb8-2049-4bc3-b9a3-8f527c507379__CLO-29473856-2",
                        "images": {
                            "aHR0cHM6Ly9jZG4uc2hvcGlmeS5jb20vcy9maWxlcy8xLzAyOTMvOTI3Ny9wcm9kdWN0cy9GYXNoaW9uX05vdmFfMTEtMTYtMTctNTg4LkpQRz92PTE1NzE0MzgxMzk=": "https://storage.googleapis.com/bacillus/productimages/946c8fb8-2049-4bc3-b9a3-8f527c507379__CLO-29473856-2/ova_11-16-17-588.JPG"
                        },
                        "matching_image": "https://cdn.shopify.com/s/files/1/0293/9277/products/image.jpg",
                        "name": "Roma Cotton Rich Bootcut Jeans - Size 8 Tall",
                        "price": "29.5",
                        "reduced_price": null,
                        "score": 0.99582064,
                        "sub_category": null,
                        "url": "http://www.example.com/clothing/women/Roma-Cotton-Bootcut-Jeans/?extid=CLO-29473856",
                        "vendor": null
                    }
                ]
            }
        ]
    }
}

For you to search with an image file you have to make a POST request to https://cloudapi.lykdat.com/v1/search with the following variables as form data:

POST https://cloudapi.lykdat.com/v1/search

Parameters Description Required
api_key A unique code to enable you make a request to the /search endpoint. true
catalog_name The name of the catalog you wish to make a search request to. true
image An image file. true

Using Postman

Global Search API

With the Global Search API, you can execute image searches to search for apparel products from LykDat's product catalogs without the need to create your own catalog.

The base URL to the Search API is: https://cloudapi.lykdat.com/v1

The URL path to the global search endpoint aganist LykDat's product catalog is: /global/search

The https://cloudapi.lykdat.com/v1/global/search endpoint only accepts POST requests.

Using /global/search endpoint.

To make use of the /global/search endpoint, you have to make a POST request to https://cloudapi.lykdat.com/v1/global/search with the following fields as form data:

Parameters Description Required
api_key A unique code to enable you make a request to the /global/search endpoint. true
image An image file. Optional
image_url If you don't have an image file to search with, you can provide a URL to the image you wish to search with. This image URL must be publicly accessible on the internet. Optional

The api_key field is required, while the image and image_url is optional.

Search with an image URL.

# using curl
  curl -X POST https://cloudapi.lykdat.com/v1/global/search
   -d "api_key=de1ba0c4eeb07bea7edcd0675fd167a2c10db850567ae94a14d974033571d76d&image_url=https://cdn.shopify.com/s/files/1/0293/9277/products/image.jpg"
# using python
import requests

url = "https://cloudapi.lykdat.com/v1/global/search"
payload = {
    "api_key": "de1ba0c4eeb07bea7edcd0675fd167a2c10db850567ae94a14d974033571d76d" , 
    "image_url": "https://cdn.shopify.com/s/files/1/0293/9277/products/image.jpg"
}

response = requests.post(url, data=payload)
print(response.content)
// Using Javascript in browser
  var formdata = new FormData();
  formdata.append("api_key", "de1ba0c4eeb07bea7edcd0675fd167a2c10db850567ae94a14d974033571d76d");
  formdata.append("image_url", "https://cdn.shopify.com/s/files/1/0293/9277/products/image.jpg");

  var requestOptions = {
    method: 'POST',
    body: formdata,
  };

  fetch("https://cloudapi.lykdat.com/v1/global/search", requestOptions)
    .then(response => response.text())
    .then(result => console.log(result))
    .catch(error => console.log('error', error));
// using nodejs
var axios = require('axios');
var FormData = require('form-data');
var data = new FormData();
data.append('api_key', 'de1ba0c4eeb07bea7edcd0675fd167a2c10db850567ae94a14d974033571d76d');
data.append('image_url', 'https://cdn.shopify.com/s/files/1/0293/9277/products/image.jpg');

var config = {
  method: 'post',
  url: "https://cloudapi.lykdat.com/v1/global/search",
  data : data
};

axios(config)
.then(function (response) {
  console.log(JSON.stringify(response.data));
})
.catch(function (error) {
  console.log(error);
});
{
    "data": {
        "query_image": "https://storage.googleapis.com/bacillus/searchuploads/1627283491459559/092015ff64e27df92cf532967d512136",
        "result_groups": [
            {
                "average_score": 0.71673858,
                "detected_item": {
                    "area": 0.179244154135734,
                    "bouding_box": {
                        "bottom": 0.36405572,
                        "left": 0.2991862,
                        "right": 0.808006,
                        "top": 0.71633005
                    },
                    "detection_confidence": 0.9378656,
                    "name": "Swimwear"
                },
                "max_score": 2.15021574,
                "rank_score": 0.38541360152564136,
                "similar_products": [
                    {
                        "brand_name": "M&S",
                        "category": null,
                        "currency": "USD",
                        "gender": "female",
                        "id": "946c8fb8-2049-4bc3-b9a3-8f527c507379__CLO-29473856-2",
                        "images": {
                            "aHR0cHM6Ly9jZG4uc2hvcGlmeS5jb20vcy9maWxlcy8xLzAyOTMvOTI3Ny9wcm9kdWN0cy9GYXNoaW9uX05vdmFfMTEtMTYtMTctNTg4LkpQRz92PTE1NzE0MzgxMzk=": "https://storage.googleapis.com/bacillus/productimages/946c8fb8-2049-4bc3-b9a3-8f527c507379__CLO-29473856-2/ova_11-16-17-588.JPG"
                        },
                        "matching_image": "https://cdn.shopify.com/s/files/1/0293/9277/products/image.jpg",
                        "name": "Roma Cotton Rich Bootcut Jeans - Size 8 Tall",
                        "price": "29.5",
                        "reduced_price": null,
                        "score": 0.99582064,
                        "sub_category": null,
                        "url": "http://www.example.com/clothing/women/Roma-Cotton-Bootcut-Jeans/?extid=CLO-29473856",
                        "vendor": null
                    }
                ]
            }
        ]
    }
}

For you to search with an image URL you have to make a POST request to https://cloudapi.lykdat.com/v1/global/search with the following variables as form data:

POST https://cloudapi.lykdat.com/v1/global/search

Parameters Description Required
api_key A unique code to enable you make a request to the /search endpoint. true
image_url If you don't have an image file to search with, you can provide a URL to the image you wish to search with. This image URL must be publicly accessible on the internet. true

Search with an image.

import requests

url = "https://cloudapi.lykdat.com/v1/globalsearch"
payload = {
    "api_key": "de1ba0c4eeb07bea7edcd0675fd167a2c10db850567ae94a14d974033571d76d"
}
image_file = open('path/to/image.jpg', 'rb')

files=[
  ('image',('image.jpg', image_file, 'image/jpeg'))
]

response = requests.post(url, data=payload, files=files)
print(response.content)

// nodejs
var axios = require('axios');
var fs = require('fs')
var FormData = require('form-data');
var data = new FormData();
data.append('api_key', 'de1ba0c4eeb07bea7edcd0675fd167a2c10db850567ae94a14d974033571d76d');
data.append('image', fs.createReadStream('image.jpg'));

var config = {
  method: 'post',
  url: "https://cloudapi.lykdat.com/v1/global/search",
  data : data
};

axios(config)
.then(function (response) {
  console.log(JSON.stringify(response.data));
})
.catch(function (error) {
  console.log(error);
});

The above command returns JSON structured like this:

{
    "data": {
        "query_image": "https://storage.googleapis.com/bacillus/searchuploads/1627283491459559/092015ff64e27df92cf532967d512136",
        "result_groups": [
            {
                "average_score": 0.71673858,
                "detected_item": {
                    "area": 0.179244154135734,
                    "bouding_box": {
                        "bottom": 0.36405572,
                        "left": 0.2991862,
                        "right": 0.808006,
                        "top": 0.71633005
                    },
                    "detection_confidence": 0.9378656,
                    "name": "Swimwear"
                },
                "max_score": 2.15021574,
                "rank_score": 0.38541360152564136,
                "similar_products": [
                    {
                        "brand_name": "M&S",
                        "category": null,
                        "currency": "USD",
                        "gender": "female",
                        "id": "946c8fb8-2049-4bc3-b9a3-8f527c507379__CLO-29473856-2",
                        "images": {
                            "aHR0cHM6Ly9jZG4uc2hvcGlmeS5jb20vcy9maWxlcy8xLzAyOTMvOTI3Ny9wcm9kdWN0cy9GYXNoaW9uX05vdmFfMTEtMTYtMTctNTg4LkpQRz92PTE1NzE0MzgxMzk=": "https://storage.googleapis.com/bacillus/productimages/946c8fb8-2049-4bc3-b9a3-8f527c507379__CLO-29473856-2/ova_11-16-17-588.JPG"
                        },
                        "matching_image": "https://cdn.shopify.com/s/files/1/0293/9277/products/image.jpg",
                        "name": "Roma Cotton Rich Bootcut Jeans - Size 8 Tall",
                        "price": "29.5",
                        "reduced_price": null,
                        "score": 0.99582064,
                        "sub_category": null,
                        "url": "http://www.example.com/clothing/women/Roma-Cotton-Bootcut-Jeans/?extid=CLO-29473856",
                        "vendor": null
                    }
                ]
            }
        ]
    }
}

For you to search with an image file you have to make a POST request to https://cloudapi.lykdat.com/v1/global/search with the following variables as form data:

POST https://cloudapi.lykdat.com/v1/global/search

Parameters Description Required
api_key A unique code to enable you make a request to the /search endpoint. true
image An image file. true

Errors

The LykDat API /search endpoint may return any of the following error responses depending on the reason for failure:

Status Code Error Message Meaning
400 api key is missing Bad Request -- You didn't provide the API KEY.
400 image and image URL is missing Bad Request -- No Image file or Image url provided
400 invalid API Key or catalog name supplied Bad Request -- Wrong API Key or catalog name
500 Error occurred while executing search Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- Our server is simply not available. Most of the time, it occurs because the server is too busy or because there's maintenance being performed on it.

Catalog Import Files

In order to create a catalog, you are required to upload a catalog import file. The import file is essentially a file containing all the products you would like to add to your catalog. This import file can either be a csv file or a tsv file.

Your Import file is required to contain a specific set of fields in order to be successfully imported into Lykdat's vision engine. The table below specifies the said fields:

Note - If your import file already follows google's product data specification then it is most likely fit for import.

Fileds Required Meaning Examples
id True A unique identifier for your product. unique-2742983-id, AA187G0288U35
title True The name of the product. Summer pant
link True the URL of the product https://www.your-web-page.com/g/women/summer_pants
image_link True An image URL to your product image itself. https://link-to-your-image.com/image.jpg
availability True Is your product available or out of stock. out of stock, in stock
price True Price for your product. 455 USD, 648 USD
sale_price False Discount price of a product in the case where it's on sale 20 USD, 10 USD
gender True Gender specification. male, female, unisex
size True The product's size. large, medium, small, XL, L, M, etc.

Once you are done preparing your import file, you can create a catalog and upload your prepared file.