Once you have created your product set and the product set has been indexed, you can query the product set using the Cloud Vision API.
Matching product search
You can find similar products to a given image by passing the image's Google Cloud Storage URI, web URL, or base64 encoded string to Vision API Product Search. Refer to the Usage Limits for maximum request size and quota information.
See the Understanding search responses & multi-detection topic for an example of single product detection and multi-detection of products in an image.
Search using a local image
The following samples read a local file and query the API by including inline the raw image bytes (base64 encoded image) in the request.
REST
Before using any of the request data, make the following replacements:
- BASE64_ENCODED_IMAGE: The base64
representation (ASCII string) of your binary image data. This string should look similar to the
following string:
/9j/4QAYRXhpZgAA...9tAVx/zDQDlGxn//2Q==
- PROJECT_ID: Your Google Cloud project ID.
- LOCATION_ID: A valid location identifier. Valid location identifiers are:
us-west1
,us-east1
,europe-west1
, andasia-east1
. - PRODUCT_SET_ID: The ID for the product set you want to run the operation on.
Field-specific considerations:
features.maxResults
- The maximum number of results to be returned.imageContext.productCategories
- The product category to search in. Currently you can only specify one product category (homegoods, apparel, toys, packaged goods, and general ).imageContext.filter
- (Optional) A key-value filtering expression (or multiple expressions) for product label. Format: "key
=value
". Filtering key-value pairs can be linked with AND or OR expressions: "color
=blue
ANDstyle
=mens
", or "color
=blue
ORcolor
=black
". If using the OR expression all keys in the expression must be the same.
HTTP method and URL:
POST https://vision.googleapis.com/v1/images:annotate
Request JSON body:
{ "requests": [ { "image": { "content": base64-encoded-image }, "features": [ { "type": "PRODUCT_SEARCH", "maxResults": 5 } ], "imageContext": { "productSearchParams": { "productSet": "projects/project-id/locations/location-id/productSets/product-set-id", "productCategories": [ "apparel" ], "filter": "style = womens" } } } ] }
To send your request, choose one of these options:
curl
Save the request body in a file named request.json
,
and execute the following command:
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "x-goog-user-project: project-id" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://vision.googleapis.com/v1/images:annotate"
PowerShell
Save the request body in a file named request.json
,
and execute the following command:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "project-id" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://vision.googleapis.com/v1/images:annotate" | Select-Object -Expand Content
If the request is successful, the server returns a 200 OK
HTTP status code and
the response in JSON format.
The response JSON includes the two following result types:
productSearchResults
- Contains a list of matching products for the entire image. In the sample response the matching products are: product_id65, product_id35, product_id34, product_id62, product_id32.productGroupedResults
- Contains bounding box coordinates and matching items for each product identified in the image. In the following response there is only one product identified, followed by matching products in the sample product set: product_id65, product_id35, product_id34, product_id93, product_id62.
Note that while there is overlap in the two result types, there may also be differences (for example, product_id32 and product_id93 in the response).
Go
To learn how to install and use the client library for Vision API Product Search, see Vision API Product Search client libraries. For more information, see the Vision API Product Search Go API reference documentation.
To authenticate to Vision API Product Search, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Java
To learn how to install and use the client library for Vision API Product Search, see Vision API Product Search client libraries. For more information, see the Vision API Product Search Java API reference documentation.
To authenticate to Vision API Product Search, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Node.js
To learn how to install and use the client library for Vision API Product Search, see Vision API Product Search client libraries. For more information, see the Vision API Product Search Node.js API reference documentation.
To authenticate to Vision API Product Search, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Python
To learn how to install and use the client library for Vision API Product Search, see Vision API Product Search client libraries. For more information, see the Vision API Product Search Python API reference documentation.
To authenticate to Vision API Product Search, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Additional languages
C#: Please follow the C# setup instructions on the client libraries page and then visit the Vision API Product Search reference documentation for .NET.
PHP: Please follow the PHP setup instructions on the client libraries page and then visit the Vision API Product Search reference documentation for PHP.
Ruby: Please follow the Ruby setup instructions on the client libraries page and then visit the Vision API Product Search reference documentation for Ruby.
Search using a remote image
You also have the option of finding similar products to a given image by specifying the Cloud Storage URI to the image.
REST
Before using any of the request data, make the following replacements:
- CLOUD_STORAGE_IMAGE_URI: the path to a valid
image file in a Cloud Storage bucket. You must at least have read privileges to the file.
Example:
gs://storage-bucket/filename.jpg
- PROJECT_ID: Your Google Cloud project ID.
- LOCATION_ID: A valid location identifier. Valid location identifiers are:
us-west1
,us-east1
,europe-west1
, andasia-east1
. - PRODUCT_SET_ID: The ID for the product set you want to run the operation on.
Field-specific considerations:
features.maxResults
- The maximum number of results to be returned.imageContext.productCategories
- The product category to search in. Currently you can only specify one product category (homegoods, apparel, toys, packaged goods, and general ).imageContext.filter
- (Optional) A key-value filtering expression (or multiple expressions) for product label. Format: "key
=value
". Filtering key-value pairs can be linked with AND or OR expressions: "color
=blue
ANDstyle
=mens
", or "color
=blue
ORcolor
=black
". If using the OR expression all keys in the expression must be the same.
HTTP method and URL:
POST https://vision.googleapis.com/v1/images:annotate
Request JSON body:
{ "requests": [ { "image": { "source": { "gcsImageUri": "cloud-storage-image-uri" } }, "features": [ { "type": "PRODUCT_SEARCH", "maxResults": 5 } ], "imageContext": { "productSearchParams": { "productSet": "projects/project-id/locations/location-id/productSets/product-set-id", "productCategories": [ "apparel" ], "filter": "style = womens" } } } ] }
To send your request, choose one of these options:
curl
Save the request body in a file named request.json
,
and execute the following command:
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "x-goog-user-project: project-id" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://vision.googleapis.com/v1/images:annotate"
PowerShell
Save the request body in a file named request.json
,
and execute the following command:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "project-id" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://vision.googleapis.com/v1/images:annotate" | Select-Object -Expand Content
If the request is successful, the server returns a 200 OK
HTTP status code and
the response in JSON format.
The response JSON includes the two following result types:
productSearchResults
- Contains a list of matching products for the entire image. In the sample response the matching products are: product_id65, product_id35, product_id34, product_id62, product_id32.productGroupedResults
- Contains bounding box coordinates and matching items for each product identified in the image. In the following response there is only one product identified, followed by matching products in the sample product set: product_id65, product_id35, product_id34, product_id93, product_id62.
Note that while there is overlap in the two result types, there may also be differences (for example, product_id32 and product_id93 in the response).
Go
To learn how to install and use the client library for Vision API Product Search, see Vision API Product Search client libraries. For more information, see the Vision API Product Search Go API reference documentation.
To authenticate to Vision API Product Search, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Java
To learn how to install and use the client library for Vision API Product Search, see Vision API Product Search client libraries. For more information, see the Vision API Product Search Java API reference documentation.
To authenticate to Vision API Product Search, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Node.js
To learn how to install and use the client library for Vision API Product Search, see Vision API Product Search client libraries. For more information, see the Vision API Product Search Node.js API reference documentation.
To authenticate to Vision API Product Search, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Python
To learn how to install and use the client library for Vision API Product Search, see Vision API Product Search client libraries. For more information, see the Vision API Product Search Python API reference documentation.
To authenticate to Vision API Product Search, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Additional languages
C#: Please follow the C# setup instructions on the client libraries page and then visit the Vision API Product Search reference documentation for .NET.
PHP: Please follow the PHP setup instructions on the client libraries page and then visit the Vision API Product Search reference documentation for PHP.
Ruby: Please follow the Ruby setup instructions on the client libraries page and then visit the Vision API Product Search reference documentation for Ruby.