Introduction to Product Categorization API

Our product categorization API is one of the most accurate e-commerce categorisation AI services on the market, used by a wide range of clients, including Unicorn startups, multinational companies, online stores, ecommerce analytics platforms, adTech companies and many others.

Our API categorizes texts according to Google Shopping Taxonomy with 5574 categories.

We also offer additional customized classifiers, adapted to your own list of categories or to other standard taxonomies, such as Amazon Shopping Categories.

Our API can be used with texts as well as images.

Authentication

All requests should be made to endpoints that start with: https://www.productcategorization.com/api/

You need an API key to access our API endpoints and can obtain it by purchasing subscription to one of our plans. After obtaining plan, please login to retrieve your API key.

Our API service expects for the API key to be included in all API requests to the server, as parameter:

api_key: b4dade2ce5fb2d0b189b5eb6f0cd

You must replace b4dade2ce5fb2d0b189b5eb6f0cd with your own API key, obtained upon purchasing one of our plans.

HTTP responses that are successful will have the status code 200 and the response formatted according to specification, please see documentation for examples.

Our servers return API data in JSON format by default.

Rules and limits

Default rate limit is set at 60 requests per minute. If you need a higher rate limit, please send us an email and we will increase your rate limit to the desired value.

The API returns both your total credits (under total_credits) as well as your remaining credits (under remaining_credits).

Pay attention to the number of API credits you still have remaining. If you exhaust your credits you can purchase them at our pricing page or upgrade your plan. API call for text costs 1 API credit. API call for image costs 10 API credits.

Product Categorization of Texts

Our categorization API classifies texts into one of 5574 possible categories. See list of categories here.

The classifier also returns 10 buyer personas it thinks are most likely to be interested in the product. Buyer personas are selected from our own taxonomy of 1820 buyer personas, see list of buyer personas here.

Example of requests:

GET Request

To run your API request copy paste the following command and make sure to replace your_api_key with your own API key:

https://www.productcategorization.com/api/ecommerce/ecommerce_category6_get.php?query=Fluorescent Highlighters 3pc Yellow &api_key=your_api_key You can also pass your API key in header: curl -X GET "https://www.productcategorization.com/api/ecommerce/ecommerce_category6_get_bearer.php?query=your_query&classification_language=en" \ -H "X-API-KEY: api"

Query Parameters

Parameter	Type	Description
query	string	text to be categorized
api_key	string	API key
classification_language (optional)	string	desired language of classification (set e.g. to 'fr' to obtain French taxonomy classification, in addition to English one)

The above command returns response in JSON format, structured like this:

{"language":"en","total_credits":720012,"remaining_credits":719490,"classification":"Office Supplies > Office
Instruments > Writing & Drawing Instruments > Markers & Highlighters > Highlighters", "buyer_personas":["Organized Individual","Art and Craft Enthusiast","Innovative Inventor","Detail-Oriented
Professional","Strategic Sketcher","Productive Professional","Creative Professional","Diligent Professional","Efficient
Administrator","Professional Planner"],"ID":"543609","status":200}

Curl Request

To run your API request with Curl, copy paste the following command and make sure to replace your_api_key with your own API key:

curl --request GET 'https://www.productcategorization.com/api/ecommerce/ecommerce_category6_get.php?query=Fluorescent Highlighters 3pc Yellow &api_key=kHtEmSj&classification_language=fr'

Note that we used optional parameter classification_language to obtain French taxonomy classification, in addition to English one.

The above command returns response in JSON format, structured like this:

{"language":"en","total_credits":720012,"remaining_credits":719486,"classification":"Office Supplies > Office
Instruments > Writing & Drawing Instruments > Markers & Highlighters > Highlighters","classification_fr":"Fournitures de
bureau > Instruments de bureau > Instruments d'écriture et de dessin > Marqueurs et surligneurs >
Surligneurs","buyer_personas":["Organized Individual","Art and Craft Enthusiast","Innovative Inventor","Detail-Oriented
Professional","Strategic Sketcher","Productive Professional","Creative Professional","Diligent Professional","Efficient
Administrator","Professional Planner"],"ID":"543609","status":200}

Example code

Below you can find minimal example code for using our API, for different programming languages.

Example code in Python

 
from urllib.parse import quote_plus     

import requests     


     
api_base_url = "https://www.productcategorization.com/api/ecommerce/ecommerce_category6_get.php?"     

api_key = "your api key"     

query_text = "Fluorescent Highlighters 3pc Yellow "     

classification_language = "fr"      # use this if you want classification in additional languages, set e.g. to "fr" to obtain French taxonomy classification, in addition to English one     

encoded_query_text = quote_plus(query_text)     

final_url = f"{api_base_url}query={encoded_query_text}&api_key={api_key}&classification_language={classification_language}"     

response = requests.get(final_url)     

print(response.text)

Example code in Javascript

 
const apiBaseUrl = "https://www.productcategorization.com/api/ecommerce/ecommerce_category6_get.php?"; 

const apiKey = "your api key"; 

const queryText = "Fluorescent Highlighters 3pc Yellow "; 

const classificationLanguage = "fr"; // Use this if you want classification in additional languages 



const encodedQueryText = encodeURIComponent(queryText); 

const finalUrl = `${apiBaseUrl}query=${encodedQueryText}&api_key=${apiKey}&classification_language=${classificationLanguage}`; 



fetch(finalUrl) 

  .then(response => response.text()) 

  .then(data => { 

    console.log(data); 

  }) 

  .catch((error) => console.error('Error:', error));

Errors

The API returns a status value in each request. Example of status returned as 200:

{"classification": "status": 200, ....}

In case of error, the status error code can be interpreted using the following table:

Error Code	Meaning
200	Request was successful.
400	Error in forming request. Please check documentation on how to form an API request.
401	Your API key is invalid. You need to purchase a subscription to use this service. If you have a paid plan, please check your API key for potential misspelling. If the problem persists please contact us via email.
403	You have used up your monthly quota for API requests. Please upgrade your plan to one that includes more API requests per month. Alternatively, add credits to your account.