Creating and managing your product resources

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-v2, apparel-v2, toys-v2, packagedgoods-v1, and general-v1 *.

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

You can use online import to create an individual product. After a product is created you can then add a reference image to it or add it to one or more product sets.

REST & CMD LINE

Before using any of the request data, make the following replacements:

  • PROJECT_ID: Your GCP project ID.
  • LOCATION_ID: A valid location identifier. Valid location identifiers are: us-west1, us-east1, europe-west1, and asia-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, and general-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 called request.json, and execute the following command: 

curl -X POST \
-H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \
-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 called request.json, and execute the following command: 

$cred = gcloud auth application-default print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

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


import (
	"context"
	"fmt"
	"io"

	vision "cloud.google.com/go/vision/apiv1"
	visionpb "google.golang.org/genproto/googleapis/cloud/vision/v1"
)

// createProduct creates a product.
func createProduct(w io.Writer, projectID string, location string, productID string, productDisplayName string, productCategory string) error {
	ctx := context.Background()
	c, err := vision.NewProductSearchClient(ctx)
	if err != nil {
		return fmt.Errorf("NewProductSearchClient: %v", err)
	}
	defer c.Close()

	req := &visionpb.CreateProductRequest{
		Parent:    fmt.Sprintf("projects/%s/locations/%s", projectID, location),
		ProductId: productID,
		Product: &visionpb.Product{
			DisplayName:     productDisplayName,
			ProductCategory: productCategory,
		},
	}

	resp, err := c.CreateProduct(ctx, req)
	if err != nil {
		return fmt.Errorf("CreateProduct: %v", err)
	}

	fmt.Fprintf(w, "Product name: %s\n", resp.Name)

	return nil
}

Java

/**
 * 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.
 * @throws IOException - on I/O errors.
 */
public static void createProduct(
    String projectId,
    String computeRegion,
    String productId,
    String productDisplayName,
    String productCategory)
    throws IOException {
  try (ProductSearchClient client = ProductSearchClient.create()) {

    // A resource that represents Google Cloud Platform location.
    String formattedParent = ProductSearchClient.formatLocationName(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)
            .build();
    Product product = client.createProduct(formattedParent, myProduct, productId);
    // Display the product information
    System.out.println(String.format("Product name: %s", product.getName()));
  }
}

Node.js

// Imports the Google Cloud client library
const vision = require('@google-cloud/vision');

// Creates a client
const client = new vision.ProductSearchClient();
async function createProduct() {
  /**
   * TODO(developer): Uncomment the following line before running the sample.
   */
  // const projectId = 'Your Google Cloud project Id';
  // const location = 'A compute region name';
  // const productId = 'Id of the product';
  // const productDisplayName = 'Display name of the product';
  // const productCategory = 'Catoegory of the product';

  // Resource path that represents Google Cloud Platform location.
  const locationPath = client.locationPath(projectId, location);

  const product = {
    displayName: productDisplayName,
    productCategory: productCategory,
  };

  const request = {
    parent: locationPath,
    product: product,
    productId: productId,
  };

  const [createdProduct] = await client.createProduct(request);
  console.log(`Product name: ${createdProduct.name}`);
}
createProduct();

Python

from google.cloud import vision
from google.protobuf import field_mask_pb2 as field_mask

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 = f"projects/{project_id}/locations/{location}"

    # Create a product with the product specification in the region.
    # Set product display name and product category.
    product = vision.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))

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.

Adding a product to a product set

When you have a product and product set available you can then add the product to the product set.

REST & CMD LINE

Before using any of the request data, make the following replacements:

  • PROJECT_ID: Your GCP project ID.
  • LOCATION_ID: A valid location identifier. Valid location identifiers are: us-west1, us-east1, europe-west1, and asia-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 called request.json, and execute the following command: 

curl -X POST \
-H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \
-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 called request.json, and execute the following command: 

$cred = gcloud auth application-default print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

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


import (
	"context"
	"fmt"
	"io"

	vision "cloud.google.com/go/vision/apiv1"
	visionpb "google.golang.org/genproto/googleapis/cloud/vision/v1"
)

// addProductToProductSet adds a product to a product set.
func addProductToProductSet(w io.Writer, projectID string, location string, productID string, productSetID string) error {
	ctx := context.Background()
	c, err := vision.NewProductSearchClient(ctx)
	if err != nil {
		return fmt.Errorf("NewProductSearchClient: %v", err)
	}
	defer c.Close()

	req := &visionpb.AddProductToProductSetRequest{
		Name:    fmt.Sprintf("projects/%s/locations/%s/productSets/%s", projectID, location, productSetID),
		Product: fmt.Sprintf("projects/%s/locations/%s/products/%s", projectID, location, productID),
	}

	if err = c.AddProductToProductSet(ctx, req); err != nil {
		return fmt.Errorf("NewProductSearchClient: %v", err)
	}

	fmt.Fprintf(w, "Product added to product set.\n")

	return nil
}

Java

/**
 * 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 addProductToProductSet(
    String projectId, String computeRegion, String productId, String productSetId)
    throws IOException {
  try (ProductSearchClient client = ProductSearchClient.create()) {

    // Get the full path of the product set.
    String formattedName =
        ProductSearchClient.formatProductSetName(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(formattedName, productPath);

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

Node.js

const vision = require('@google-cloud/vision');
const client = new vision.ProductSearchClient();

async function addProductToProductSet() {
  /**
   * TODO(developer): Uncomment the following line before running the sample.
   */
  // const projectId = 'Your Google Cloud project Id';
  // const location = 'A compute region name';
  // const productId = 'Id of the product';
  // const productSetId = 'Id of the product set';

  const productPath = client.productPath(projectId, location, productId);
  const productSetPath = client.productSetPath(
    projectId,
    location,
    productSetId
  );

  const request = {
    name: productSetPath,
    product: productPath,
  };

  await client.addProductToProductSet(request);
  console.log('Product added to product set.');
}
addProductToProductSet();

Python

from google.cloud import 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.')

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.

Removing a product from a product set

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

REST & CMD LINE

Before using any of the request data, make the following replacements:

  • PROJECT_ID: Your GCP project ID.
  • LOCATION_ID: A valid location identifier. Valid location identifiers are: us-west1, us-east1, europe-west1, and asia-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:removeProduct

Request JSON body: 

{
  "product": "product-name"
}

To send your request, choose one of these options:

curl

Save the request body in a file called request.json, and execute the following command: 

curl -X POST \
-H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \
-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:removeProduct"

PowerShell

Save the request body in a file called request.json, and execute the following command: 

$cred = gcloud auth application-default print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

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:removeProduct" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

{}

Go


import (
	"context"
	"fmt"
	"io"

	vision "cloud.google.com/go/vision/apiv1"
	visionpb "google.golang.org/genproto/googleapis/cloud/vision/v1"
)

// removeProductFromProductSet removes a product from a product set.
func removeProductFromProductSet(w io.Writer, projectID string, location string, productID string, productSetID string) error {
	ctx := context.Background()
	c, err := vision.NewProductSearchClient(ctx)
	if err != nil {
		return fmt.Errorf("NewProductSearchClient: %v", err)
	}
	defer c.Close()

	req := &visionpb.RemoveProductFromProductSetRequest{
		Name:    fmt.Sprintf("projects/%s/locations/%s/productSets/%s", projectID, location, productSetID),
		Product: fmt.Sprintf("projects/%s/locations/%s/products/%s", projectID, location, productID),
	}

	if err = c.RemoveProductFromProductSet(ctx, req); err != nil {
		return fmt.Errorf("NewProductSearchClient: %v", err)
	}

	fmt.Fprintf(w, "Product removed from product set.\n")

	return nil
}

Java

/**
 * 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 {
  try (ProductSearchClient client = ProductSearchClient.create()) {

    // Get the full path of the product set.
    String formattedParent =
        ProductSearchClient.formatProductSetName(projectId, computeRegion, productSetId);

    // Get the full path of the product.
    String formattedName =
        ProductSearchClient.formatProductName(projectId, computeRegion, productId);

    // Remove the product from the product set.
    client.removeProductFromProductSet(formattedParent, formattedName);

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

Node.js

const vision = require('@google-cloud/vision');

const client = new vision.ProductSearchClient();

async function removeProductFromProductSet() {
  /**
   * TODO(developer): Uncomment the following line before running the sample.
   */
  const productSetPath = client.productSetPath(
    projectId,
    location,
    productSetId
  );

  const productPath = client.productPath(projectId, location, productId);

  const request = {
    name: productSetPath,
    product: productPath,
  };

  await client.removeProductFromProductSet(request);
  console.log('Product removed from product set.');
}
removeProductFromProductSet();

Python

from google.cloud import 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.')

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.