Google Taxonomy

The Google Taxonomy API provides access to the full Google Product Category taxonomy. Use it to search categories by keyword and to get AI-powered category suggestions based on product attributes. Categories are used for product feeds, advertising platforms, and marketplace listings.

Base URL: https://api.hydrajs.dev

Endpoints

Method	Path	Auth	Description
GET	/v1/google-taxonomy	Publishable	Search Google product categories
POST	/v1/google-taxonomy/suggest	Secret	AI-suggest product categories

---

Search Google product categories

GET /v1/google-taxonomy

Searches the Google Product Taxonomy by keyword. Returns matching category paths with IDs and hierarchy information. When no search query is provided, returns the first limit categories.

Query parameters

Parameter	Type	Default	Description
q	string	-	Search keyword (1-100 chars). Matches against the full category path
limit	integer	50	Max results (1-100)

Request

curl "https://api.hydrajs.dev/v1/google-taxonomy?q=shirts&limit=10" \
  -H "Authorization: Bearer pk_live_YOUR_KEY"

Response 200

{
	"data": [
		{
			"id": 212,
			"path": "Apparel & Accessories > Clothing > Shirts & Tops",
			"parent_path": "Apparel & Accessories > Clothing",
			"level": 3
		},
		{
			"id": 5388,
			"path": "Apparel & Accessories > Clothing > Shirts & Tops > T-Shirts",
			"parent_path": "Apparel & Accessories > Clothing > Shirts & Tops",
			"level": 4
		}
	]
}

---

AI-suggest product categories

POST /v1/google-taxonomy/suggest

Uses AI to suggest the most relevant Google Product Categories for a product based on its attributes. Returns up to 3 suggestions, each with the full category path and a reason explaining why it was chosen.

The AI pre-filters taxonomy candidates using keywords from the product data, then selects the most specific matching categories from the filtered set.

Request body

Field	Type	Required	Description
title	string	Yes	Product title (1-255 chars)
description	string	No	Product description (max 10,000 chars)
product_type	string	No	Free-text product type (max 100 chars)
brand	string	No	Brand name (max 100 chars)
tags	string[]	No	Product tags (max 250)
specifications	object[]	No	Key-value specs. Each: { label, value }
variant_title	string	No	Variant title for context (max 255 chars)

Request

curl -X POST https://api.hydrajs.dev/v1/google-taxonomy/suggest \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Classic Cotton T-Shirt",
    "product_type": "Apparel",
    "brand": "Hydra Basics",
    "tags": ["cotton", "basics", "summer"],
    "specifications": [
      { "label": "Material", "value": "100% Cotton" },
      { "label": "Weight", "value": "180 GSM" }
    ]
  }'

Response 200

{
	"data": [
		{
			"path": "Apparel & Accessories > Clothing > Shirts & Tops",
			"reason": "Cotton t-shirt matches the shirts and tops category"
		},
		{
			"path": "Apparel & Accessories > Clothing > Shirts & Tops > T-Shirts",
			"reason": "Specific t-shirt subcategory for better feed targeting"
		},
		{
			"path": "Apparel & Accessories > Clothing",
			"reason": "Broader apparel category as fallback"
		}
	]
}

---

The taxonomy category object

Field	Type	Description
id	integer	Google taxonomy category ID
path	string	Full category path (e.g. Apparel & Accessories > Clothing > Shirts & Tops)
parent_path	string | null	Parent category path. null for top-level categories
level	integer	Depth in the taxonomy tree (1 = top-level)

The taxonomy suggestion object

Field	Type	Description
path	string	Suggested Google Product Category path
reason	string	Brief explanation of why this category was suggested