Managing Products and Reference Images

Product Search has three resource types: product sets, products, and reference images.

  • Product Set - A container for a group of products with reference images for those products. When you query for product images, you must supply the id of the product set to search.

  • Product - Describes a product. Contains one or more reference images, a product category, and optional list of product labels that describe the product. You can add any key/value pair as a label. Label examples include color=blue, style=kids.

    Currently supported product categories are: homegoods and apparel

  • Reference Image - An image file for a product. The metadata includes a product ID, a category, and bounding box details. Reference images must belong to a product.

The API contains methods for creating, listing/getting, updating, and deleting product sets, products, and reference images.

Authentication

Cloud Vision API product search supports both API key and OAuth 2.0 authentication.

If you use an API key when creating your reference images, the image files in Google Cloud Storage must be publicly readable. Private files are supported when using OAuth 2.0, provided the service account has read access.

For instructions on authenticating with either method, refer to Authenticating to a Cloud Service in the Cloud Vision API docs.

Client Libraries

The samples in this topic use the Beta Client Libraries. Be sure to install the client library before running the samples in this topic.

Creating a product set

A product set is a simple container for a group of products.

We recommend a single product set for all of your items. You can create additional product sets for testing.

Command-line

To create a product set, send a POST to the https://vision.googleapis.com/v1p3beta1/{parent=projects/*/locations/*}/productSets endpoint in the following format.

  • Replace project-id with the id of your Google Cloud Platform (GCP) project.

  • Replace location-id with a valid location identifier. Valid location identifiers are: us-west1, us-east1, europe-west1, and asia-east1.

  • Replace display-name with the display name for your new product set.

POST https://vision.googleapis.com/v1p3beta1/projects/project-id/locations/location-id/productSets
{
   'displayName' : 'display-name'
}

Python

For more on installing and creating a Vision Product Search client, refer to Vision Product Search Client Libraries.

from google.cloud import vision_v1p3beta1 as vision

def create_product_set(
        project_id, location, product_set_id, product_set_display_name):
    """Create a product set.
    Args:
        project_id: Id of the project.
        location: A compute region name.
        product_set_id: Id of the product set.
        product_set_display_name: Display name of the product set.
    """
    client = vision.ProductSearchClient()

    # A resource that represents Google Cloud Platform location.
    location_path = client.location_path(
        project=project_id, location=location)

    # Create a product set with the product set specification in the region.
    product_set = vision.types.ProductSet(
            display_name=product_set_display_name)

    # The response is the product set with `name` populated.
    response = client.create_product_set(
        parent=location_path,
        product_set=product_set,
        product_set_id=product_set_id)

    # Display the product set information.
    print('Product set name: {}'.format(response.name))

Java

For more on installing and creating a Vision Product Search client, refer to Vision Product Search Client Libraries.

/**
 * Create a product set
 *
 * @param projectId - Id of the project.
 * @param computeRegion - Region name.
 * @param productSetId - Id of the product set.
 * @param productSetDisplayName - Display name of the product set.
 * @throws IOException - on I/O errors.
 */
public static void createProductSet(
    String projectId, String computeRegion, String productSetId, String productSetDisplayName)
    throws IOException {
  ProductSearchClient client = ProductSearchClient.create();

  // A resource that represents Google Cloud Platform location.
  LocationName projectLocation = LocationName.of(projectId, computeRegion);

  // Create a product set with the product set specification in the region.
  ProductSet myProductSet = ProductSet.newBuilder().setDisplayName(productSetDisplayName).build();
  CreateProductSetRequest request =
      CreateProductSetRequest.newBuilder()
          .setParent(projectLocation.toString())
          .setProductSet(myProductSet)
          .setProductSetId(productSetId)
          .build();
  ProductSet productSet = client.createProductSet(request);

  // Display the product set information
  System.out.println(String.format("Product set name: %s", productSet.getName()));
}

Creating your products

After you have created a product set, you can create products and add them to the product set. When you create a product, you must provide a display name for the product and a product category. Currently supported categories are: homegoods or apparel.

You can also supply an optional description of your product, and optional labels for your product. Labels are key/value pairs that describe your product such as color=black or style=mens. You can include labels to filter the results of a product search to only search certain product images.

Creating a product

Command-line

To get the information for a product set, send a request to the following URI.

  • Replace project-id with the id of your Google Cloud Platform (GCP) project.

  • Replace location-id with a valid location identifier. Valid location identifiers are: us-west1, us-east1, europe-west1, and asia-east1.

POST https://vision.googleapis.com/v1p3beta1/projects/project-id/locations/location-id/products
{
  'displayName': 'sample-product-1234',
  'description': 'Athletic shorts',
  'productCategory': 'apparel',
  'productLabels': [
      { 'key': 'style', 'value': 'womens' },
      { 'key': 'color', 'value': 'blue' }
  ]
}

Python

For more on installing and creating a Vision Product Search client, refer to Vision Product Search Client Libraries.

from google.cloud import vision_v1p3beta1 as vision

def create_product(
        project_id, location, product_id, product_display_name,
        product_category):
    """Create one product.
    Args:
        project_id: Id of the project.
        location: A compute region name.
        product_id: Id of the product.
        product_display_name: Display name of the product.
        product_category: Category of the product.
    """
    client = vision.ProductSearchClient()

    # A resource that represents Google Cloud Platform location.
    location_path = client.location_path(project=project_id, location=location)

    # Create a product with the product specification in the region.
    # Set product name and product display name.
    product = vision.types.Product(
        display_name=product_display_name,
        product_category=product_category)

    # The response is the product with the `name` field populated.
    response = client.create_product(
        parent=location_path,
        product=product,
        product_id=product_id)

    # Display the product information.
    print('Product name: {}'.format(response.name))

Java

For more on installing and creating a Vision Product Search client, refer to Vision Product Search Client Libraries.

/**
 * Create one product.
 *
 * @param projectId - Id of the project.
 * @param computeRegion - Region name.
 * @param productId - Id of the product.
 * @param productDisplayName - Display name of the product.
 * @param productCategory - Category of the product.
 * @param productDescription - Description of the product.
 * @param productLabels - Labels of the product.
 * @throws IOException - on I/O errors.
 */
public static void createProduct(
    String projectId,
    String computeRegion,
    String productId,
    String productDisplayName,
    String productCategory,
    String productDescription,
    String productLabels)
    throws IOException {
  ProductSearchClient client = ProductSearchClient.create();

  // A resource that represents Google Cloud Platform location.
  LocationName projectLocation = LocationName.of(projectId, computeRegion);

  // Create a product with the product specification in the region.
  // Multiple labels are also supported.
  Product myProduct =
      Product.newBuilder()
          .setName(productId)
          .setDisplayName(productDisplayName)
          .setProductCategory(productCategory)
          .setDescription(productDescription)
          .addProductLabels(
              KeyValue.newBuilder()
                  .setKey(productLabels.split(",")[0].split("=")[0])
                  .setValue(productLabels.split(",")[0].split("=")[1])
                  .build())
          .build();
  Product product = client.createProduct(projectLocation.toString(), myProduct, productId);

  // Display the product information
  System.out.println(String.format("Product name: %s", product.getName()));
}

Adding a product to a product set

Once a product and product set are available you can add the product to the product set.

Command-line

To add a product to a product set, send a POST request to the following URI.

  • Replace project-id with the id of your Google Cloud Platform (GCP) project.

  • Replace location-id with a valid location identifier. Valid location identifiers are: us-west1, us-east1, europe-west1, and asia-east1.

  • Replace product-set-id with the id for the product set to associate with the product.

  • Replace product-id with the id for the product to add.

POST https://vision.googleapis.com/v1p3beta1/projects/project-id/locations/location-id/productSets/product-set-id:addProduct
{
  'product': 'product-id'
}

Python

For more on installing and creating a Vision Product Search client, refer to Vision Product Search Client Libraries.

from google.cloud import vision_v1p3beta1 as vision

def add_product_to_product_set(
        project_id, location, product_id, product_set_id):
    """Add a product to a product set.
    Args:
        project_id: Id of the project.
        location: A compute region name.
        product_id: Id of the product.
        product_set_id: Id of the product set.
    """
    client = vision.ProductSearchClient()

    # Get the full path of the product set.
    product_set_path = client.product_set_path(
        project=project_id, location=location,
        product_set=product_set_id)

    # Get the full path of the product.
    product_path = client.product_path(
        project=project_id, location=location, product=product_id)

    # Add the product to the product set.
    client.add_product_to_product_set(
        name=product_set_path, product=product_path)
    print('Product added to product set.')

Java

For more on installing and creating a Vision Product Search client, refer to Vision Product Search Client Libraries.

/**
 * Add a product to a product set.
 *
 * @param projectId - Id of the project.
 * @param computeRegion - Region name.
 * @param productId - Id of the product.
 * @param productSetId - Id of the product set.
 * @throws IOException - on I/O errors.
 */
public static void addProductToSet(
    String projectId, String computeRegion, String productId, String productSetId)
    throws IOException {
  ProductSearchClient client = ProductSearchClient.create();

  // Get the full path of the product set.
  ProductSetName productSetPath = ProductSetName.of(projectId, computeRegion, productSetId);

  // Get the full path of the product.
  String productPath = ProductName.of(projectId, computeRegion, productId).toString();

  // Add the product to the product set.
  client.addProductToProductSet(productSetPath, productPath);

  System.out.println(String.format("Product added to product set."));
}

Removing a product from a product set

You can also remove an existing product from a product set.

Command-line

To remove a product from a product set, send a POST request to the following URI.

  • Replace project-id with the id of your Google Cloud Platform (GCP) project.

  • Replace location-id with a valid location identifier. Valid location identifiers are: us-west1, us-east1, europe-west1, and asia-east1.

  • Replace product-set-id with the id for the product set that is associated with the product.

  • Replace product-id with the id for the product to remove.

POST https://vision.googleapis.com/v1p3beta1/projects/project-id/locations/location-id/productSets/product-set-id:removeProduct
{
  'product': 'product-id'
}

Python

For more on installing and creating a Vision Product Search client, refer to Vision Product Search Client Libraries.

from google.cloud import vision_v1p3beta1 as vision

def remove_product_from_product_set(
        project_id, location, product_id, product_set_id):
    """Remove a product from a product set.
    Args:
        project_id: Id of the project.
        location: A compute region name.
        product_id: Id of the product.
        product_set_id: Id of the product set.
    """
    client = vision.ProductSearchClient()

    # Get the full path of the product set.
    product_set_path = client.product_set_path(
        project=project_id, location=location,
        product_set=product_set_id)

    # Get the full path of the product.
    product_path = client.product_path(
        project=project_id, location=location, product=product_id)

    # Remove the product from the product set.
    client.remove_product_from_product_set(
        name=product_set_path, product=product_path)
    print('Product removed from product set.')

Java

For more on installing and creating a Vision Product Search client, refer to Vision Product Search Client Libraries.

/**
 * Remove a product from a product set.
 *
 * @param projectId - Id of the project.
 * @param computeRegion - Region name.
 * @param productId - Id of the product.
 * @param productSetId - Id of the product set.
 * @throws IOException - on I/O errors.
 */
public static void removeProductFromProductSet(
    String projectId, String computeRegion, String productId, String productSetId)
    throws IOException {
  ProductSearchClient client = ProductSearchClient.create();

  // Get the full path of the product set.
  ProductSetName productSetPath = ProductSetName.of(projectId, computeRegion, productSetId);

  // Get the full path of the product.
  String productPath = ProductName.of(projectId, computeRegion, productId).toString();

  // Remove the product from the product set.
  client.removeProductFromProductSet(productSetPath, productPath);

  System.out.println(String.format("Product removed from product set."));
}

Creating your reference images

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 (30MB).
  • 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 Google 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.

Bulk creation

Bulk create reference images by passing the Google Cloud Storage location of a CSV file to the import method. The source file must be public.

The CSV file must contain one image per line and contain the following columns:

  • imageUri: The Google Cloud Storage URI of the reference image.
  • productSetId: The identifier for the product set to import the images to.
  • productId: A user-defined ID for the product identified by the reference image. A productId can be associated with multiple reference images.
  • productCategory: Optional. The category for the product identified by the reference image. Inferred by the system if not specified in the create request. Allowed values are homegoods and apparel. Allowed values are also listed in the productCategory reference documentation.
  • labels: Optional. Labels that describe the products in the reference image. For example: color=green.
  • boundingPoly: Optional. Specifies the area of interest in the reference image. If not specified: 1) bounding box for the image is inferred by the Vision API, and 2) the line must end with a comma. See the examples below.

    The boundingPoly column should contain an even number of comma-separated numbers, with the format p1_x,p1_y,p2_x,p2_y,...,pn_x,pn_y. For example, 0.1,0.1,0.9,0.1,0.9,0.9,0.1,0.9. Non-negative integers should be used for absolute bounding polygons, and float values in [0, 1] should be used for normalized bounding polygons.

For example:

"gs://example-reference-images/10001-001/10001-001_A.jpg","sample-set","sample-product-123","apparel","style=womens","1,1,100,1,100,100,1,100"
"gs://example-reference-images/10002-002/10002-002_B.jpg","sample-set","sample-product-123","apparel",,

To import the products in your product set, send a POST request to the following URI.

  • Replace project-id with the id of your Google Cloud Platform (GCP) project.

  • Replace location-id with a valid location identifier. Valid location identifiers are: us-west1, us-east1, europe-west1, and asia-east1.

POST https://vision.googleapis.com/v1p3beta1/projects/project-id/locations/location-id/productSets:import
{
  "inputConfig": {
    "gcsSource": {
      "csvFileUri": "gs://bucket/path/to/file.csv"
    }
  }
}

A successful response contains a long-running operation object:

{
  "name": "locations/location-id/operations/operation-id"
}

To request the status of the operation, call the operations endpoint and pass the operation-id that was returned from your call to the import method. Replace location-id with the location id from your call to the import method.

GET https://vision.googleapis.com/v1p3beta1/locations/location-id/operations/operation-id

The response looks like:

{
  "name": "locations/us-west1/operations/eea5667a0ed419d8",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.vision.v1p3beta1.BatchOperationMetadata",
    "state": "SUCCESSFUL",
    "endTime": "2018-04-18T21:45:14.926185506Z"
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.cloud.vision.v1p3beta1.ImportProductSetsResponse",
    "referenceImages": [
      {
        "name": "projects/media-demo-service/locations/us-west1/products/160421_kids_01/referenceImages/17196263426604931544-0",
        "uri": "gs://cloud-ml-api-e2e-testing/vision/product_search/client-lib/160421_kids_01.jpg"
      },
      {
        "name": "projects/media-demo-service/locations/us-west1/products/160421_kids_02/referenceImages/17196263426604931544-1",
        "uri": "gs://cloud-ml-api-e2e-testing/vision/product_search/client-lib/160421_kids_02.jpg"
      },
      {
        "name": "projects/media-demo-service/locations/us-west1/products/160421_kids_04/referenceImages/17196263426604931544-2",
        "uri": "gs://cloud-ml-api-e2e-testing/vision/product_search/client-lib/160421_kids_04.jpg"
      },
      {
        "name": "projects/media-demo-service/locations/us-west1/products/160421_kids_05/referenceImages/17196263426604931544-3",
        "uri": "gs://cloud-ml-api-e2e-testing/vision/product_search/client-lib/160421_kids_05.jpg"
      },
      {
        "name": "projects/media-demo-service/locations/us-west1/products/160421_women_05/referenceImages/17196263426604931544-4",
        "uri": "gs://cloud-ml-api-e2e-testing/vision/product_search/client-lib/160421_women_05.jpg"
      },
      {
        "name": "projects/media-demo-service/locations/us-west1/products/160421_women_07/referenceImages/17196263426604931544-5",
        "uri": "gs://cloud-ml-api-e2e-testing/vision/product_search/client-lib/160421_women_07.jpg"
      }
    ],
    "statuses": [
      {},
      {},
      {},
      {},
      {},
      {}
    ]
  }
}

Common import error messages include:

  • The number of columns in the csv line should be 6: If you're not providing a bounding box, the line must end with a comma. For example:

    "gs://example-reference-images/10002-002/10002-002_B.jpg","sample-set","sample-product-123","apparel",,

  • Image not found: Your Google Cloud Storage URI does not resolve to an image file.

  • Access denied: Either your image or your CSV file does not have the correct permissions. Image files must be accessible by the authentication method used for your request. If you are authenticating with an API Key, then your CSV files must be public.

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.

Command-line

To create a reference image, send a POST request to the following URI.

  • Replace project-id with the id of your Google Cloud Platform (GCP) project.

  • Replace location-id with a valid location identifier. Valid location identifiers are: us-west1, us-east1, europe-west1, and asia-east1.

  • Replace product-id with the id of the product to associate the reference image with.

POST https://vision.googleapis.com/v1p3beta1/projects/project-id/locations/location-id/products/product-id/referenceImages
{
  'uri': 'gs://bucket/path/to/red-shoe.jpg',
  'boundingPolys': [
    {
      'vertices': [
        {
          'x': 44,
          'y': 252
        },
        {
          'x': 44,
          'y': 1351
        },
        {
          'x': 1161,
          'y': 252
        },
        {
          'x': 1161,
          'y': 1351
        }
      ]
    }
  ]
}

The boundingPolys field is optional. If omitted, the service will infer the values of the bounds for the image.

Python

For more on installing and creating a Vision Product Search client, refer to Vision Product Search Client Libraries.

from google.cloud import vision_v1p3beta1 as vision

def create_reference_image(
        project_id, location, product_id, reference_image_id, gcs_uri):
    """Create a reference image.
    Args:
        project_id: Id of the project.
        location: A compute region name.
        product_id: Id of the product.
        reference_image_id: Id of the reference image.
        gcs_uri: Google Cloud Storage path of the input image.
    """
    client = vision.ProductSearchClient()

    # Get the full path of the product.
    product_path = client.product_path(
        project=project_id, location=location, product=product_id)

    # Create a reference image.
    reference_image = vision.types.ReferenceImage(uri=gcs_uri)

    # The response is the reference image with `name` populated.
    image = client.create_reference_image(
        parent=product_path,
        reference_image=reference_image,
        reference_image_id=reference_image_id)

    # Display the reference image information.
    print('Reference image name: {}'.format(image.name))
    print('Reference image uri: {}'.format(image.uri))

Java

For more on installing and creating a Vision Product Search client, refer to Vision Product Search Client Libraries.

/**
 * Create a reference image.
 *
 * @param projectId - Id of the project.
 * @param computeRegion - Region name.
 * @param productId - Id of the product.
 * @param referenceImageId - Id of the image.
 * @param gcsUri - Google Cloud Storage path of the input image.
 * @throws IOException - on I/O errors.
 */
public static void createReferenceImage(
    String projectId,
    String computeRegion,
    String productId,
    String referenceImageId,
    String gcsUri)
    throws IOException {
  ProductSearchClient client = ProductSearchClient.create();

  // Get the full path of the product.
  ProductName productPath = ProductName.of(projectId, computeRegion, productId);

  // Create a reference image.
  ReferenceImage referenceImage = ReferenceImage.newBuilder().setUri(gcsUri).build();
  ReferenceImage image =
      client.createReferenceImage(productPath, referenceImage, referenceImageId);

  // Display the reference image information.
  System.out.println(String.format("Reference image name: %s", image.getName()));
  System.out.println(String.format("Reference image uri: %s", image.getUri()));
}

Indexing

The Product Search index 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.

Getting and listing resources

Listing product sets

You can have multiple product sets. This section describes how to retrieve a list of all your product sets.

Command-line

To get a list of all of the product sets for a GCP project, send a request to the following URI.

  • Replace project-id with the id of your Google Cloud Platform (GCP) project.

  • Replace location-id with a valid location identifier. Valid location identifiers are: us-west1, us-east1, europe-west1, and asia-east1.

GET https://vision.googleapis.com/v1p3beta1/projects/project-id/locations/location-id/productSets

Python

For more on installing and creating a Vision Product Search client, refer to Vision Product Search Client Libraries.

from google.cloud import vision_v1p3beta1 as vision

def list_product_sets(project_id, location):
    """List all product sets.
    Args:
        project_id: Id of the project.
        location: A compute region name.
    """
    client = vision.ProductSearchClient()

    # A resource that represents Google Cloud Platform location.
    location_path = client.location_path(
        project=project_id, location=location)

    # List all the product sets available in the region.
    product_sets = client.list_product_sets(parent=location_path)

    # Display the product set information.
    for product_set in product_sets:
        print('Product set name: {}'.format(product_set.name))
        print('Product set id: {}'.format(product_set.name.split('/')[-1]))
        print('Product set display name: {}'.format(product_set.display_name))
        print('Product set index time:')
        print('  seconds: {}'.format(product_set.index_time.seconds))
        print('  nanos: {}\n'.format(product_set.index_time.nanos))

Java

For more on installing and creating a Vision Product Search client, refer to Vision Product Search Client Libraries.

/**
 * List all product sets
 *
 * @param projectId - Id of the project.
 * @param computeRegion - Region name.
 * @throws IOException - on I/O errors.
 */
public static void listProductSets(String projectId, String computeRegion) throws IOException {
  ProductSearchClient client = ProductSearchClient.create();

  // A resource that represents Google Cloud Platform location.
  LocationName projectLocation = LocationName.of(projectId, computeRegion);

  // List all the product sets available in the region.
  for (ProductSet productSet : client.listProductSets(projectLocation).iterateAll()) {
    // Display the product set information
    System.out.println(String.format("Product set name: %s", productSet.getName()));
    System.out.println(
        String.format(
            "Product set id: %s",
            productSet.getName().substring(productSet.getName().lastIndexOf('/') + 1)));
    System.out.println(
        String.format("Product set display name: %s", productSet.getDisplayName()));
    System.out.println("Product set index time:");
    System.out.println(String.format("\tseconds: %s", productSet.getIndexTime().getSeconds()));
    System.out.println(String.format("\tnanos: %s", productSet.getIndexTime().getNanos()));
  }
}

Getting a single product set

You can get a single product set to use or modify.

Command-line

To get the information for a product set, send a request to the following URI.

  • Replace project-id with the id of your Google Cloud Platform (GCP) project.

  • Replace location-id with a valid location identifier. Valid location identifiers are: us-west1, us-east1, europe-west1, and asia-east1.

  • Replace product-set-id with the id for the product set that you want to get.

GET https://vision.googleapis.com/v1p3beta1/projects/project-id/locations/location-id/productSets/product-set-id

Python

For more on installing and creating a Vision Product Search client, refer to Vision Product Search Client Libraries.

from google.cloud import vision_v1p3beta1 as vision

def get_product_set(project_id, location, product_set_id):
    """Get info about the product set.
    Args:
        project_id: Id of the project.
        location: A compute region name.
        product_set_id: Id of the product set.
    """
    client = vision.ProductSearchClient()

    # Get the full path of the product set.
    product_set_path = client.product_set_path(
        project=project_id, location=location,
        product_set=product_set_id)

    # Get complete detail of the product set.
    product_set = client.get_product_set(name=product_set_path)

    # Display the product set information.
    print('Product set name: {}'.format(product_set.name))
    print('Product set id: {}'.format(product_set.name.split('/')[-1]))
    print('Product set display name: {}'.format(product_set.display_name))
    print('Product set index time:')
    print('  seconds: {}'.format(product_set.index_time.seconds))
    print('  nanos: {}'.format(product_set.index_time.nanos))

Java

For more on installing and creating a Vision Product Search client, refer to Vision Product Search Client Libraries.

/**
 * Get info about the product set.
 *
 * @param projectId - Id of the project.
 * @param computeRegion - Region name.
 * @param productSetId - Id of the product set.
 * @throws IOException - on I/O errors.
 */
public static void getProductSet(String projectId, String computeRegion, String productSetId)
    throws IOException {
  ProductSearchClient client = ProductSearchClient.create();

  // Get the full path of the product set.
  ProductSetName productSetPath = ProductSetName.of(projectId, computeRegion, productSetId);

  // Get complete detail of the product set.
  ProductSet productSet = client.getProductSet(productSetPath);

  // Display the product set information
  System.out.println(String.format("Product set name: %s", productSet.getName()));
  System.out.println(
      String.format(
          "Product set id: %s",
          productSet.getName().substring(productSet.getName().lastIndexOf('/') + 1)));
  System.out.println(String.format("Product set display name: %s", productSet.getDisplayName()));
  System.out.println("Product set index time:");
  System.out.println(String.format("\tseconds: %s", productSet.getIndexTime().getSeconds()));
  System.out.println(String.format("\tnanos: %s", productSet.getIndexTime().getNanos()));
}

Listing products

You may wish to view all products in a Google Cloud Platform project. The following example shows how to list products in a given project.

Command-line

To get a list of all of the products for a GCP project, send a request to the following URI.

  • Replace project-id with the id of your Google Cloud Platform (GCP) project.

  • Replace location-id with a valid location identifier. Valid location identifiers are: us-west1, us-east1, europe-west1, and asia-east1.

GET https://vision.googleapis.com/v1p3beta1/projects/project-id/locations/location-id/products

To list the products for a product set, send a request to the following URI.

  • Replace project-id with the id of your Google Cloud Platform (GCP) project.

  • Replace location-id with a valid location identifier. Valid location identifiers are: us-west1, us-east1, europe-west1, and asia-east1.

  • Replace product-set-id with the id for the product set that you is associated with the products that you want to list.

GET https://vision.googleapis.com/v1p3beta1/projects/project-id/locations/location-id/productSets/product-set-id/products

Python

For more on installing and creating a Vision Product Search client, refer to Vision Product Search Client Libraries.

from google.cloud import vision_v1p3beta1 as vision

def list_products(project_id, location):
    """List all products.
    Args:
        project_id: Id of the project.
        location: A compute region name.
    """
    client = vision.ProductSearchClient()

    # A resource that represents Google Cloud Platform location.
    location_path = client.location_path(project=project_id, location=location)

    # List all the products available in the region.
    products = client.list_products(parent=location_path)

    # Display the product information.
    for product in products:
        print('Product name: {}'.format(product.name))
        print('Product id: {}'.format(product.name.split('/')[-1]))
        print('Product display name: {}'.format(product.display_name))
        print('Product description: {}'.format(product.description))
        print('Product category: {}'.format(product.product_category))
        print('Product labels: {}\n'.format(product.product_labels))

Java

For more on installing and creating a Vision Product Search client, refer to Vision Product Search Client Libraries.

/**
 * List all products.
 *
 * @param projectId - Id of the project.
 * @param computeRegion - Region name.
 * @throws IOException - on I/O errors.
 */
public static void listProducts(String projectId, String computeRegion) throws IOException {
  ProductSearchClient client = ProductSearchClient.create();

  // A resource that represents Google Cloud Platform location.
  LocationName projectLocation = LocationName.of(projectId, computeRegion);

  // List all the products available in the region.
  for (Product product : client.listProducts(projectLocation).iterateAll()) {
    // Display the product information
    System.out.println(String.format("\nProduct name: %s", product.getName()));
    System.out.println(
        String.format(
            "Product id: %s",
            product.getName().substring(product.getName().lastIndexOf('/') + 1)));
    System.out.println(String.format("Product display name: %s", product.getDisplayName()));
    System.out.println(String.format("Product category: %s", product.getProductCategory()));
    System.out.println("Product labels:");
    System.out.println(
        String.format("Product labels: %s", product.getProductLabelsList().toString()));
  }
}

Getting a single product

You can also get a single product to use or modify.

Command-line

To get the information for a single product, send a request to the following URI.

  • Replace project-id with the id of your Google Cloud Platform (GCP) project.

  • Replace location-id with a valid location identifier. Valid location identifiers are: us-west1, us-east1, europe-west1, and asia-east1.

  • Replace product-id with the id for the product that you want to get.

GET https://vision.googleapis.com/v1p3beta1/projects/project-id/locations/location-id/products/product-id

Python

For more on installing and creating a Vision Product Search client, refer to Vision Product Search Client Libraries.

from google.cloud import vision_v1p3beta1 as vision

def get_product(project_id, location, product_id):
    """Get information about a product.
    Args:
        project_id: Id of the project.
        location: A compute region name.
        product_id: Id of the product.
    """
    client = vision.ProductSearchClient()

    # Get the full path of the product.
    product_path = client.product_path(
        project=project_id, location=location, product=product_id)

    # Get complete detail of the product.
    product = client.get_product(name=product_path)

    # Display the product information.
    print('Product name: {}'.format(product.name))
    print('Product id: {}'.format(product.name.split('/')[-1]))
    print('Product display name: {}'.format(product.display_name))
    print('Product description: {}'.format(product.description))
    print('Product category: {}'.format(product.product_category))
    print('Product labels: {}'.format(product.product_labels))

Java

For more on installing and creating a Vision Product Search client, refer to Vision Product Search Client Libraries.

/**
 * Get information about a product.
 *
 * @param projectId - Id of the project.
 * @param computeRegion - Region name.
 * @param productId - Id of the product.
 * @throws IOException - on I/O errors.
 */
public static void getProduct(String projectId, String computeRegion, String productId)
    throws IOException {
  ProductSearchClient client = ProductSearchClient.create();

  // Get the full path of the product.
  ProductName productPath = ProductName.of(projectId, computeRegion, productId);

  // Get complete detail of the product.
  Product product = client.getProduct(productPath.toString());

  // Display the product information
  System.out.println(String.format("Product name: %s", product.getName()));
  System.out.println(
      String.format(
          "Product id: %s", product.getName().substring(product.getName().lastIndexOf('/') + 1)));
  System.out.println(String.format("Product display name: %s", product.getDisplayName()));
  System.out.println(String.format("Product description: %s", product.getDescription()));
  System.out.println(String.format("Product category: %s", product.getProductCategory()));
  System.out.println("Product labels:");
  System.out.println(
      String.format("Product labels: %s", product.getProductLabelsList().toString()));
}

Listing images

A product can have multiple associated reference images. The following example describes how to obtain all reference images linked to a single product.

Command-line

To list the reference images for a product, send GET request to the following URI.

  • Replace project-id with the id of your Google Cloud Platform (GCP) project.

  • Replace location-id with a valid location identifier. Valid location identifiers are: us-west1, us-east1, europe-west1, and asia-east1.

  • Replace product-id with the id for the product that is associated with the images.

GET https://vision.googleapis.com/v1p3beta1/projects/project-id/locations/location-id/products/product-id/referenceImages

If the response contains a nextPageToken, there are more results. You can repeat the request, adding a pageToken parameter with the value of nextPageToken:

GET https://vision.googleapis.com/v1p3beta1/projects/project-id/locations/location-id/products/product-id/referenceImages?pageToken=11

Python

For more on installing and creating a Vision Product Search client, refer to Vision Product Search Client Libraries.

from google.cloud import vision_v1p3beta1 as vision

def list_reference_images(
        project_id, location, product_id):
    """List all images in a product.
    Args:
        project_id: Id of the project.
        location: A compute region name.
        product_id: Id of the product.
    """
    client = vision.ProductSearchClient()

    # Get the full path of the product.
    product_path = client.product_path(
        project=project_id, location=location, product=product_id)

    # List all the reference images available in the product.
    reference_images = client.list_reference_images(parent=product_path)

    # Display the reference image information.
    for image in reference_images:
        print('Reference image name: {}'.format(image.name))
        print('Reference image id: {}'.format(image.name.split('/')[-1]))
        print('Reference image uri: {}'.format(image.uri))
        print('Reference image bounding polygons: {}'.format(
            image.bounding_polys))

Java

For more on installing and creating a Vision Product Search client, refer to Vision Product Search Client Libraries.

/**
 * List all images in a product.
 *
 * @param projectId - Id of the project.
 * @param computeRegion - Region name.
 * @param productId - Id of the product.
 * @throws IOException - on I/O errors.
 */
public static void listReferenceImagesOfProduct(
    String projectId, String computeRegion, String productId) throws IOException {
  ProductSearchClient client = ProductSearchClient.create();

  // Get the full path of the product.
  ProductName productPath = ProductName.of(projectId, computeRegion, productId);

  for (ReferenceImage image : client.listReferenceImages(productPath.toString()).iterateAll()) {
    // Display the reference image information.
    System.out.println(String.format("Reference image name: %s", image.getName()));
    System.out.println(
        String.format(
            "Reference image id: %s",
            image.getName().substring(image.getName().lastIndexOf('/') + 1)));
    System.out.println(String.format("Reference image uri: %s", image.getUri()));
    System.out.println(
        String.format(
            "Reference image bounding polygons: %s \n", image.getBoundingPolysList().toString()));
  }
}

Getting a single image

You can also get a single reference image linked to a product.

Command-line

To get information for a single image, send a GET request to the following URI.

  • Replace project-id with the id of your Google Cloud Platform (GCP) project.

  • Replace location-id with a valid location identifier. Valid location identifiers are: us-west1, us-east1, europe-west1, and asia-east1.

  • Replace product-id with the id for the product that is associated with the image.

  • Replace image-id with the id of the image to get.

GET https://vision.googleapis.com/v1p3beta1/projects/project-id/locations/location-id/products/product-id/referenceImages/image-id

Python

For more on installing and creating a Vision Product Search client, refer to Vision Product Search Client Libraries.

from google.cloud import vision_v1p3beta1 as vision

def get_reference_image(
        project_id, location, product_id, reference_image_id):
    """Get info about a reference image.
    Args:
        project_id: Id of the project.
        location: A compute region name.
        product_id: Id of the product.
        reference_image_id: Id of the reference image.
    """
    client = vision.ProductSearchClient()

    # Get the full path of the reference image.
    reference_image_path = client.reference_image_path(
        project=project_id, location=location, product=product_id,
        reference_image=reference_image_id)

    # Get complete detail of the reference image.
    image = client.get_reference_image(name=reference_image_path)

    # Display the reference image information.
    print('Reference image name: {}'.format(image.name))
    print('Reference image id: {}'.format(image.name.split('/')[-1]))
    print('Reference image uri: {}'.format(image.uri))
    print('Reference image bounding polygons: {}'.format(image.bounding_polys))

Java

For more on installing and creating a Vision Product Search client, refer to Vision Product Search Client Libraries.

/**
 * Get info about a reference image.
 *
 * @param projectId - Id of the project.
 * @param computeRegion - Region name.
 * @param productId - Id of the product.
 * @param referenceImageId - Id of the image.
 * @throws IOException - on I/O errors.
 */
public static void getReferenceImage(
    String projectId, String computeRegion, String productId, String referenceImageId)
    throws IOException {
  ProductSearchClient client = ProductSearchClient.create();

  // Get the full path of the reference image.
  ReferenceImageName referenceImagePath =
      ReferenceImageName.of(projectId, computeRegion, productId, referenceImageId);

  // Get complete detail of the reference image.
  ReferenceImage image = client.getReferenceImage(referenceImagePath);

  // Display the reference image information.
  System.out.println(String.format("Reference image name: %s", image.getName()));
  System.out.println(
      String.format(
          "Reference image id: %s",
          image.getName().substring(image.getName().lastIndexOf('/') + 1)));
  System.out.println(String.format("Reference image uri: %s", image.getUri()));
  System.out.println(
      String.format(
          "Reference image bounding polygons: %s \n", image.getBoundingPolysList().toString()));
}

Updating resources

Updating a product

You can update a product's labels via key-value pairs, such as style=women's or onSale=true, using the following code.

Command-line

To update a product, send a PATCH request to the following URI.

  • Replace project-id with the id of your Google Cloud Platform (GCP) project.

  • Replace location-id with a valid location identifier. Valid location identifiers are: us-west1, us-east1, europe-west1, and asia-east1.

  • Replace product-id with the id for the product to update.

PATCH https://vision.googleapis.com/v1p3beta1/projects/project-id/locations/location-id/products/product-id
{
    'updateMask': { 'paths': ['display_name'] }
   'product': { 'display_name': 'new-display-name' },
}

Python

For more on installing and creating a Vision Product Search client, refer to Vision Product Search Client Libraries.

from google.cloud import vision_v1p3beta1 as vision

def update_product_labels(
        project_id, location, product_id, key, value):
    """Update the product labels.
    Args:
        project_id: Id of the project.
        location: A compute region name.
        product_id: Id of the product.
        key: The key of the label.
        value: The value of the label.
    """
    client = vision.ProductSearchClient()

    # Get the name of the product.
    product_path = client.product_path(
        project=project_id, location=location, product=product_id)

    # Set product name, product label and product display name.
    # Multiple labels are also supported.
    key_value = vision.types.Product.KeyValue(key=key, value=value)
    product = vision.types.Product(
        name=product_path,
        product_labels=[key_value])

    # Updating only the product_labels field here.
    update_mask = vision.types.FieldMask(paths=['product_labels'])

    # This overwrites the product_labels.
    updated_product = client.update_product(
        product=product, update_mask=update_mask)

    # Display the updated product information.
    print('Product name: {}'.format(updated_product.name))
    print('Updated product labels: {}'.format(product.product_labels))

Java

For more on installing and creating a Vision Product Search client, refer to Vision Product Search Client Libraries.

/**
 * Update the product labels.
 *
 * @param projectId - Id of the project.
 * @param computeRegion - Region name.
 * @param productId -Id of the product.
 * @param productLabels - Labels of the product.
 * @throws IOException - on I/O errors.
 */
public static void updateProductLabels(
    String projectId, String computeRegion, String productId, String productLabels)
    throws IOException {
  ProductSearchClient client = ProductSearchClient.create();

  // Get the full path of the product.
  String productPath = ProductName.of(projectId, computeRegion, productId).toString();

  // Set product name, product labels and product display name.
  // Multiple labels are also supported.
  Product product =
      Product.newBuilder()
          .setName(productPath)
          .addProductLabels(
              KeyValue.newBuilder()
                  .setKey(productLabels.split(",")[0].split("=")[0])
                  .setValue(productLabels.split(",")[0].split("=")[1])
                  .build())
          .build();

  // Set product update field name.
  FieldMask updateMask = FieldMask.newBuilder().addPaths("product_labels").build();

  // Update the product.
  Product updatedProduct = client.updateProduct(product, updateMask);

  // Display the product information
  System.out.println(String.format("Product name: %s", updatedProduct.getName()));
  System.out.println(
      String.format(
          "Updated product labels: %s", updatedProduct.getProductLabelsList().toString()));
}

Deleting resources

Deleting images

You can delete a reference image associated with a product.

Command-line

To delete a single image, send a DELETE request to the following URI.

  • Replace project-id with the id of your Google Cloud Platform (GCP) project.

  • Replace location-id with a valid location identifier. Valid location identifiers are: us-west1, us-east1, europe-west1, and asia-east1.

  • Replace product-id with the id for the product that is associated with the image.

  • Replace image-id with the id of the image to delete.

DELETE https://vision.googleapis.com/v1p3beta1/projects/project-id/locations/location-id/products/product-id/referenceImages/image-id

The images are marked for deletion, but will remain in the product until the next time it is indexed.

The actual image files in Google Cloud Storage are NOT deleted by this operation. Only the reference to the image is removed from the product.

Python

For more on installing and creating a Vision Product Search client, refer to Vision Product Search Client Libraries.

from google.cloud import vision_v1p3beta1 as vision

def delete_reference_image(
        project_id, location, product_id, reference_image_id):
    """Delete a reference image.
    Args:
        project_id: Id of the project.
        location: A compute region name.
        product_id: Id of the product.
        reference_image_id: Id of the reference image.
    """
    client = vision.ProductSearchClient()

    # Get the full path of the reference image.
    reference_image_path = client.reference_image_path(
        project=project_id, location=location, product=product_id,
        reference_image=reference_image_id)

    # Delete the reference image.
    client.delete_reference_image(name=reference_image_path)
    print('Reference image deleted from product.')

Java

For more on installing and creating a Vision Product Search client, refer to Vision Product Search Client Libraries.

/**
 * Delete a reference image.
 *
 * @param projectId - Id of the project.
 * @param computeRegion - Region name.
 * @param productId - Id of the product.
 * @param referenceImageId - Id of the image.
 * @throws IOException - on I/O errors.
 */
public static void deleteReferenceImage(
    String projectId, String computeRegion, String productId, String referenceImageId)
    throws IOException {
  ProductSearchClient client = ProductSearchClient.create();

  // Get the full path of the reference image.
  ReferenceImageName referenceImagePath =
      ReferenceImageName.of(projectId, computeRegion, productId, referenceImageId);

  // Delete the reference image.
  client.deleteReferenceImage(referenceImagePath.toString());
  System.out.println("Reference image deleted from product.");
}

Deleting a product

You can delete a product associated with a specific project.

Deleting a Product causes its child images to be deleted.

Command-line

To delete a single product, send a DELETE request to the following URI.

  • Replace project-id with the id of your Google Cloud Platform (GCP) project.

  • Replace location-id with a valid location identifier. Valid location identifiers are: us-west1, us-east1, europe-west1, and asia-east1.

  • Replace product-id with the id for the product that is associated with the image.

DELETE https://vision.googleapis.com/v1p3beta1/projects/project-id/locations/location-id/products/product-id

Python

For more on installing and creating a Vision Product Search client, refer to Vision Product Search Client Libraries.

from google.cloud import vision_v1p3beta1 as vision

def delete_product(project_id, location, product_id):
    """Delete the product and all its reference images.
    Args:
        project_id: Id of the project.
        location: A compute region name.
        product_id: Id of the product.
    """
    client = vision.ProductSearchClient()

    # Get the full path of the product.
    product_path = client.product_path(
        project=project_id, location=location, product=product_id)

    # Delete a product.
    client.delete_product(name=product_path)
    print('Product deleted.')

Java

For more on installing and creating a Vision Product Search client, refer to Vision Product Search Client Libraries.

/**
 * Delete the product and all its reference images.
 *
 * @param projectId - Id of the project.
 * @param computeRegion - Region name.
 * @param productId - Id of the product.
 * @throws IOException - on I/O errors.
 */
public static void deleteProduct(String projectId, String computeRegion, String productId)
    throws IOException {
  ProductSearchClient client = ProductSearchClient.create();

  // Get the full path of the product.
  ProductName productPath = ProductName.of(projectId, computeRegion, productId);

  // Delete a product.
  client.deleteProduct(productPath);

  System.out.println("Product deleted.");
}

Deleting a product set

You can also delete an entire product set and all the images contained in it.

Deleting a product set immediately removes the product set from results. You do not need to wait for the next index for the change to take effect.

The actual image files in Google Cloud Storage are NOT deleted by this operation. ReferenceImage resources created by the API are not removed.

Command-line

To delete a product set and all of the images it contains, send a DELETE request to the following URI.

  • Replace project-id with the id of your Google Cloud Platform (GCP) project.

  • Replace location-id with a valid location identifier. Valid location identifiers are: us-west1, us-east1, europe-west1, and asia-east1.

  • Replace product-set-id with the id for the product that is associated with the image.

DELETE https://vision.googleapis.com/v1p3beta1/projects/project-id/locations/location-id/productSets/product-set-id

Python

For more on installing and creating a Vision Product Search client, refer to Vision Product Search Client Libraries.

from google.cloud import vision_v1p3beta1 as vision

def delete_product_set(project_id, location, product_set_id):
    """Delete a product set.
    Args:
        project_id: Id of the project.
        location: A compute region name.
        product_set_id: Id of the product set.
    """
    client = vision.ProductSearchClient()

    # Get the full path of the product set.
    product_set_path = client.product_set_path(
        project=project_id, location=location,
        product_set=product_set_id)

    # Delete the product set.
    client.delete_product_set(name=product_set_path)
    print('Product set deleted.')

Java

For more on installing and creating a Vision Product Search client, refer to Vision Product Search Client Libraries.

/**
 * Delete a product set.
 *
 * @param projectId - Id of the project.
 * @param computeRegion - Region name.
 * @param productSetId - Id of the product set.
 * @throws IOException - on I/O errors.
 */
public static void deleteProductSet(
    String projectId, String computeRegion, String productSetId) throws IOException {
  ProductSearchClient client = ProductSearchClient.create();

  // Get the full path of the product set.
  ProductSetName productSetPath = ProductSetName.of(projectId, computeRegion, productSetId);

  // Delete the product set.
  client.deleteProductSet(productSetPath.toString());

  System.out.println(String.format("Product set deleted"));
}

Was this page helpful? Let us know how we did:

Send feedback about...

Cloud Vision API