Return to homepage

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 websites.

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

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.

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

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.