ProductCategorization.com Python Client

---

Overview

The productcategorization Python package provides seamless access to one of the world's most advanced product categorization APIs, powering e-commerce classification for unicorn startups, multinational enterprises, retail analytics platforms, adTech innovators, and online merchants. Whether you operate an e-commerce storefront, marketplace, or SaaS platform, this package allows you to integrate AI-powered categorization directly into your Python applications, unlocking world-class product, URL, and image classification using industry-standard taxonomies.

Key Features

• Ultra-Accurate Product Categorization Classify product titles, descriptions, and URLs using:

  • Google Shopping Taxonomy: Over 5,500 hierarchical categories for granular and up-to-date mapping.
  • Shopify Taxonomy: Leverage the latest Shopify category structure with ~11,000 fine-grained categories.
  • Amazon and Other Standard Taxonomies: Flexibility for diverse retail needs.
  • Custom Taxonomies: Tailor classifiers to your unique vertical or proprietary taxonomy.

• Multi-Modal Classification

  • Text: Classify any product-related string.
  • URL: Categorize products directly from their web pages.
  • Image: Obtain Shopify categories and attribute extraction directly from images (using AI vision).

• Buyer Persona Enrichment Every classification returns relevant buyer personas—select from a proprietary library of over 1,800 personas to enrich your analytics, personalization, or marketing automations. Confidence scores and expanded context available.

• High Scalability and Reliability Robust API supporting high throughput (rate limits adjustable upon request), with credit-based billing for predictable scaling.

• Plug-and-Play Python Integration Simple, modern, and extensible Python API client. See Quickstart for usage examples.

---

Table of Contents

• Getting Started

• Authentication

• API Usage

  • Text Categorization
  • URL Categorization
  • Image Categorization

• Advanced Options

  • Buyer Personas and Confidence Scores
  • Context Expansion

• Error Handling

• Best Practices

• Integration Examples

• Contact & Support

• Related Services

• References

---

Getting Started

Install the package via PyPI:

pip install productcategorization

Or add it to your requirements.txt for automatic deployment.

---

Authentication

All API access is secured by a personal API key. To obtain your API key:

1. Sign up and purchase a subscription at [www.productcategorization.com](https://www.productcategorization.com/pricing.php
2. Provide the API key in every request (see examples).

Note: Never share your API key publicly. Store it securely as an environment variable or in your configuration files.

---

API Usage

Text Categorization

Classify any product text (title, description, or keyword) in a single line:

from productcategorization import ProductCategorizationAPI

api = ProductCategorizationAPI(api_key="your_api_key")
result = api.categorize_text("Fluorescent Highlighters 3pc Yellow")
print(result)

Sample Response:

{
    "total_credits": 100044,
    "remaining_credits": 33075,
    "language": "en",
    "classification": "Office Supplies > Office Instruments > Writing & Drawing Instruments",
    "buyer_personas": [
        "Business Professional", "Office Professional", "Administrative Coordinator", ...
    ],
    "buyer_personas_confidence_selection": {
        "Office Professional": 0.9,
        "Business Professional": 0.8,
        ...
    },
    "ID": "977",
    "status": 200
}

Parameters:

• query (str): Product text for categorization.
• confidence (optional, int): Set to 1 to include confidence scores for each persona.
• expand_context (optional, int): Set to 1 to auto-generate expanded context for short/ambiguous texts.

---

URL Categorization

You can also classify products by URL, leveraging our AI’s ability to extract relevant text and metadata:

result = api.categorize_url("https://www.apple.com")
print(result)

Sample Python (requests):

import requests

payload = {'query': 'www.apple.com', 'api_key': 'your_api_key', 'data_type': 'url'}
response = requests.post("https://www.productcategorization.com/api/iab/iab_web_content_filtering_url.php", data=payload)
print(response.json())

---

Image Categorization

Classify products using image URLs or local image files (Shopify Taxonomy + attribute extraction):

result = api.categorize_image(image_url="https://images.com/product.jpg", text="Product title")
print(result)

Example Function:

import requests
import io

def call_api(image_url, text, api_key):
    api_endpoint = 'https://www.productcategorization.com/api/ecommerce/ecommerce_shopify_image.php'
    response = requests.get(image_url)
    if response.status_code != 200:
        return {'error': 'Failed to download image'}
    image_file = io.BytesIO(response.content)
    data = {'ip': '0', 'api_key': api_key, 'login': '0', 'text': text}
    files = {'image': ('image.jpg', image_file, 'image/jpeg')}
    response = requests.post(api_endpoint, data=data, files=files)
    return response.json()

---

Advanced Options

Buyer Personas and Confidence Scores

Our AI delivers a unique set of buyer personas for every product—ideal for market analysis, targeted marketing, or persona-based analytics. Enable confidence scoring to obtain relevance weights for each persona:

result = api.categorize_text("Eco-Friendly Notebook", confidence=1)
print(result["buyer_personas_confidence_selection"])

Context Expansion

For short or ambiguous inputs, enable expand_context=1 to let our AI generate an enhanced description for improved classification accuracy:

result = api.categorize_text("3pc Yellow Highlighters", expand_context=1)
print(result["expanded_context"])

---

Error Handling

All API responses include a status code for programmatic error handling:

Status	Meaning
200	Request was successful
400	Request malformed (check parameters)
401	Invalid API key (check or purchase key)
403	Quota exhausted (upgrade or add credits)

Example error handling in Python:

if result["status"] != 200:
    print(f"API Error: {result.get('message', 'Unknown error')}")

---

Best Practices

• Monitor Remaining Credits: Every response includes total_credits and remaining_credits. Plan your usage to avoid interruptions.
• Respect Rate Limits: Default is 60 requests per minute. Contact support for higher needs.
• Secure Your API Key: Do not embed directly in code if publishing open-source.
• Use Context Expansion When Needed: For short/ambiguous product titles, enable expand_context.
• Batch Requests: For large datasets, consider batching requests and handling quota gracefully.

---

Integration Examples

Python Example

from productcategorization import ProductCategorizationAPI

api = ProductCategorizationAPI(api_key="your_api_key")
result = api.categorize_text("Fluorescent Highlighters 3pc Yellow")
print(result["classification"])

JavaScript Example

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));

Ruby Example

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

C# Example

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);
        }
    }
}

---

Contact & Support

Need a higher rate limit, a custom classifier, or additional support? Visit Contact, or email support via your account dashboard.

---

Related Services

Domain review becomes easier when analysts can reference a domain classification database for consistent category data. Strong classification coverage is useful for c ompliance checks and internal security reviews. To operationalize those results, organizations may deploy a managed filtering platform across their networks.

Leverage our broader suite of AI-powered APIs to cover every aspect of your business’s data intelligence and privacy needs:

• Live Video Anonymization – live video anonymization: Protect privacy with automatic anonymization of faces and sensitive objects in live video streams, supporting GDPR compliance and safeguarding user identities.

• Domain Categorization Data – domain categorization data: Access the world’s largest database of categorized domains for cybersecurity, web filtering, and content safety.

Our APIs integrate seamlessly with your product workflows, providing reliable, scalable, and secure endpoints for your business logic.

For organizations operating in the education sector, product classification often feeds into broader content-safety workflows — a CIPA-compliant filtering database with over 120 million categorized domains helps K-12 districts and libraries enforce acceptable-use policies required by federal law. Cybersecurity is equally critical in e-commerce environments where phishing pages impersonate legitimate retailers, and a real-time phishing intelligence feed of 390,000+ verified malicious domains enables platforms to warn buyers before they land on a fraudulent storefront. Combining product-level classification with domain-level threat detection creates a layered defense that protects both brand reputation and end-user safety.

---

References & Further Reading

For best-in-class taxonomy, AI, and categorization research, explore:

• Stanford AI Lab
• MIT CSAIL
• Berkeley AI Research
• Oxford Internet Institute
• UCL Centre for Artificial Intelligence
• Google AI Blog
• Microsoft Research
• arXiv Machine Learning

For taxonomy standards and e-commerce data:

• Google Shopping Taxonomy
• Shopify Product Taxonomy

---

License

This library is distributed under the MIT License.

---

Disclaimer

This project is unaffiliated with Google, Shopify, or Amazon. All trademarks are property of their respective owners.

---

Classification needs have expanded beyond products: AI tool domain classification is now a common requirement for security and compliance teams that must inventory and control generative-AI usage. A dedicated, daily-refreshed list of AI-tool domains with functional categories lets network products offer per-category AI policies out of the box. It pairs naturally with the taxonomy-driven approach described in this package.

__init__.py Example

import requests

class ProductCategorizationAPI:
    def __init__(self, api_key):
        self.api_key = api_key
        self.base_url = "https://www.productcategorization.com/api/"

    def categorize_text(self, text, confidence=0, expand_context=0):
        params = {
            "query": text,
            "api_key": self.api_key,
            "confidence": str(confidence),
            "expand_context": str(expand_context)
        }
        response = requests.get(self.base_url + "ecommerce/ecommerce_category6_get.php", params=params)
        return response.json()

    def categorize_url(self, url):
        payload = {
            'query': url,
            'api_key': self.api_key,
            'data_type': 'url'
        }
        headers = {
            'Content-Type': 'application/x-www-form-urlencoded'
        }
        response = requests.post(self.base_url + "iab/iab_web_content_filtering_url.php", data=payload, headers=headers)
        return response.json()

    def categorize_image(self, image_url, text="", ip="0", login="0"):
        # Download image to memory
        image_response = requests.get(image_url)
        if image_response.status_code != 200:
            return {'error': 'Failed to download image'}
        import io
        image_file = io.BytesIO(image_response.content)
        data = {
            'ip': ip,
            'api_key': self.api_key,
            'login': login,
            'text': text
        }
        files = {
            'image': ('image.jpg', image_file, 'image/jpeg')
        }
        response = requests.post(self.base_url + "ecommerce/ecommerce_shopify_image.php", data=data, files=files)
        return response.json()

---

• Acquisition candidate discovery — Classification AI applied to identifying business targets for M&A transactions. The platform screens over 100 million domains against custom acquisition theses and extracts 15 operational signals per company from web presence, surfacing targets that keyword-based deal databases miss.
• Privacy-safe audience classification — Product and domain classification extends to privacy-compliant audience building for ad-tech. Pre-categorized domain datasets under the IAB taxonomy enable contextual targeting campaigns that replace cookie-based tracking with domain-level content signals.
• AI tool domain classification
• Resume parser API — AI resume parsing API — structured JSON from PDF/DOCX resumes, extracting work history, education, skills, and contact data for HR-tech and recruiting platforms.