productAI

Product Search

Product Set

Each data item in the data set contains all information of a product. E.g.: product name, description, price, type and pictures. When a new product set is created, a unique id will be assigned, called PRODUCT_SET_ID.

Create Product Set

Python

PHP

Java

cURL

from productai import Client

cli = Client(ACCESS_KEY_ID, SECRET_KEY)
api = cli.get_product_set_api()
resp = api.create_product_set(name=SET_NAME, description=SET_DESC)
use  ProductAI\Api;

$product_ai = new ProductAI\Api\ProductSetApi($access_key_id=ACCESS_KEY_ID, $secret_key=SECRET_KEY);
$result = $product_ai->createProductSet($name=SET_NAME,['description'=>'SET_DESC']);
$product_set_id = $result['id'];
import cn.productai.api.core.*;
import cn.productai.api.core.enums.*;
import cn.productai.api.pai.entity.productset.*;

// Set initial parameters for API calling
IProfile profile = new DefaultProfile();
profile.setAccessKeyId(ACCESS_KEY_ID);
profile.setSecretKey(SECRET_KEY);
profile.setVersion("1");

// Set name and description for the product set
IWebClient client = new DefaultProductAIClient(profile);
CreateProductSetRequest request = new CreateProductSetRequest(SET_NAME, SET_DESC);

// Call API and get the response
CreateProductSetResponse response = client.getResponse(request);
// Get ID of the product set
String prod_set_id = response.getId();
// Get all data containing in the response
//String json = response.getResponseJsonString();
curl -X POST \
-H 'x-ca-version: 1.0' \
-H 'x-ca-accesskeyid: ACCESS_KEY_ID' \
-H 'Content-Type: application/json' \
-d '{"name": "NAME", "description": "DESCRIPTION"}' \
https://api.productai.cn/product_sets/_0000178

Request

ArgumentTypeDescriptionRequiredLimitation
nameStringProduct set nameRequiredMaximum 16 Unicode characters, extra characters will be truncated
descriptionStringProduct set descriptionRequiredMaximum 128 Unicode characters, extra characters will be truncated

Response

200 HTTP Status Code
{
"created_at" : "2018-03-26T06:30:49Z",
"creator_id" : ...,
"description" : "ProductDESC",
"id" : "y70vjzt6",
"image_set_id" : "fvh589ei",
"modified_at" : "2018-03-26T06:30:49Z",
"name" : "ProductNAME",
"request_id" : "42fdb742-3187-11e8-96f1-024a21e9e3e6",
"status" : "not-downloaded"
}
FieldTypeDescription
created_atStringCreated UTC datetime, the format is: %Y-%m-%dT%H:%M:%SZ
creator_idIntegerCreator ID
descriptionStringProduct set description
idStringUnique ID, all the product set related APIs will use this ID to identify a product set
image_set_idStringUnique image set ID which bonding with the product set
modified_atStringLast modified UTC datetime, the format is: %Y-%m-%dT%H:%M:%SZ
nameStringProduct set name
request_idStringThe unique ID of this request, it can be used in product issue debugging with ProductAI support team
statusStringCurrent status of the product set
Non-200 HTTP Status Code
{
"error_code": 5001,
"message": "lineno 1 : `` should be a valid image URL less than or equal to 512 characters in length",
"request_id": "810c0180-e00e-11e7-9a0f-b217471bc47d"
}
FieldTypeDescription
error_codeIntegerDetailed error code
messageStringDetailed error message
request_idStringThe unique ID of this request, it can be used in product issue debugging with ProductAI support team

Error Code

SDK/API notifies the client about whether the request success or fails via HTTP status code

Http Status Codeerror_codeDescription
200N/aProduct set created successfully
4001007Product set name is not provided

List All Product Sets

Python

PHP

Java

cURL

from productai import Client

cli = Client(ACCESS_KEY_ID, SECRET_KEY)
api = cli.get_product_set_api()
resp = api.get_product_sets()
use  ProductAI\Api;

$product_ai = new ProductAI\Api\ProductSetApi($access_key_id=ACCESS_KEY_ID, $secret_key=SECRET_KEY);
$result = $product_ai->listProductSets();
import cn.productai.api.core.*;
import cn.productai.api.core.enums.*;
import cn.productai.api.pai.entity.productset.*;

// Set initial parameters for API calling
IProfile profile = new DefaultProfile();
profile.setAccessKeyId(ACCESS_KEY_ID);
profile.setSecretKey(SECRET_KEY);
profile.setVersion("1");

// Create request for getting all product sets data
IWebClient client = new DefaultProductAIClient(profile);
GetAllProductSetsRequest request = new GetAllProductSetsRequest();

// Call API and get the response
GetAllProductSetsResponse response = client.getResponse(request);
String json = response.getResponseJsonString();
curl -X GET \
-H 'x-ca-version: 1.0' \
-H 'x-ca-accesskeyid: ACCESS_KEY_ID' \
https://api.productai.cn/product_sets/_0000178

Request

N/a

Response

200 HTTP Status Code
{
"request_id": "a05da544-0f9c-11e8-8f9b-0242ac120103",
"results": [
{
"created_at" : "2018-03-27T03:51:57Z",
"creator_id" : ...,
"description" : "This is my product set of fashion images.",
"id" : "28m1h3v9",
"image_set_id" : "b9r44tn5",
"modified_at" : "2018-03-27T03:51:57Z",
"name" : "My Product Set",
"status" : "not-downloaded"
},
...
]
}
FieldTypeDescription
resultsArrayAll the existing product sets, the fields of single item in array is same as Create Product Set Response
request_idStringThe unique ID of this request, it can be used in product issue debugging with ProductAI support team

Error Code

SDK/API notifies the client about whether the request success or fails via HTTP status code

HTTP Status Codeerror_codeDescription
200N/aList product sets successfully

Fetch a Single Product Set

Python

PHP

Java

cURL

from productai import Client

cli = Client(ACCESS_KEY_ID, SECRET_KEY)
api = cli.get_product_set_api(product_set_id=PRODUCT_SET_ID)
resp = api.get_product_set()
use  ProductAI\Api;

$product_ai = new ProductAI\Api\ProductSetApi($access_key_id=ACCESS_KEY_ID, $secret_key=SECRET_KEY);
$result = $product_ai->getProductSet($productSetID=PRODUCT_SET_ID);
import cn.productai.api.core.*;
import cn.productai.api.core.enums.*;
import cn.productai.api.pai.entity.productset.*;

// Set initial parameters for API calling
IProfile profile = new DefaultProfile();
profile.setAccessKeyId(ACCESS_KEY_ID);
profile.setSecretKey(SECRET_KEY);
profile.setVersion("1");

// Create request for getting a product set data
IWebClient client = new DefaultProductAIClient(profile);
GetProductSetRequest request = new GetProductSetRequest(PRODUCT_SET_ID);

// Call API and get the response
GetProductSetResponse response = client.getResponse(request);
String json = response.getResponseJsonString();
curl -X GET \
-H 'x-ca-version: 1.0' \
-H 'x-ca-accesskeyid: ACCESS_KEY_ID' \
https://api.productai.cn/product_sets/_0000178/PRODUCT_SET_ID

Request

N/a

Response

Same as Create Product Set Response

Error Code

SDK/API notifies the client about whether the request success or fail via HTTP status code

HTTP Status Codeerror_codeDescription
200N/aFetch the product set successfully
4031005Authentication failure
4041004Product set doesn’t exist

Modify Image Set

Python

PHP

Java

cURL

from productai import Client

cli = Client(ACCESS_KEY_ID, SECRET_KEY)
api = cli.get_product_set_api(product_set_id=PRODUCT_SET_ID)
resp = api.update_product_set(name=SET_NAME, description=NEW_DESC)
use  ProductAI\Api;

$product_ai = new ProductAI\Api\ProductSetApi($access_key_id=ACCESS_KEY_ID, $secret_key=SECRET_KEY);
$result = $product_ai->updateProductSet($productSetID=PRODUCT_SET_ID, ['name'=>'NEW_NAME','description'=>'NEW_DESC']);
import cn.productai.api.core.*;
import cn.productai.api.core.enums.*;
import cn.productai.api.pai.entity.productset.*;

IProfile profile = new DefaultProfile();
profile.setAccessKeyId(ACCESS_KEY_ID);
profile.setSecretKey(SECRET_KEY);
profile.setVersion("1");

IWebClient client = new DefaultProductAIClient(profile);
UpdateProductSetRequest request = new UpdateProductSetRequest(PRODUCT_SET_ID, NEW_NAME, NEW_DESC);

UpdateProductSetResponse response = client.getResponse(request);
String json = response.getResponseJsonString();
curl -X POST \
-H 'x-ca-version: 1.0' \
-H 'x-ca-accesskeyid: ACCESS_KEY_ID' \
-H 'Content-Type: application/json' \
-d '{"name": "NEW_NAME", "description": "NEW_DESC"}' \
https://api.productai.cn/product_sets/_0000178/PRODUCT_SET_ID

Request

Same as Create Product Set Request

Response

Same as Create Product Set Response

Error Code

SDK/API notifies the client about whether the request success or fail via HTTP status code

HTTP Status Codeerror_codeDescription
200N/aModify product set successfully
4001007Empty product set name is not allowed
4031005Authentication failure
4041004Product set doesn’t exist

Delete Product Set

Python

PHP

Java

cURL

from productai import Client

cli = Client(ACCESS_KEY_ID, SECRET_KEY)
api = cli.get_product_set_api(product_set_id=PRODUCT_SET_ID)
resp = api.delete_product_set()
use  ProductAI\Api;

$product_ai = new ProductAI\Api\ProductSetApi($access_key_id=ACCESS_KEY_ID, $secret_key=SECRET_KEY);
$result = $product_ai->deleteProductSet($productSetID=PRODUCT_SET_ID);
import cn.productai.api.core.*;
import cn.productai.api.core.enums.*;
import cn.productai.api.pai.entity.productset.*;

IProfile profile = new DefaultProfile();
profile.setAccessKeyId(ACCESS_KEY_ID);
profile.setSecretKey(SECRET_KEY);
profile.setVersion("1");

IWebClient client = new DefaultProductAIClient(profile);
DeleteProductSetRequest request = new DeleteProductSetRequest(PRODUCT_SET_ID);

DeleteProductSetResponse response = client.getResponse(request);
curl -X DELETE \
-H 'x-ca-accesskeyid:ACCESS_KEY_ID' \
https://api.productai.cn/product_sets/_0000178/PRODUCT_SET_ID

Request

N/a

Response

N/a

Error Code

SDK/API notifies the client about whether the request success or fail via HTTP status code

HTTP Status Codeerror_codeDescription
204N/aDelete product set successfully
4031005Authentication failed
5002002Delete product set
4041004Product set doesn’t exist

Data

Add Single Data to Product Set

Python

PHP

Java

cURL

from productai import Client

cli = Client(ACCESS_KEY_ID, SECRET_KEY)
api = cli.get_product_set_api(product_set_id=PRODUCT_SET_ID)
resp = api.add_product(
product_id='_001',
price=10000.0,
keywords='Black Nordic style Fabric Sofa',
image_url='http://xxxx.jpg',
meta=None,
tags=None)
use  ProductAI\Api;

$product_ai = new ProductAI\Api\ProductSetApi($access_key_id=ACCESS_KEY_ID, $secret_key=SECRET_KEY);
$result = $product_ai->addProductToProductSet(
$productSetID=PRODUCT_SET_ID,
$productID= '_001',
$imageUrl='http://xxxx.jpg',
$args = [
'price'=>10000.0,
'keywords'=>'Black Nordic style Fabric Sofa']);
import cn.productai.api.core.*;
import cn.productai.api.core.enums.*;
import cn.productai.api.pai.entity.productset.*;

IProfile profile = new DefaultProfile();
profile.setAccessKeyId(ACCESS_KEY_ID);
profile.setSecretKey(SECRET_KEY);
profile.setVersion("1");

IWebClient client = new DefaultProductAIClient(profile);

String productId = "_001";
String price = "2000";
String keywords = "Black Nordic style Fabric Sofa";
String imageUrl = "http://yyyy.jpg";

AddProductRequest request = new AddProductRequest(
PRODUCT_SET_ID, productId, price, keywords, imageUrl, null, null);
String json = client.getResponse(request).getResponseJsonString();
curl -X POST \
-H 'x-ca-version: 1.0' \
-H 'x-ca-accesskeyid: ACCESS_KEY_ID' \
-H 'Content-Type: application/json' \
-d '{"image_url":"https://xxxx.jpg","keywords":"Black Nordic style Fabric Sofa","price":"2000","product_id":"_001"}' \
https://api.productai.cn/product_sets/_0000178/PRODUCT_SET_ID/products

Request

ArgumentTypeDescriptionRequiredLimitation
productIdStringProduct IDRequiredThe unique ID of the product
priceStringProduct priceNot RequiredThe product price, see min_price and max_price
keywordsStringProduct keywordsNot RequiredKeywords related to the product, see Keywords
urlStringURL for uploading imageRequiredMaximum 512 unicode characters, will raise an error if length exceeds this limit

Response

{
"ok" : true,
"request_id" : "7ca8d6cc-319e-11e8-92d3-b28616b7eea5"
}
ArgumentTypeDescription
okBooleanTrue means adding data into the product set successfully, false means failure in adding data
request_idStringThe unique ID of this request, it can be used in product issue debugging with ProductAI support team

Error Code

SDK/API notifies the client about whether the request success or fails via HTTP status code

HTTP Status Codeerror_codeDescription
200N/aUpload data successfully
4041004Product set doesn’t exist

Add Multiple Data to Product Set or Modify Product Data

This method uses Upsert logic. If the product ID already exist in the database, just update all attributes of the product, no new record will be added. The file uploaded should be a text file, and every item of the file should be JSON format, please refer to batch data modification example. JSON format item can include following arguments:

ArgumentTypeDescriptionRequiredLimitation
product_idStringProduct IDRequiredThe unique ID of the product. A same product_id corresponds to multiple images, see A product with multiple images
priceStringProduct priceNot RequiredThe product price, see min_price and max_price
keywordsStringProduct keywordsNot RequiredKeywords related to the product, see Keywords
urlStringURL for uploading imageRequiredMaximum 512 unicode characters, will raise an error if length exceeds this limit

Python

PHP

Java

cURL

from productai import Client

cli = Client(ACCESS_KEY_ID, SECRET_KEY)
api = cli.get_product_set_api(product_set_id=PRODUCT_SET_ID)
with open('./batch_modify_products.json') as f:
resp = api.add_products_in_bulk(f)
use ProductAI\Api;

$product_ai = new ProductAI\Api\ProductSetApi($access_key_id=ACCESS_KEY_ID, $secret_key=SECRET_KEY);
$result = $product_ai->addProductsToProductSet($productSetID=PRODUCT_SET_ID, $products='./batch_modify_products.json');
import cn.productai.api.core.*;
import cn.productai.api.core.enums.*;
import cn.productai.api.pai.entity.productset.*;

IProfile profile = new DefaultProfile();
profile.setAccessKeyId(ACCESS_KEY_ID);
profile.setSecretKey(SECRET_KEY);
profile.setVersion("1");

IWebClient client = new DefaultProductAIClient(profile);

AddProductsBatchRequest request = new AddProductsBatchRequest(PRODUCT_SET_ID);
request.setCsvFile(new File("./batch_modify_products.json"));

AddProductsBatchResponse response = client.getResponse(request);
String json = response.getResponseJsonString()
curl -X POST \
-H 'x-ca-version: 1.0' \
-H 'x-ca-accesskeyid: ACCESS_KEY_ID' \
-F "products_to_add=@./batch_modify_products.json" \
https://api.productai.cn/product_sets/_0000178/PRODUCT_SET_ID/products

Request

ArgumentTypeDescriptionRequiredLimitation
products_to_addText fileText file content, for text file format please refer to batch data modification exampleRequiredShould be smaller than 50MB

Response

Same as Add Single Data to Product Set Response

Error Code

Same as Add Single Data to Product Set Error Code

Delete Multiple Data from Product Set

Python

PHP

Java

cURL

from productai import Client

cli = Client(ACCESS_KEY_ID, SECRET_KEY)
api = cli.get_product_set_api(product_set_id=PRODUCT_SET_ID)
with open('./batch_modify_products.json') as f:
resp = api.delete_products_in_bulk(f)
use ProductAI\Api;

$product_ai = new ProductAI\Api\ProductSetApi($access_key_id=ACCESS_KEY_ID, $secret_key=SECRET_KEY);
$result = $product_ai->deleteProductsFromProductSet($productSetID=PRODUCT_SET_ID, $products='./batch_modify_products.json');
import cn.productai.api.core.*;
import cn.productai.api.core.enums.*;
import cn.productai.api.pai.entity.productset.*;

IProfile profile = new DefaultProfile();
profile.setAccessKeyId(ACCESS_KEY_ID);
profile.setSecretKey(SECRET_KEY);
profile.setVersion("1");

IWebClient client = new DefaultProductAIClient(profile);

DeleteProductsRequest request = new DeleteProductsRequest(PRODUCT_SET_ID);
request.setCsvFile(new File("./batch_modify_products.json"));

DeleteProductsResponse response = client.getResponse(request);
String json = response.getResponseJsonString()
curl -X POST \
-H 'x-ca-version: 1.0' \
-H 'x-ca-accesskeyid: ACCESS_KEY_ID' \
-F "products_to_delete=@./batch_modify_products.json" \
https://api.productai.cn/product_sets/_0000178/PRODUCT_SET_ID/products

Request

ArgumentTypeDescriptionRequiredLimitation
products_to_deleteText fileText file content, for text file format please refer to batch data modification example, the “product_id“specifies the product need to be deletedRequiredShould be smaller than 50MB

Response

Same as Add Single Data to Product Set Response

Error Code

Same as Add Single Data to Product Set Error Code

Deleting Data by Product ID

Python

PHP

Java

cURL

from productai import Client

cli = Client(ACCESS_KEY_ID, SECRET_KEY)
api = cli.get_product_set_api(product_set_id=PRODUCT_SET_ID)
resp = api.delete_products(['id1', 'id2'])
use ProductAI\Api;

$product_ai = new ProductAI\Api\ProductSetApi($access_key_id=ACCESS_KEY_ID, $secret_key=SECRET_KEY);
$result = $product_ai->deleteProductsByID($productSetID=PRODUCT_SET_ID, $productIDs=['id1', 'id2']);
import cn.productai.api.core.*;
import cn.productai.api.core.enums.*;
import cn.productai.api.pai.entity.productset.*;

IProfile profile = new DefaultProfile();
profile.setAccessKeyId(ACCESS_KEY_ID);
profile.setSecretKey(SECRET_KEY);
profile.setVersion("1");

IWebClient client = new DefaultProductAIClient(profile);

DeleteProductsByProductSetRequest request = new DeleteProductsByProductSetRequest(PRODUCT_SET_ID, new String[]{"_001", "_002"});
DeleteProductsByProductSetResponse response = client.getResponse(request);
String json = response.getResponseJsonString();
curl -X DELETE \
-H 'x-ca-version: 1.0' \
-H 'x-ca-accesskeyid: ACCESS_KEY_ID' \
-H 'Content-Type: application/json' \
-d '{"ids":["_001","_002"]}' \
https://api.productai.cn//product_sets/_0000178/PRODUCT_SET_ID/products

Request

N/a

Response

N/a

Error Code

Same as Add Single Data to Product Set Error Code

Service Management

Create Search Service

Python

PHP

Java

cURL

from productai import Client

cli = Client(ACCESS_KEY_ID, SECRET_KEY)
api = cli.get_product_set_api(product_set_id=PRODUCT_SET_ID)
resp = api.create_service(name='test', scenario='material_v2')
use ProductAI\Api;

$product_ai = new ProductAI\Api\ProductSearchServiceApi($access_key_id=ACCESS_KEY_ID, $secret_key=SECRET_KEY);
$result = $product_ai->createService($productSetID=PRODUCT_SET_ID, $name='test', $scenario='material_v2');
import cn.productai.api.core.*;
import cn.productai.api.core.enums.*;
import cn.productai.api.pai.entity.productset.*;

IProfile profile = new DefaultProfile();
profile.setAccessKeyId(ACCESS_KEY_ID);
profile.setSecretKey(SECRET_KEY);
profile.setVersion("1");

IWebClient client = new DefaultProductAIClient(profile);

CreateServiceRequest request = new CreateServiceRequest(PRODUCT_SET_ID, SERVICE_NAME, SCENARIO_ID);

CreateServiceResponse response = client.getResponse(request);
String json = response.getResponseJsonString()
curl -X POST \
-H 'x-ca-version: 1.0' \
-H 'x-ca-accesskeyid: ACCESS_KEY_ID' \
-H 'Content-Type: application/json' \
-d '{"name": "NAME", "scenario": "material_v2"}' \
https://api.productai.cn/product_sets/_0000178/PRODUCT_SET_ID/services

Request

ArgumentTypeDescriptionRequiredLimitation
nameStringService nameRequiredMaximum 32 characters, extra characters will be truncated
scenarioStringScenario TypeRequiredMust be one of Supported Scenarios

Response

200 HTTP Status Code
{
"created_at" : "2018-03-28T06:20:52Z",
"creator_id" : ...,
"id" : "n4wh8fzx",
"image_set_id" : "ftvxj8s5",
"indexed_ratio" : 0,
"last_indexed_time" : null,
"last_updated_at" : null,
"n_indexed" : 0,
"name" : "product-service",
"request_id" : "29d7ed90-3250-11e8-963a-7e00c202692f",
"scenario" : "fashion_5_7",
"status" : "running",
"status_duration" : 0,
"type" : 1
}
FieldTypeDescription
created_atStringCreated UTC datetime, the format is:%Y-%m-%dT%H:%M:%SZ
creator_idIntegerCreator ID
idStringUnique ID of search service, all following operations are depending on this ID
image_set_idStringdataset ID which is used for current service
indexed_ratioFloatration = indexed image amount / downloaded image amount
last_indexed_timeStringLast index deployed time for this service
last_updated_atStringLast modified UTC time, to seconds, the format is: %Y-%m-%dT%H:%M:%SZ
n_indexedIntegerCurrent indexed amount
nameStringSearch service name
request_idStringThe unique ID of this request, it can be used in product issue debugging with ProductAI support team
scenarioStringScenario name
statusStringThe status of searching service, only support running currently
status_durationIntegerN/a
typeIntegerN/a
Non-200 HTTP Status Code
{
"error_code": 2003,
"message": "Failed to Create Service",
"request_id": "a0393714-e331-11e7-9a0f-b217471bc47d"
}
FieldTypeDescription
error_codeIntegerDetailed error code
messageStringDetailed error message
request_idStringThe unique ID of this request, it can be used in product issue debugging with ProductAI support team

Error Code

SDK/API notifies the client about whether the request success or fails via HTTP status code

HTTP Status Codeerror_codeDescription
200N/aSuccess
4002003Specified scenario does not exist

List All Search Services

Python

PHP

Java

cURL

from productai import Client

cli = Client(ACCESS_KEY_ID, SECRET_KEY)
api = cli.get_product_search_api()
resp = api.list_services()
use ProductAI\Api;

$product_ai = new ProductAI\Api\ProductSearchServiceApi($access_key_id=ACCESS_KEY_ID, $secret_key=SECRET_KEY);
$result = $product_ai->listServices();
import cn.productai.api.core.*;
import cn.productai.api.core.enums.*;
import cn.productai.apiv2.*;
import cn.productai.apiv2.impl.*;

IProfile profile = new DefaultProfile();
profile.setAccessKeyId(ACCESS_KEY_ID);
profile.setVersion("1");

ProductSearch productService = new ProductSearchImpl();
productService.setProfile(profile);

String result = productService.listAllService();
System.out.println(result);
curl -X GET \
-H 'x-ca-version: 1.0' \
-H 'x-ca-accesskeyid: ACCESS_KEY_ID' \
https://api.productai.cn/product_sets/_0000178/services

Request

N/A

Response

Python

{
"request_id": "edcb5b96-5aa6-11e8-8c3f-1a02c65827d9",
"services": [
{
"created_at": "2018-05-18T14:22:43Z",
"creator_id": ...,
"id": "hlrlcx06",
"image_set_id": "0w3ftsbl",
"indexed_ratio": 0,
"last_indexed_time": null,
"last_updated_at": null,
"n_indexed": 0,
"name": "prd_test",
"scenario": "material_v2",
"status": "running",
"status_duration": 0,
"type": 1
}
]
}
FieldTypeDescription
request_idStringThe unique ID of this request, it can be used in product issue debugging with ProductAI support team
servicesArrayList all customer’s running services, the field of single service is same as Create Search Service Response

Fetch Search Service

Python

PHP

Java

cURL

from productai import Client

cli = Client(ACCESS_KEY_ID, SECRET_KEY)
api = cli.get_product_search_api(SERVICE_ID)
resp = api.get_service()
use ProductAI\Api;

$product_ai = new ProductAI\Api\ProductSearchServiceApi($access_key_id=ACCESS_KEY_ID, $secret_key=SECRET_KEY);
$result = $product_ai->getService($serviceID=SERVICE_ID);
import cn.productai.api.core.*;
import cn.productai.api.core.enums.*;
import cn.productai.apiv2.*;
import cn.productai.apiv2.impl.*;

IProfile profile = new DefaultProfile();
profile.setAccessKeyId(ACCESS_KEY_ID);
profile.setVersion("1");

ProductSearch productService = new ProductSearchImpl();
productService.setProfile(profile);

String result = productService.getServiceById(SERVICE_ID);
System.out.println(result);
curl -X GET \
-H 'x-ca-version: 1.0' \
-H 'x-ca-accesskeyid: ACCESS_KEY_ID' \
https://api.productai.cn/product_sets/_0000178/services/SERVICE_ID

Request

N/A

Response

Same as List All Search Services Response

Error Code

SDK/API notifies the client about whether the request success or fails via HTTP status code

HTTP Status CodeDescription
200Fetch successfully
404Service doesn’t exist

Update Search Service Name

Python

PHP

Java

cURL

from productai import Client

cli = Client(ACCESS_KEY_ID, SECRET_KEY)
api = cli.get_product_search_api(SERVICE_ID)
resp = api.update_service(name='NEW_NAME')
use ProductAI\Api;

$product_ai = new ProductAI\Api\ProductSearchServiceApi($access_key_id=ACCESS_KEY_ID, $secret_key=SECRET_KEY);
$result = $product_ai->updateService($serviceID=SERVICE_ID, $args=["name"=>'NEW_NAME']);
import cn.productai.api.core.*;
import cn.productai.api.core.enums.*;
import cn.productai.apiv2.*;
import cn.productai.apiv2.impl.*;

IProfile profile = new DefaultProfile();
profile.setAccessKeyId(ACCESS_KEY_ID);
profile.setVersion("1");

ProductSearch productService = new ProductSearchImpl();
productService.setProfile(profile);

String result = productService.updateServiceName(SERVICE_ID, "NEW_NAME");
System.out.println(result);
curl -X PATCH \
-H 'x-ca-version: 1.0' \
-H 'x-ca-accesskeyid: ACCESS_KEY_ID' \
-H 'Content-Type: application/json' \
-d '{"name": "NEW_NAME"}' \
https://api.productai.cn/product_sets/_0000178/services/SERVICE_ID

Request

ArgumentTypeDescriptionRequiredLimitation
nameStringNew service nameRequiredMaximum 32 characters, extra characters will be truncated

Response

Same as Create Search Service Response

Error Code

SDK/API notifies the client about whether the request success or fails via HTTP status code

HTTP Status CodeDescription
200Update successfully
400Service name can’t be empty
404Service doesn’t exist

Delete Search Service

Python

PHP

Java

cURL

from productai import Client

cli = Client(ACCESS_KEY_ID, SECRET_KEY)
api = cli.get_product_search_api(SERVICE_ID)
resp = api.delete_service()
use ProductAI\Api;

$product_ai = new ProductAI\Api\ProductSearchServiceApi($access_key_id=ACCESS_KEY_ID, $secret_key=SECRET_KEY);
$result = $product_ai->deleteService($serviceID=SERVICE_ID);
import cn.productai.api.core.*;
import cn.productai.api.core.enums.*;
import cn.productai.apiv2.*;
import cn.productai.apiv2.impl.*;

IProfile profile = new DefaultProfile();
profile.setAccessKeyId(ACCESS_KEY_ID);
profile.setVersion("1");

ProductSearch productService = new ProductSearchImpl();
productService.setProfile(profile);

String result = productService.deleteServiceById(SERVICE_ID);
System.out.println(result);
curl -X DELETE \
-H 'x-ca-version: 1.0' \
-H 'x-ca-accesskeyid: ACCESS_KEY_ID' \
https://api.productai.cn/product_sets/_0000178/services/SERVICE_ID

Request

N/A

Response

N/A

Error Code

SDK/API notifies the client about whether the request success or fails via HTTP status code

HTTP Status CodeDescription
200Delete successfully
404Service doesn’t exist

Python

PHP

Java

cURL

from productai import Client

cli = Client(ACCESS_KEY_ID, SECRET_KEY)
api = cli.get_product_search_api(SERVICE_ID)

# Query by using URL of the image
resp = api.query(image='http://yyyy', loc='0.1-0.1-0.8-0.7')

# or query by uploading local image file
with open("zzzz.jpg", mode='rb') as search:
resp = api.query(
image=search,
count=2,
keywords='hello',
min_price=100,
max_price=5000)

# Query by using URL and tags to filter searching results.
resp = api.query(
image='http://yyyy',
count=2,
keywords='hello',
min_price=100,
max_price=5000)
use ProductAI\Api;

$product_ai = new PProductAI\Api\ProductSearchServiceApi($access_key_id=ACCESS_KEY_ID, $secret_key=SECRET_KEY);

// Query by using URL of the image
$result = $product_ai->search(
$service_id=SERVICE_ID,
$image='http://yyyy',
$options=[
"loc" => "0.5-0.1-0.1-0.5",
"count" => 10,
"min_price" => 100,
"max_price" => 5000,
"keywords" => "hello"
]);

// or query by uploading local image file
$result = $product_ai->search(
$service_id=SERVICE_ID,
$image='@./zzzz.jpg',
$options=[
"loc" => "0.5-0.1-0.1-0.5",
"count" => 10,
"min_price" => 100,
"max_price" => 5000,
"keywords" => "hello"
]);
import cn.productai.api.core.*;
import cn.productai.api.core.enums.*;
import cn.productai.apiv2.*;
import cn.productai.apiv2.impl.*;
import java.io.File;

IProfile profile = new DefaultProfile();
profile.setAccessKeyId(ACCESS_KEY_ID);
profile.setVersion("1");

ProductSearch productService = new ProductSearchImpl();
productService.setProfile(profile);

// Query by using URL of the image
String result = productService.query(
SERVICE_ID,
"http://yyyy",
"0-0-1-1",
20,
null,
"hello",
"100",
"5000",
null);

// or query by uploading local image file
String result = productService.query(
SERVICE_ID,
new File("zzzz.jpg"),
"0-0-1-1",
20,
null,
"hello",
"100",
"5000",
null);

System.out.println(result);
# Query by using URL of the image
curl -X POST \
-H 'x-ca-version: 1.0' \
-H 'x-ca-accesskeyid: ACCESS_KEY_ID' \
-H 'Content-Type: application/json' \
-d '{"url":"http://yyyy","count":"2","tags":{"and":["MALE","SHOES"]},"min_price":"100","max_price":"5000","keywords":"hello"}' \
https://api.productai.cn/product_search/SERVICE_ID

# or query by uploading local image file
curl -X POST \
-H 'x-ca-version: 1.0' \
-H 'x-ca-accesskeyid: ACCESS_KEY_ID' \
-F "search=@zzzz.jpg" \
-F "count=2" \
-F "min_price=100" \
-F "max_price=5000" \
-F "keywords=hello" \
https://api.productai.cn/product_search/SERVICE_ID

Request

ArgumentTypeDescriptionRequiredLimitation
imageString or FileImage url or image content for queryRequiredN/a
countIntegerSpecify result countNot Required20 by default, the value range is [1-3000], but should no more than 3000
min_priceFloatThe lower limit of product priceNot RequiredA positive number, see min_price and max_price
max_priceFloatThe upper limit of product priceNot RequiredA positive number and should be greater than min_price, see min_price and max_price
keywordsStringUsed in fuzzy search, see KeywordsNot RequiredN/a

Response

{
"detect_time": "0.000",
"detection_score": null,
"download_time": "0.381",
"ds": "e8ie3j2s",
"filter_time": 0.028,
"is_err": 0,
"labels": null,
"loc": [
0,
0,
316,
470
],
"most_common_tags": [],
"preprocess_time": "0.005",
"request_id": "755a639c-634c-11e8-91b4-fa76868b7be4",
"results": [
{
"keywords": "key",
"metadata": null,
"price": 10,
"product_id": "1",
"score": 1,
"url": "https://styleai-shopping.oss-cn-beijing.aliyuncs.com/14d1b1e8a38ae767cc67834799be5ef9ed4595b9.jpg",
"url_id": 1
},
{
"keywords": "key",
"metadata": null,
"price": 10,
"product_id": "2",
"score": 1,
"url": "https://styleai-shopping.oss-cn-beijing.aliyuncs.com/14d1b1e8a38ae767cc67834799be5ef9ed4595b9.jpg",
"url_id": 1
}
],
"searchtime": "0.125",
"time": 0.706,
"type": null,
"ver": "20180529-112740"
}

results field is an arrary, it contains all the search results, for details please refer to Results details

Fields relate to time

FieldTypeDescription
detect_timeStringTime cost of detection, seconds
download_timeStringTime cost of image downloading, seconds
preprocess_timeStringTime cost of preprocessing, seconds
searchtimeStringTime cost of search, seconds
timeStringTotal time cost on server side, seconds

Fields relate to detector

FieldTypeDescription
detect_timeStringTime cost of detection, seconds
detection_scoreFloatConfidence score returned by detection service
locArrayReturned from detection service, object detected with highest score, values are x, y, w, h
typeArrayReturned from detection service, category of detected object

Other fields

FieldTypeDescription
dsStringdeprecated, please do not use
is_errIntegerdeprecated, please do not use
most_common_tagsArrayFor details please refer to ret_img_tags
request_idStringUnique ID of this API call, can be used in issue debugging with ProductAI support team
verStringindex version number

Results details

{
"keywords": "key",
"metadata": null,
"price": 10,
"product_id": "1",
"score": 1,
"url": "https://styleai-shopping.oss-cn-beijing.aliyuncs.com/14d1b1e8a38ae767cc67834799be5ef9ed4595b9.jpg",
"url_id": 1
}
FieldTypeDescription
product_idStringThe unique ID of the product
urlStringThe URL of the returned image
priceFloatThe product price
keywordsStringContent of product fuzzy search
scoreScoreSimilarity score with query image

Error Code

SDK/API notifies the client about whether the request success or fails via HTTP status code

HTTP Status CodeDescription
200Search successfully
404Service doesn’t exist

Advanced

Keywords

Every product item in the product set will have a ‘keywords’ field. This ‘keywords’ filed will be segmented into several single words in the indexing process. The search engine will use these words to filter the searching result and make sure the products returned will include these words in the ‘keywords’ field.

For example, returning products containing word ‘sofa’ in the ‘keywords’ filed.

Python

PHP

Java

cURL

api.query(image='http://xxxx.jpg', keywords=u'sofa')
api->search($service_id=SERVICE_ID, $image='http://xxxx.jpg', $options=[ 'keywords'=>'sofa' ]);
String result = productService.query(SERVICE_ID, "http://yyyy", null, 20, null, "sofa", null, null, null);
curl -X POST \
-H 'x-ca-version: 1.0' \
-H 'x-ca-accesskeyid: ACCESS_KEY_ID' \
-H 'Content-Type: application/json' \
-d '{"url":"http://xxxx.jpg","keywords":"sofa"}' \
https://api.productai.cn/product_search/SERVICE_ID

min_price and max_price

Every product item in the product set can have a ‘price’ field. We can use ‘min_price’ and ‘max_price’ arguments to filter the searching result, and make sure the product price is between the minimum price and the maximum price.

For example, returning products whose price is between 1000 and 50000.

Python

PHP

Java

cURL

api.query(image='http://xxx.jpg', min_price=1000.0, max_price=50000.0)
api->search($service_id=SERVICE_ID, $image='http://xxx.jpg', $options=[ 'max_price'=>50000.0, 'min_price'=>1000.0]);
String result = productService.query(SERVICE_ID, "http://yyyy", null, 20, null, null, "1000", "50000", null);
curl -X POST \
-H 'x-ca-version: 1.0' \
-H 'x-ca-accesskeyid: ACCESS_KEY_ID' \
-H 'Content-Type: application/json' \
-d '{"url":"http://xxxx.jpg","min_price":"1000","max_price":"50000"}' \
https://api.productai.cn/product_search/SERVICE_ID

Returning products whose price is higher than 1000.

Python

PHP

Java

cURL

api.query(image='http://xxxx.jpg', min_price=1000.0)
api->search($service_id=SERVICE_ID, $image='http://xxxx.jpg', $options=[ 'min_price'=>1000.0]);
String result = productService.query(SERVICE_ID, "http://yyyy", null, 20, null, null, "1000", null, null);
curl -X POST \
-H 'x-ca-version: 1.0' \
-H 'x-ca-accesskeyid: ACCESS_KEY_ID' \
-H 'Content-Type: application/json' \
-d '{"url":"http://xxxx.jpg","min_price":"1000"}' \
https://api.productai.cn/product_search/SERVICE_ID

Returning products whose price is under 50000.

Python

PHP

Java

cURL

api.query(image='http://xxxx.jpg', max_price=50000.0)
api->search($service_id=SERVICE_ID, $image='http://xxxx.jpg', $options=[ 'max_price'=>50000.0]);
String result = productService.query(SERVICE_ID, "http://yyyy", null, 20, null, null, null, "50000", null);
curl -X POST \
-H 'x-ca-version: 1.0' \
-H 'x-ca-accesskeyid: ACCESS_KEY_ID' \
-H 'Content-Type: application/json' \
-d '{"url":"http://xxxx.jpg","max_price":"50000"}' \
https://api.productai.cn/product_search/SERVICE_ID

A product with multiple images

The same product_id in the product set can correspond to multiple product images. When adding product data, it is allowed that records with the same product_id can correspond to different image_url. Please refer to the following product set update file contents:

{"product_id": "001", "image_url": "XXX", "keywords":"XX XXX XX", "price": 1.0}
{"product_id": "001", "image_url": "YYY"}