This tutorial demonstrates how to create a product set which contains a group of products with reference images for those products. The tutorial shows users how to create a product set via online (individual) import. After the product set has been indexed, you can query the product set using Vision API Product Search.
In this tutorial, you will learn how to:
- Create a product set through online (individual) import
- Create an individual product
- Add a product to a product set
- Update a product
- Create a reference image
- Search for similar products
Before you begin
Before you begin this tutorial make sure you have installed the appropriate client libraries, enabled billing and the API for your project, and have properly set up authentication.
Import Libraries
To use the Vision API Product Search, import the following modules after downloading and installing the client library:
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.
Running the Application
Step 1: Create a Product Catalog
Users have two options for creating a product catalog, either via batch import using a CSV file, which allows an entire product catalog to be imported in a single API call, or via online import, which offers you control over your product sets and allows for management of one resource or relationship at a time. This primarily means individual creation of product sets, products, and reference images. Online import also allows you to incrementally update a product catalog you have already created via batch import.
In this tutorial you will use online import. See the Quickstart for an example of batch import with a CSV.
Online (Individual) Import
1. Create a Product Set
Create an empty Product Set which is a simple container for a group of products.
Request
Create an empty Product Set and name it "PS_CLOTH-SHOE_070318"
by executing the following request using the method create_product_set()
.
Pass the product set id and display name as arguments.
REST
Before using any of the request data, make the following replacements:
- 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
. - DISPLAY_NAME: A string display name of your choosing.
HTTP method and URL:
POST https://vision.googleapis.com/v1/projects/project-id/locations/location-id/productSets
Request JSON body:
{ "displayName": "display-name" }
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/projects/project-id/locations/location-id/productSets"
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/projects/project-id/locations/location-id/productSets" | Select-Object -Expand Content
If the request is successful, the server returns a 200 OK
HTTP status code and the
response in JSON format.
You should see output similar to the following. You can use the product set ID
(b6d809615b6dd675
, in this case) to perform other operations on the product set.
{ "name": "projects/project-id/locations/location-id/productSets/b6d809615b6dd675", "displayName": "new-product-set" }
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.
Response
Product set name: projects/prj-prod-search-tutorials/locations/us-east1/productSets/PS_CLOTH-SHOE_070318 Product set id: PS_CLOTH-SHOE_070318 Product set display name: CLOTH-SHOE
2. Create a Product
After a product set has been created, the next step is to create a product. Create a product by executing the following request.
REST
Before using any of the request data, make the following replacements:
- 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
. - DISPLAY_NAME: A string display name of your choosing.
- PRODUCT_DESCRIPTION: A string description of your choosing.
- product-category: A valid product category. The
following product categories are currently available:
homegoods-v2
,apparel-v2
,toys-v2
,packagedgoods-v1
, andgeneral-v1
. productLabels
: One or more key-value pairs associated with a product. Each KEY_STRING must have an associated VALUE_STRING.
HTTP method and URL:
POST https://vision.googleapis.com/v1/projects/project-id/locations/location-id/products
Request JSON body:
{ "displayName": "display-name", "description": "product-description", "productCategory": "product-category", "productLabels": [ { "key": "key-string", "value": "value-string" } ] }
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/projects/project-id/locations/location-id/products"
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/projects/project-id/locations/location-id/products" | Select-Object -Expand Content
Example request body:
{ "displayName": "sample-product-1234", "description": "Athletic shorts", "productCategory": "apparel-v2", "productLabels": [ { "key": "style", "value": "womens" }, { "key": "color", "value": "blue" } ] }
If the request is successful, the server returns a 200 OK
HTTP status code and the
response in JSON format.
You should see output similar to the following. You can use the product ID
(37b9811d308c4e42
, in this case) to perform other operations on the product.
{ "name": "projects/project-id/locations/location-id/products/37b9811d308c4e42", "displayName": "sample-product-456", "description": "Athletic shorts", "productCategory": "apparel-v2", "productLabels": [ { "key": "style", "value": "womens" }, { "key": "color", "value": "blue" } ] }
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.
Response
Product name: projects/prj-prod-search-tutorials/locations/us-east1/products/P_CLOTH-SHOE_46903668_070318 Product id: P_CLOTH-SHOE_46903668_070318 Product display name: Blue Dress Product category: apparel Product description: Short sleeved and 1950s style satin dress Product labels: Product label 1: key: style value: women Product label 2: key: category value: dress Product label 3: key: color value: dark-blue
3. Add a Product to a Product Set
After a product set and a product have been created, you can add the product to the product set.
REST
Before using any of the request data, make the following replacements:
- 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.
- PRODUCT_NAME: The full resource name of the product.
Format:
projects/PROJECT_ID/locations/LOCATION_ID/products/PRODUCT_ID
HTTP method and URL:
POST https://vision.googleapis.com/v1/projects/project-id/locations/location-id/productSets/product-set-id:addProduct
Request JSON body:
{ "product": "product-name" }
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/projects/project-id/locations/location-id/productSets/product-set-id:addProduct"
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/projects/project-id/locations/location-id/productSets/product-set-id:addProduct" | Select-Object -Expand Content
You should receive a JSON response similar to the following:
{}
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.
Response
Product added to product set.
4. Update a product
If you need to update a product or product set after it has been created, you can use our update methods. This example shows a product update where the labels are changed:
Command-line
When you send a PATCH
request all previous fields and their values will be erased
except for the productCategory
field, which is immutable.
Send all fields you need with values when making the PATCH
update request.
Before using any of the request data, make the following replacements:
- 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_ID: The ID for the product that is associated with a reference image. This ID is either randomly set or specified by the user at product creation time.
- display-name: A string display name of your choosing. This can be the same as the previous display name or an updated value.
- description: A string description of your choosing. This can be the same as the
previous display name or an updated value. Omit the
description
field and value if you don't need it. productLabels
: One or more key-value pairs associated with a product. Each KEY_STRING must have an associated VALUE_STRING.
HTTP method and URL:
PATCH https://vision.googleapis.com/v1/projects/project-id/locations/location-id/products/product-id
Request JSON body:
{ "displayName": "display-name", "description": "description", "productLabels": [ { "key": "key-string", "value": "value-string" }, { "key": "key-string", "value": "value-string" } ] }
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 PATCH \
-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/projects/project-id/locations/location-id/products/product-id"
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 PATCH `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://vision.googleapis.com/v1/projects/project-id/locations/location-id/products/product-id" | Select-Object -Expand Content
You should receive a JSON response similar to the following:
{ "name": "projects/project-id/locations/location-id/products/product-id", "displayName": "display-name", "description": "description", "productCategory": "apparel-v2", "productLabels": [ { "key": "style", "value": "womens" }, { "key": "onSale", "value": "true" } ] }
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.
Response
Product name: projects/prj-prod-search-tutorials/locations/us-east1/products/P_CLOTH-SHOE_46903668_070318 Product id: P_CLOTH-SHOE_46903668_070318 Product display name: Blue Dress Updated product labels: Product label 1: key: style value: women Product label 2: key: category value: dress Product label 3: key: color value: blue Product description: Short sleeved and 1950s style satin dress
5. Create a Product's Reference Image
Creating a reference image for an individual product allows Vision API Product Search to search for the product by this image after it is indexed. You can have multiple reference images in a product, particularly if you desire a better match quality.
You can add a new reference image to a product at any time.
When creating a reference image you have the option to include bounding poly coordinates. A bounding poly identifies an area of interest in the reference image. For example, if you create a reference image for a product that is a jacket, you can provide the coordinates for the jacket in the bounding poly argument, and the system will only consider the jacket when looking for product matches. Note: You can provide multiple bounding polys at index time, though at query time the API supports only a single bounding poly.
A convenient way to get the bounding poly coordinates for an image is to use Vision API object localization. For more information on object localization, see Detecting Multiple Objects.
REST
Before using any of the request data, make the following replacements:
- 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_ID: The ID for the product that is associated with a reference image. This ID is either randomly set or specified by the user at product creation time.
- 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:https://storage-bucket/filename.jpg
HTTP method and URL:
POST https://vision.googleapis.com/v1/projects/project-id/locations/location-id/products/product-id/referenceImages
Request JSON body:
{ "uri": "cloud-storage-image-uri", "boundingPolys": [ { "vertices": [ { "x": X_MIN, "y": Y_MIN }, { "x": X_MAX, "y": Y_MIN }, { "x": X_MAX, "y": Y_MAX }, { "x": X_MIN, "y": Y_MAX } ] } ] }
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/projects/project-id/locations/location-id/products/product-id/referenceImages"
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/projects/project-id/locations/location-id/products/product-id/referenceImages" | Select-Object -Expand Content
If the request is successful, the server returns a 200 OK
HTTP status code and the
response in JSON format.
You should see output similar to the following. The example request specified a single
boundingPoly
in the image. The vertices for the bounding box are not
normalized; the vertex values are the actual pixel values, and not relative to the
original image and scaled from 0 to 1. These vertices have the following
values: [(33,22),(282,22),(282,278),(33,278)].
{ "name": "projects/project-id/locations/location-id/products/product-id/referenceImages/image-id", "uri": "gs:https://storage-bucket/filename.jpg", "boundingPolys": [ { "vertices": [ { "x": 33, "y": 22 }, { "x": 282, "y": 22 }, { "x": 282, "y": 278 }, { "x": 33, "y": 278 } ] } ] }
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.
Response
Reference image name: projects/prj-prod-search-tutorials/locations/us-east1/products/P_CLOTH-SHOE_46903668_070318/referenceImages/I_469a896b70ba11e8be97d20059124800_070418 Reference image id: I_469a896b70ba11e8be97d20059124800_070418 Reference image uri: gs://product-search-tutorial/dress-shoe-dataset/469a896b70ba11e8be97d20059124800.jpg Reference image bounding polygons: vertices { x: 80 y: 50 } vertices { x: 80 y: 660 } vertices { x: 300 y: 50 } vertices { x: 430 y: 660 }
Step 2: Search For Matching Products
This interface allows you to query the product catalog you created by taking a new image as input and searching for the best matching product.
Similar to creating a reference image, when searching for matching images you have the option to include bounding poly coordinates. A bounding poly identifies the area of interest in the source image that you want to find matches for. For example, if your source image contains both a dress and a purse, and you only want to find matches for the dress, you can identify the bounding poly coordinates for the region of the picture that contains only the dress. By default, if no bounding poly is specified the API determines the largest bounding poly and queries it automatically.
A convenient way to get the bounding poly coordinates for an image is to use Vision API object localization. For more information on object localization, see Detecting Multiple Objects. For example, you can explicitly query a full image by specifying a bounding poly of the entire image box: [(0, 0), (0, 1), (1, 1), (1, 0)].
The request returns an API response that includes the best matching product for an image with the score and the matching image. This image is returned using the highest confidence value.
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.
Apparel Response Example
Search Image: D:/product/final/images-20180618T073733Z-01/images/469355b570ba11e88ff2d20059124800.jpg
Similar product information: Product id: 46930b6b Product display name: Evening gown Product description: Blue evening gown in 1940s style Product category: apparel style: women category: dress color: blue
Searching with a Label
The following search example includes a filter based on color.
Request
Make a search request by executing the following request with method
get_similar_products_file()
or get_similar_products_uri()
. Product set id,
local image file path and filter
are passed as arguments. This input image is also present in "resources/input/".
Python
python product_search.py get_similar_products_file "12000002" "D:/product/final/images-20180618T073733Z-001/images/469355b570ba11e88ff2d20059124800.jpg" "color=white"
Response
Search Image: D:/product/final/images-20180618T073733Z-001/images/469355b570ba11e88ff2d20059124800.jpg
Similar product information: Product id: p569d4e7a1 Product display name: Wedding Dress Product description: Elegant Wedding Dress for women Product category: apparel style: women category: dress color: white