Reference images are images containing various views of your products. The following recommendations apply:
- Make sure the size of the file doesn't exceed the maximum size (20MB).
- Consider viewpoints that logically highlight the product and contain relevant visual information.
- Create reference images that supplement any missing viewpoints. For example, if you only have images of the right shoe in a pair, provide mirrored versions of those files as the left shoe.
- Upload the highest resolution image available.
- Show the product against a white background.
- Convert PNGs with transparent backgrounds to a solid background.
Images must be stored in a Cloud Storage bucket. If you're authenticating your image create call with an API key, the bucket must be public. If you're authenticating with a service account, that service account must have read access on the bucket.
Creating a single reference image
You can add a reference image to an existing product. This then allows you to search for the product by the image.
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://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://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.
Creating multiple reference images with bulk import
You can also create reference images at the same time you create a product set and multiple products.
Create reference images in bulk by passing the Cloud Storage location of
a CSV file to the import
method. Thus, the CSV file and the images it points to must both be in a
Cloud Storage bucket.
If you're authenticating your bulk import call with an API key, this CSV source file must be public.
If you're authenticating with a service account, that service account must have read access on the CSV source file.
CSV format
image-uri,[image-id],product-set-id,product-id,product-category,[product-display-name],[label(s)],[bounding-poly]
See the CSV format how-to topic for more detailed information about formatting your CSV.
Bulk creation 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
. - STORAGE_PATH: A Cloud Storage bucket/directory where your input CSV file is stored. The requesting user must have at least read permission to the bucket.
HTTP method and URL:
POST https://vision.googleapis.com/v1/projects/project-id/locations/location-id/productSets:import
Request JSON body:
{ "inputConfig": { "gcsSource": { "csvFileUri": "storage-path" } } }
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:import"
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:import" | Select-Object -Expand Content
You should see output similar to the following. You can use the operation ID
(f10f34e32c40a710
, in this case) to get the status of the task. For an
example, see Getting an operation's status:
{ "name": "projects/project-id/locations/location-id/operations/f10f34e32c40a710" }
After the long-running operation completes you can get the details of the import operation. The response should look similar to the following:
{ "name": "locations/location-id/operations/f10f34e32c40a710", "metadata": { "@type": "type.googleapis.com/google.cloud.vision.v1.BatchOperationMetadata", "state": "SUCCESSFUL", "submitTime": "2019-12-06T21:16:04.476466873Z", "endTime": "2019-12-06T21:16:40.594258084Z" }, "done": true, "response": { "@type": "type.googleapis.com/google.cloud.vision.v1.ImportProductSetsResponse", "referenceImages": [ { "name": "projects/project-id/locations/location-id/products/product_id0/referenceImages/image0", "uri": "gs://my-storage-bucket/img_039.jpg" }, { "name": "projects/project-id/locations/location-id/products/product_id1/referenceImages/image1", "uri": "gs://my-storage-bucket/img_105.jpg" }, { "name": "projects/project-id/locations/location-id/products/product_id2/referenceImages/image2", "uri": "gs://my-storage-bucket/img_224.jpg" }, { "name": "projects/project-id/locations/location-id/products/product_id3/referenceImages/image3", "uri": "gs://my-storage-bucket/img_385.jpg" } ], "statuses": [ {}, {}, {}, {} ] } }
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.
Indexing
The Product Search index of products is updated approximately every 30 minutes. When images are added or deleted, the change won't be reflected in your Product Search responses until the index is next updated.
To make sure that indexing has completed successfully, check the
indexTime
field
of a product set.