All Products
Search
Document Center

Image Search:Search for images

Last Updated:Aug 25, 2023

Searches for image information in an Image Search instance.

Before you call this operation, you must specify the instanceName parameter in a URL to specify the instance in which you want to search for images. You must also specify other parameters in a specified format to construct a request body. The request URL includes /item/search.

Request parameters

  • Parameters in the URL

    Parameter

    Type

    Required

    Description

    instanceName

    String

    Yes

    The name of the instance where you search for images.

  • Parameters in the request body

    Parameter

    Type

    Required

    Description

    cat_id

    String

    No

    The ID of the category.

    n

    int

    No

    The number of images to be returned.

    s

    int

    No

    No. of the first image to be displayed.

    crop

    boolean

    No

    Specifies whether to recognize the subject in the image and search for images based on the recognized subject. Valid values: true and false. Default value: true.

    region

    String

    No

    The subject area in the image. The subject area is in the format of x1,x2,y1,y2. x1 and y1 represent the upper-left corner pixel. x2 and y2 represent the lower-right pixel. By default, the system automatically recognizes the subject area.

    pic_list

    List

    Yes

    The name of the sample image based on which you search for similar images. You can specify only one image name.

    pic_map

    Map

    Yes

    The content of the sample image.

  • Body structure
    The body is in the following format:
    key1,key1_start_offset,key1_end_offset#...#keyn,keyn_start_offset,keyn_end_offset^key1_content...keyn_content

    The body is divided into two parts: image metadata and image content, which are separated with a circumflex (^). The metadata includes a set of keys and the offset of each key value in the content. Keys are separated with number signs (#). Each key includes a key name, a start offset value, and an end offset value, which are separated with commas (,). The start offset value and the end offset value represent the start position and end position of the key the image content. The pic_list parameter specifies Base64-encoded images names that are separated with commas (,). The pic_map parameter specifies Base64-encoded image content. Each key that is specified in the pic_map parameter must be paired with a key that is specified in the pic_list parameter.

Response parameters

Parameter

Type

Description

Success

Boolean

Indicates whether the request is successful.

RequestId

String

The ID of the request.

Code

int

The error code. The value 0 indicates a request success. A value that is not 0 indicates a request failure.

Message

String

The returned message.

Head

Map

The description of the search results.

DocsReturn

int

The number of the returned images.

DocsFound

int

The number of the matched images in the instance.

PicInfo

Map

The image matting information.

Category

String

The category of the image.

Region

String

The subject area in the image. The subject area is in the format of x1,x2,y1,y2. x1 and y1 represent the upper-left corner pixel. x2 and y2 represent the lower-right pixel. By default, the system automatically recognizes the subject area.

AllCategory

Map

All the categories that are supported by the system.

Name

String

The name of the category.

Id

String

The ID of the category.

Auctions

Map

All the product descriptions that were returned.

CustContent

String

The custom content of the product.

PicName

String

The name of the image.

CatId

String

The category of the image.

ProductId

String

The ID of the product.

SortExprValues

String

The score information about the image.

Response format

{
    "Auctions": {
        "Auction": [{
            "CustContent": "k1:v1,k2:v2,k3:v3",
            "PicName": "girl_cloth3.jpg",
            "CatId": "0",
            "SortExprValues": "7.33136443711219e+24;0",
            "ProductId": "1002"
        }]
    },
    "Head": {
        "DocsReturn": 1,
        "DocsFound": 57,
        "SearchTime": 124
    },
    "PicInfo": {
        "Category": "0",
        "Region": "51,339,91,392",
        "AllCategory": {
            "Category": [{
                "Name": "Tops",
                "Id": "0"
            }, {
                "Name": "Dress",
                "Id": "1"
            }, {
                "Name": "Bottoms",
                "Id": "2"
            }, {
                "Name": "Bag",
                "Id": "3"
            }, {
                "Name": "Shoes",
                "Id": "4"
            }, {
                "Name": "Accessories",
                "Id": "5"
            }, {
                "Name": "Snack",
                "Id": "6"
            }, {
                "Name": "Makeup",
                "Id": "7"
            }, {
                "Name": "Bottle",
                "Id": "8"
            }, {
                "Name": "Furniture",
                "Id": "9"
            }, {
                "Name": "Toy",
                "Id": "20"
            }, {
                "Name": "Underwear",
                "Id": "21"
            }, {
                "Name": "Digital device",
                "Id": "22"
            }, {
                "Name": "Other",
                "Id": "88888888"
            }]
        }
    },
    "Message": "success",
    "RequestId": "183A7C57-20B9-4AE6-8227-1EE8B0A4B99B",
    "Success": true,
    "Code": 0
}

Examples

The following example shows how to search for a product image whose category ID is 0 in the goodssearch instance. In this example, the image content is pic_content1 and the image name is searchPic. No. of the first image to be displayed is 0. The number of images to be returned is 10. The following request is provided:

URL: /item/search? instanceName=goodssearch
POST Body:
s,0,1#cat_id,1,2#pic_list,2,14#c2VhcmNoUGlj,14,30#n,30,32^00c2VhcmNoUGljcGljX2NvbnRlbnQx10
Note

c2VhcmNoUGlj represents the Base64-encoded image name.