Stay organized with collections
Save and categorize content based on your preferences.
You can use the import
method to create a product set and products with reference images all at the
same time using a CSV file. This page describes how to format the CSV file.
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 (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.
CSV formatting guidelines
To use the import method, both the CSV file and the images it points to
must be in a Cloud Storage bucket. CSV files are limited to a maximum of
20,000 lines; each line is limited to a maximum of 2,048 characters. To import
more images, split them into multiple CSV files.
The CSV file must contain one image per line and contain the following columns:
image-uri: The Cloud Storage URI of the reference image.
image-id: Optional. A unique value if you supply it. Otherwise, the
system will assign a unique value.
product-set-id: A unique identifier for the product set to import the
images into.
product-id: A user-defined ID for the product identified by the reference
image. A product-id can be associated with multiple reference images.
product-category: Allowed values are homegoods-v2, apparel-v2,
toys-v2, packagedgoods-v1,
and general-v1
*;
the category for the product identified by the
reference image. Inferred by the system if not specified in the create
request.
Allowed values are also listed in the
productCategory
reference documentation.
product-display-name: Optional. If you don't provide a name for
the product displayName
will be set to " ". You can update this value later.
labels: Optional. A string (with quotation marks) of key-value
pairs that describe the products in the reference image. For example:
"category=shoes"
"color=black,style=formal"
Vision API Product Search also allows you to provide multiple values for
a single key. For example:
"category=shoes,category=heels"
"color=black,style=formal,style=mens"
bounding-poly: Optional. Specifies the area of interest in the
reference image. If a bounding box is not specified:
Bounding boxes for the image are inferred by the Vision API; multiple
regions in a single image may be indexed if multiple products are
detected by the API.
The line must end with a comma.
See the example below for a product without a bounding poly specified.
If you include a bounding box, 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. An example
line looks like this: 0.1,0.1,0.9,0.1,0.9,0.9,0.1,0.9.
To define a bounding box with the actual pixel values of your image use
non-negative integers. Thus, you could express bounding boxes in 1000 pixel
by 1000 pixel images in the following way:
Vision API Product Search also allows you to use normalized values for
bounding boxes. Define a bounding box using normalized values with float
values in [0, 1].
Using normalized values, the above reference image rows could also be
expressed as:
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Hard to understand","hardToUnderstand","thumb-down"],["Incorrect information or sample code","incorrectInformationOrSampleCode","thumb-down"],["Missing the information/samples I need","missingTheInformationSamplesINeed","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-08-28 UTC."],[],[],null,["# Formatting a bulk import CSV\n\nYou can use the [`import`](/vision/product-search/docs/reference/rest/v1/projects.locations.productSets/import)\nmethod to create a product set and products with reference images all at the\nsame time using a CSV file. This page describes how to format the CSV file.\n\nCreating your reference images\n------------------------------\n\nReference images are images containing various views of your products. The\nfollowing recommendations apply:\n\n- Make sure the size of the file doesn't exceed the maximum size (20MB).\n- Consider viewpoints that logically highlight the product and contain relevant visual information.\n- 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.\n- Upload the highest resolution image available.\n- Show the product against a white background.\n- Convert PNGs with transparent backgrounds to a solid background.\n\nImages must be stored in a [Cloud Storage](https://cloud.google.com/storage/)\nbucket. If you're authenticating your image create call with an API key, the bucket must be\npublic. If you're authenticating with a service account, that service account\nmust have read access on the bucket.\n\nCSV formatting guidelines\n-------------------------\n\nTo use the `import` method, both the CSV file *and* the images it points to\nmust be in a Cloud Storage bucket. CSV files are limited to a maximum of\n20,000 lines; each line is limited to a maximum of 2,048 characters. To import\nmore images, split them into multiple CSV files.\n\nThe CSV file must contain one image per line and contain the following columns:\n\n1. `image-uri`: The Cloud Storage URI of the reference image.\n2. `image-id`: ***Optional***. A unique value if you supply it. Otherwise, the system will assign a unique value.\n3. `product-set-id`: A unique identifier for the product set to import the images into.\n4. `product-id`: A user-defined ID for the product identified by the reference\n image. A `product-id` can be associated with multiple reference images.\n\n | **Note:** A single product may also belong to several product sets. If a `product-id` already exists on bulk import then `product-category`, `product-display`, and `labels` are ignored for that line entry.\n5. `product-category`: Allowed values are `homegoods-v2`, `apparel-v2`,\n `toys-v2`, `packagedgoods-v1`,\n and `general-v1`\n \\*;\n the category for the product identified by the\n reference image. Inferred by the system if not specified in the create\n request.\n Allowed values are also listed in the\n [`productCategory`](/vision/product-search/docs/reference/rest/v1/projects.locations.products#Product.FIELDS.product_category)\n reference documentation.\n\n \u003cbr /\u003e\n\n | **\\* Legacy `productCategory` codes:** Legacy categories (`homegoods`, `apparel`, and `toys`) are still supported, but the updated `-v2` categories should be used for new products.\n\n \u003cbr /\u003e\n\n6. `product-display-name`: ***Optional*** . If you don't provide a name for\n the product [`displayName`](/vision/product-search/docs/reference/rest/v1/projects.locations.products#Product.FIELDS.display_name)\n will be set to \" \". You can [update](/vision/product-search/docs/reference/rest/v1/projects.locations.products/patch) this value later.\n\n7. `labels`: ***Optional***. A string (with quotation marks) of key-value\n pairs that describe the products in the reference image. For example:\n\n - `\"category=shoes\"`\n - `\"color=black,style=formal\"`\n\n Vision API Product Search also allows you to provide multiple values for\n a single key. For example:\n - `\"category=shoes,category=heels\"`\n\n - `\"color=black,style=formal,style=mens\"`\n\n8. `bounding-poly`: ***Optional*** . Specifies the area of interest in the\n reference image. If a bounding box is **not** specified:\n\n 1. Bounding boxes for the image are inferred by the Vision API; multiple regions in a single image may be indexed if multiple products are detected by the API.\n 2. The line must end with a comma.\n\n See the example below for a product without a bounding poly specified.\n\n If you include a bounding box, the `boundingPoly` column should contain\n an even number of comma-separated numbers, with the format\n `p1_x,p1_y,p2_x,p2_y,...,pn_x,pn_y`. An example\n line looks like this: `0.1,0.1,0.9,0.1,0.9,0.9,0.1,0.9`.\n\n To define a bounding box with the actual pixel values of your image use\n non-negative integers. Thus, you could express bounding boxes in 1000 pixel\n by 1000 pixel images in the following way: \n\n gs://example-reference-images/10001-001/10001-001_A.jpg,img001,sample-set-summer,sample-product-123,tan summer bag,apparel-v2,\"style=womens,color=tan\",100,150,450,150,450,550,100,550\n gs://example-reference-images/10001-001/10001-001_A.jpg,img001,sample-set-summer,sample-product-456,blue summer bag,apparel-v2,\"style=womens,color=blue\",670,790,980,790,980,920,670,920\n gs://example-reference-images/10002-002/10002-002_B.jpg,img002,sample-set-summer,sample-product-123,apparel-v2,,,\n\n | **Note:** You can use Vision API's [Object Localizer](/vision/docs/detecting-objects) feature to get bounding box coordinates for generalized objects in images.\n\n Vision API Product Search also allows you to use normalized values for\n bounding boxes. Define a bounding box using normalized values with float\n values in \\[0, 1\\].\n\n Using normalized values, the above reference image rows could also be\n expressed as: \n\n gs://example-reference-images/10001-001/10001-001_A.jpg,img001,sample-set-summer,sample-product-123,tan summer bag,apparel-v2,\"style=womens,color=tan\",0.10,0.15,0.45,0.15,0.45,0.55,0.10,0.55\n gs://example-reference-images/10001-001/10001-001_A.jpg,img001,sample-set-summer,sample-product-456,blue summer bag,apparel-v2,\"style=womens,color=blue\",0.67,0.79,0.98,0.79,0.98,0.92,0.67,0.92\n gs://example-reference-images/10002-002/10002-002_B.jpg,img002,sample-set-summer,sample-product-123,apparel-v2,,,"]]