Introduction to Product Categorization API

Our product categorization API is one of the most accurate e-commerce categorization 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
• Shopify Taxonomy (latest version) with around 11k categories (GitHub Link)
• Other taxonomies, such as Amazon Shopping Categories

We also offer additional customized classifiers, adapted to your own list of categories or to other standard taxonomies.

In addition to product categorization, our Shopify API can also return Shopify Attributes based on product images. Attributes can help improve user search experience and rankings on search engines.

Example of Shopify attributes in this screenshot from our dashboard (same results are available via API):

Our API can be used with both texts and 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. You can obtain it by purchasing a subscription . After obtaining a plan, please log in to retrieve your API key.

Our API service expects the API key to be included in all requests as a parameter:
api_key: b4dade2ce5fb2d0b189b5eb6f0cd

HTTP responses that are successful have status code 200. Our servers return API data in JSON format by default.

Rules and limits

Default rate limit: 60 requests per minute. If you need a higher rate limit, please contact us.

The API returns both your total credits (total_credits) and your remaining credits (remaining_credits). Pay attention to your remaining credits. If you exhaust them, you can purchase more or upgrade your plan.

API cost:

• 1 credit per text-based API call
• 10 credits per image-based API call

Product Categorization of Texts

Our categorization API classifies texts based on either Google Shopping Taxonomy or Shopify Taxonomy.
Google Shopping categories (extended)
Shopify categories

The classifier also returns 10 buyer personas from our own taxonomy of 1820 buyer personas (see list here ).

Example of a request:

GET Request

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 the header:

            
              
            

curl -X GET "https://www.productcategorization.com/api/ecommerce/ecommerce_category6_get_bearer.php?query=your_query" \
     -H "X-API-KEY: api"

          

Query Parameters

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

Use Curl with your API key to get the classification:

            
              
            

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

          

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 are minimal code examples for making requests to our API in different programming languages.

Example Code in Python

            
              
            

import requests
from urllib.parse import quote_plus

api_base_url = "https://www.productcategorization.com/api/ecommerce/ecommerce_category6_get.php?"
api_key = "your_api_key"
query_text = "Fluorescent Highlighters 3pc Yellow"

encoded_query_text = quote_plus(query_text)
final_url = f"{api_base_url}query={encoded_query_text}&api_key={api_key}"

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 encodedQueryText = encodeURIComponent(queryText);

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

fetch(finalUrl)
  .then(response => response.json())
  .then(data => {
    console.log(data);
  })
  .catch(error => console.error('Error:', error));

          

Example Code in Ruby

            
              
            

require 'uri'
require 'net/http'

api_base_url = "https://www.productcategorization.com/api/ecommerce/ecommerce_category6_get.php"
api_key = "your_api_key"
query_text = "Fluorescent Highlighters 3pc Yellow"

encoded_query = URI.encode_www_form_component(query_text)
url = URI("#{api_base_url}?query=#{encoded_query}&api_key=#{api_key}")

response = Net::HTTP.get(url)
puts response

          

Example Code in PHP

            
              
            



$api_base_url = "https://www.productcategorization.com/api/ecommerce/ecommerce_category6_get.php";
$api_key = "your_api_key";
$query_text = "Fluorescent Highlighters 3pc Yellow";

$query_text_encoded = urlencode($query_text);
$final_url = $api_base_url . "?query=" . $query_text_encoded . "&api_key=" . $api_key;

$response = file_get_contents($final_url);
echo $response;



          

Example Code in C#

            
              
            

using System;
using System.Net.Http;
using System.Threading.Tasks;

class Program {
    static async Task Main(string[] args) {
        var apiBaseUrl = "https://www.productcategorization.com/api/ecommerce/ecommerce_category6_get.php?";
        var apiKey = "your_api_key";
        var queryText = "Fluorescent Highlighters 3pc Yellow";

        var encodedQueryText = Uri.EscapeDataString(queryText);
        var finalUrl = $"{apiBaseUrl}query={encodedQueryText}&api_key={apiKey}";

        using (HttpClient client = new HttpClient()) {
            var response = await client.GetStringAsync(finalUrl);
            Console.WriteLine(response);
        }
    }
}

          

Product Categorization of Images

Our categorization and attributes API can classify images based on Shopify Taxonomy: https://github.com/Shopify/product-taxonomy/tree/main

Below is a Python example for calling our image-categorization endpoint in case of using URL for image (modify the code accordingly in case of using local image file):

            
              
            

import requests
import io

def call_api(image_url, text, ip='0', api_key='your_api_key', login='0'):
    api_endpoint = 'https://www.productcategorization.com/api/ecommerce/ecommerce_shopify_image.php'

    # Download the image
    response = requests.get(image_url)
    if response.status_code != 200:
        return {'error': 'Failed to download image'}

    # Create a file-like object
    image_file = io.BytesIO(response.content)

    # Prepare the data
    data = {
        'ip': ip,
        'api_key': api_key,
        'login': login,
        'text': text
    }

    files = {
        'image': ('image.jpg', image_file, 'image/jpeg')
    }

    try:
        response = requests.post(api_endpoint, data=data, files=files)
        response.raise_for_status()
        return response.json()
    except requests.exceptions.RequestException as e:
        return {'error': f'API call failed: {str(e)}'}

          

Errors

The API returns a status value for each request. For example, a successful request might look like:

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

          

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