productcategorizationapi 1.5__tar.gz → 1.6__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.1
2
2
  Name: productcategorizationapi
3
- Version: 1.5
3
+ Version: 1.6
4
4
  Summary: product categorization API
5
5
  Home-page: https://www.productcategorization.com
6
6
  Author-email: info@productcategorizationapi.com
@@ -371,6 +371,9 @@ Description:
371
371
 
372
372
  ---
373
373
 
374
+
375
+ Classification needs have expanded beyond products: [AI tool domain classification](https://www.aitoolsblocklist.com) 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.
376
+
374
377
  # `__init__.py` Example
375
378
 
376
379
  ```python
@@ -424,7 +427,7 @@ Description:
424
427
  ```
425
428
 
426
429
  ---
427
-
430
+ * [AI tool domain classification](https://www.aitoolsblocklist.com)
428
431
 
429
432
  Keywords: product categorization,classification,categorization
430
433
  Platform: UNKNOWN
@@ -1,420 +1,423 @@
1
-
2
- # ProductCategorization.com Python Client
3
-
4
- [![PyPI version](https://badge.fury.io/py/productcategorization.svg)](https://pypi.org/project/productcategorization/)
5
- [![API Docs](https://www.productcategorization.com/api.php)](https://www.productcategorization.com/product_categorization_api.php)
6
-
7
- ---
8
-
9
- ## Overview
10
-
11
- 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.
12
-
13
- ## Key Features
14
-
15
- * **Ultra-Accurate Product Categorization**
16
- Classify product titles, descriptions, and URLs using:
17
-
18
- * **Google Shopping Taxonomy:** Over 5,500 hierarchical categories for granular and up-to-date mapping.
19
- * **Shopify Taxonomy:** Leverage the latest Shopify category structure with \~11,000 fine-grained categories.
20
- * **Amazon and Other Standard Taxonomies:** Flexibility for diverse retail needs.
21
- * **Custom Taxonomies:** Tailor classifiers to your unique vertical or proprietary taxonomy.
22
-
23
- * **Multi-Modal Classification**
24
-
25
- * **Text**: Classify any product-related string.
26
- * **URL**: Categorize products directly from their web pages.
27
- * **Image**: Obtain Shopify categories and attribute extraction directly from images (using AI vision).
28
-
29
- * **Buyer Persona Enrichment**
30
- Every classification returns relevant buyer personas—select from a proprietary library of over 1,800 personas to enrich your analytics, personalization, or marketing automations.
31
- Confidence scores and expanded context available.
32
-
33
- * **High Scalability and Reliability**
34
- Robust API supporting high throughput (rate limits adjustable upon request), with credit-based billing for predictable scaling.
35
-
36
- * **Plug-and-Play Python Integration**
37
- Simple, modern, and extensible Python API client.
38
- See [Quickstart](#quickstart) for usage examples.
39
-
40
- ---
41
-
42
- ## Table of Contents
43
-
44
- * [Getting Started](#getting-started)
45
- * [Authentication](#authentication)
46
- * [API Usage](#api-usage)
47
-
48
- * [Text Categorization](#text-categorization)
49
- * [URL Categorization](#url-categorization)
50
- * [Image Categorization](#image-categorization)
51
- * [Advanced Options](#advanced-options)
52
-
53
- * [Buyer Personas and Confidence Scores](#buyer-personas-and-confidence-scores)
54
- * [Context Expansion](#context-expansion)
55
- * [Error Handling](#error-handling)
56
- * [Best Practices](#best-practices)
57
- * [Integration Examples](#integration-examples)
58
- * [Contact & Support](#contact--support)
59
- * [Related Services](#related-services)
60
- * [References](#references)
61
-
62
- ---
63
-
64
- ## Getting Started
65
-
66
- Install the package via PyPI:
67
-
68
- ```bash
69
- pip install productcategorization
70
- ```
71
-
72
- Or add it to your `requirements.txt` for automatic deployment.
73
-
74
- ---
75
-
76
- ## Authentication
77
-
78
- All API access is secured by a personal API key.
79
- To obtain your API key:
80
-
81
- 1. Sign up and purchase a subscription at [www.productcategorization.com](https://www.productcategorization.com/pricing.php
82
- 3. Provide the API key in every request (see examples).
83
-
84
- > **Note:** Never share your API key publicly. Store it securely as an environment variable or in your configuration files.
85
-
86
- ---
87
-
88
- ## API Usage
89
-
90
- ### Text Categorization
91
-
92
- Classify any product text (title, description, or keyword) in a single line:
93
-
94
- ```python
95
- from productcategorization import ProductCategorizationAPI
96
-
97
- api = ProductCategorizationAPI(api_key="your_api_key")
98
- result = api.categorize_text("Fluorescent Highlighters 3pc Yellow")
99
- print(result)
100
- ```
101
-
102
- **Sample Response:**
103
-
104
- ```json
105
- {
106
- "total_credits": 100044,
107
- "remaining_credits": 33075,
108
- "language": "en",
109
- "classification": "Office Supplies > Office Instruments > Writing & Drawing Instruments",
110
- "buyer_personas": [
111
- "Business Professional", "Office Professional", "Administrative Coordinator", ...
112
- ],
113
- "buyer_personas_confidence_selection": {
114
- "Office Professional": 0.9,
115
- "Business Professional": 0.8,
116
- ...
117
- },
118
- "ID": "977",
119
- "status": 200
120
- }
121
- ```
122
-
123
- **Parameters:**
124
-
125
- * `query` (str): Product text for categorization.
126
- * `confidence` (optional, int): Set to `1` to include confidence scores for each persona.
127
- * `expand_context` (optional, int): Set to `1` to auto-generate expanded context for short/ambiguous texts.
128
-
129
- ---
130
-
131
- ### URL Categorization
132
-
133
- You can also classify products by URL, leveraging our AI’s ability to extract relevant text and metadata:
134
-
135
- ```python
136
- result = api.categorize_url("https://www.apple.com")
137
- print(result)
138
- ```
139
-
140
- **Sample Python (requests):**
141
-
142
- ```python
143
- import requests
144
-
145
- payload = {'query': 'www.apple.com', 'api_key': 'your_api_key', 'data_type': 'url'}
146
- response = requests.post("https://www.productcategorization.com/api/iab/iab_web_content_filtering_url.php", data=payload)
147
- print(response.json())
148
- ```
149
-
150
- ---
151
-
152
- ### Image Categorization
153
-
154
- Classify products using image URLs or local image files (Shopify Taxonomy + attribute extraction):
155
-
156
- ```python
157
- result = api.categorize_image(image_url="https://images.com/product.jpg", text="Product title")
158
- print(result)
159
- ```
160
-
161
- **Example Function:**
162
-
163
- ```python
164
- import requests
165
- import io
166
-
167
- def call_api(image_url, text, api_key):
168
- api_endpoint = 'https://www.productcategorization.com/api/ecommerce/ecommerce_shopify_image.php'
169
- response = requests.get(image_url)
170
- if response.status_code != 200:
171
- return {'error': 'Failed to download image'}
172
- image_file = io.BytesIO(response.content)
173
- data = {'ip': '0', 'api_key': api_key, 'login': '0', 'text': text}
174
- files = {'image': ('image.jpg', image_file, 'image/jpeg')}
175
- response = requests.post(api_endpoint, data=data, files=files)
176
- return response.json()
177
- ```
178
-
179
- ---
180
-
181
- ## Advanced Options
182
-
183
- ### Buyer Personas and Confidence Scores
184
-
185
- Our AI delivers a unique set of buyer personas for every product—ideal for market analysis, targeted marketing, or persona-based analytics.
186
- Enable confidence scoring to obtain relevance weights for each persona:
187
-
188
- ```python
189
- result = api.categorize_text("Eco-Friendly Notebook", confidence=1)
190
- print(result["buyer_personas_confidence_selection"])
191
- ```
192
-
193
- ### Context Expansion
194
-
195
- For short or ambiguous inputs, enable `expand_context=1` to let our AI generate an enhanced description for improved classification accuracy:
196
-
197
- ```python
198
- result = api.categorize_text("3pc Yellow Highlighters", expand_context=1)
199
- print(result["expanded_context"])
200
- ```
201
-
202
- ---
203
-
204
- ## Error Handling
205
-
206
- All API responses include a `status` code for programmatic error handling:
207
-
208
- | Status | Meaning |
209
- | ------ | ---------------------------------------- |
210
- | 200 | Request was successful |
211
- | 400 | Request malformed (check parameters) |
212
- | 401 | Invalid API key (check or purchase key) |
213
- | 403 | Quota exhausted (upgrade or add credits) |
214
-
215
- Example error handling in Python:
216
-
217
- ```python
218
- if result["status"] != 200:
219
- print(f"API Error: {result.get('message', 'Unknown error')}")
220
- ```
221
-
222
- ---
223
-
224
- ## Best Practices
225
-
226
- * **Monitor Remaining Credits:** Every response includes `total_credits` and `remaining_credits`. Plan your usage to avoid interruptions.
227
- * **Respect Rate Limits:** Default is 60 requests per minute. Contact support for higher needs.
228
- * **Secure Your API Key:** Do not embed directly in code if publishing open-source.
229
- * **Use Context Expansion When Needed:** For short/ambiguous product titles, enable `expand_context`.
230
- * **Batch Requests:** For large datasets, consider batching requests and handling quota gracefully.
231
-
232
- ---
233
-
234
- ## Integration Examples
235
-
236
- ### Python Example
237
-
238
- ```python
239
- from productcategorization import ProductCategorizationAPI
240
-
241
- api = ProductCategorizationAPI(api_key="your_api_key")
242
- result = api.categorize_text("Fluorescent Highlighters 3pc Yellow")
243
- print(result["classification"])
244
- ```
245
-
246
- ### JavaScript Example
247
-
248
- ```javascript
249
- const apiBaseUrl = "https://www.productcategorization.com/api/ecommerce/ecommerce_category6_get.php?";
250
- const apiKey = "your_api_key";
251
- const queryText = "Fluorescent Highlighters 3pc Yellow";
252
- const encodedQueryText = encodeURIComponent(queryText);
253
- const finalUrl = `${apiBaseUrl}query=${encodedQueryText}&api_key=${apiKey}`;
254
-
255
- fetch(finalUrl)
256
- .then(response => response.json())
257
- .then(data => console.log(data));
258
- ```
259
-
260
- ### Ruby Example
261
-
262
- ```ruby
263
- require 'uri'
264
- require 'net/http'
265
-
266
- api_base_url = "https://www.productcategorization.com/api/ecommerce/ecommerce_category6_get.php"
267
- api_key = "your_api_key"
268
- query_text = "Fluorescent Highlighters 3pc Yellow"
269
-
270
- encoded_query = URI.encode_www_form_component(query_text)
271
- url = URI("#{api_base_url}?query=#{encoded_query}&api_key=#{api_key}")
272
-
273
- response = Net::HTTP.get(url)
274
- puts response
275
- ```
276
-
277
- ### C# Example
278
-
279
- ```csharp
280
- using System;
281
- using System.Net.Http;
282
- using System.Threading.Tasks;
283
-
284
- class Program {
285
- static async Task Main(string[] args) {
286
- var apiBaseUrl = "https://www.productcategorization.com/api/ecommerce/ecommerce_category6_get.php?";
287
- var apiKey = "your_api_key";
288
- var queryText = "Fluorescent Highlighters 3pc Yellow";
289
- var encodedQueryText = Uri.EscapeDataString(queryText);
290
- var finalUrl = $"{apiBaseUrl}query={encodedQueryText}&api_key={apiKey}";
291
-
292
- using (HttpClient client = new HttpClient()) {
293
- var response = await client.GetStringAsync(finalUrl);
294
- Console.WriteLine(response);
295
- }
296
- }
297
- }
298
- ```
299
-
300
- ---
301
-
302
- ## Contact & Support
303
-
304
- Need a higher rate limit, a custom classifier, or additional support?
305
- Visit [Contact](https://www.productcategorization.com/contact), or email support via your account dashboard.
306
-
307
- ---
308
-
309
- ## Related Services
310
-
311
- Domain review becomes easier when analysts can reference a [domain classification database](https://webfilteringdatabase.com) for consistent category data. Strong classification coverage is useful for c
312
- ompliance checks and internal security reviews. To operationalize those results, organizations may deploy a [managed filtering platform](https://webfilteringservice.com) across their networks.
313
-
314
- Leverage our broader suite of AI-powered APIs to cover every aspect of your business’s data intelligence and privacy needs:
315
-
316
- * **[Comment Moderation API](https://www.contentmoderationapi.net) – comment moderation api:**
317
- Safeguard your community, app, or platform with industry-leading AI moderation for comments and user-generated content. Detect profanity, hate speech, spam, and toxicity in real time.
318
-
319
- * **[Live Video Anonymization](https://www.anonymizationapi.com) – live video anonymization:**
320
- Protect privacy with automatic anonymization of faces and sensitive objects in live video streams, supporting GDPR compliance and safeguarding user identities.
321
-
322
- * **[Text Redaction API](https://www.redactionapi.net) – text redaction api:**
323
- Redact personal data, financial information, or any sensitive fields from documents at scale using our high-precision redaction API.
324
-
325
-
326
- * **[Domain Categorization Data](https://www.urlcategorizationdatabase.com) – domain categorization data:**
327
- Access the world’s largest database of categorized domains for cybersecurity, web filtering, and content safety.
328
-
329
-
330
- Our APIs integrate seamlessly with your product workflows, providing reliable, scalable, and secure endpoints for your business logic.
331
-
332
- ---
333
-
334
- ## References & Further Reading
335
-
336
- For best-in-class taxonomy, AI, and categorization research, explore:
337
-
338
- * [Stanford AI Lab](https://ai.stanford.edu)
339
- * [MIT CSAIL](https://www.csail.mit.edu)
340
- * [Berkeley AI Research](https://bair.berkeley.edu)
341
- * [Oxford Internet Institute](https://www.oii.ox.ac.uk)
342
- * [UCL Centre for Artificial Intelligence](https://www.ucl.ac.uk/ai)
343
- * [Google AI Blog](https://ai.googleblog.com/)
344
- * [Microsoft Research](https://www.microsoft.com/en-us/research/)
345
- * [arXiv Machine Learning](https://arxiv.org/list/cs.LG/recent)
346
-
347
- For taxonomy standards and e-commerce data:
348
-
349
- * [Google Shopping Taxonomy](https://support.google.com/merchants/answer/6324436)
350
- * [Shopify Product Taxonomy](https://github.com/Shopify/product-taxonomy)
351
-
352
- ---
353
-
354
- ## License
355
-
356
- This library is distributed under the MIT License.
357
-
358
- ---
359
-
360
- ## Disclaimer
361
-
362
- This project is unaffiliated with Google, Shopify, or Amazon.
363
- All trademarks are property of their respective owners.
364
-
365
- ---
366
-
367
- # `__init__.py` Example
368
-
369
- ```python
370
- import requests
371
-
372
- class ProductCategorizationAPI:
373
- def __init__(self, api_key):
374
- self.api_key = api_key
375
- self.base_url = "https://www.productcategorization.com/api/"
376
-
377
- def categorize_text(self, text, confidence=0, expand_context=0):
378
- params = {
379
- "query": text,
380
- "api_key": self.api_key,
381
- "confidence": str(confidence),
382
- "expand_context": str(expand_context)
383
- }
384
- response = requests.get(self.base_url + "ecommerce/ecommerce_category6_get.php", params=params)
385
- return response.json()
386
-
387
- def categorize_url(self, url):
388
- payload = {
389
- 'query': url,
390
- 'api_key': self.api_key,
391
- 'data_type': 'url'
392
- }
393
- headers = {
394
- 'Content-Type': 'application/x-www-form-urlencoded'
395
- }
396
- response = requests.post(self.base_url + "iab/iab_web_content_filtering_url.php", data=payload, headers=headers)
397
- return response.json()
398
-
399
- def categorize_image(self, image_url, text="", ip="0", login="0"):
400
- # Download image to memory
401
- image_response = requests.get(image_url)
402
- if image_response.status_code != 200:
403
- return {'error': 'Failed to download image'}
404
- import io
405
- image_file = io.BytesIO(image_response.content)
406
- data = {
407
- 'ip': ip,
408
- 'api_key': self.api_key,
409
- 'login': login,
410
- 'text': text
411
- }
412
- files = {
413
- 'image': ('image.jpg', image_file, 'image/jpeg')
414
- }
415
- response = requests.post(self.base_url + "ecommerce/ecommerce_shopify_image.php", data=data, files=files)
416
- return response.json()
417
- ```
418
-
419
- ---
420
-
1
+
2
+ # ProductCategorization.com Python Client
3
+
4
+ [![PyPI version](https://badge.fury.io/py/productcategorization.svg)](https://pypi.org/project/productcategorization/)
5
+ [![API Docs](https://www.productcategorization.com/api.php)](https://www.productcategorization.com/product_categorization_api.php)
6
+
7
+ ---
8
+
9
+ ## Overview
10
+
11
+ 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.
12
+
13
+ ## Key Features
14
+
15
+ * **Ultra-Accurate Product Categorization**
16
+ Classify product titles, descriptions, and URLs using:
17
+
18
+ * **Google Shopping Taxonomy:** Over 5,500 hierarchical categories for granular and up-to-date mapping.
19
+ * **Shopify Taxonomy:** Leverage the latest Shopify category structure with \~11,000 fine-grained categories.
20
+ * **Amazon and Other Standard Taxonomies:** Flexibility for diverse retail needs.
21
+ * **Custom Taxonomies:** Tailor classifiers to your unique vertical or proprietary taxonomy.
22
+
23
+ * **Multi-Modal Classification**
24
+
25
+ * **Text**: Classify any product-related string.
26
+ * **URL**: Categorize products directly from their web pages.
27
+ * **Image**: Obtain Shopify categories and attribute extraction directly from images (using AI vision).
28
+
29
+ * **Buyer Persona Enrichment**
30
+ Every classification returns relevant buyer personas—select from a proprietary library of over 1,800 personas to enrich your analytics, personalization, or marketing automations.
31
+ Confidence scores and expanded context available.
32
+
33
+ * **High Scalability and Reliability**
34
+ Robust API supporting high throughput (rate limits adjustable upon request), with credit-based billing for predictable scaling.
35
+
36
+ * **Plug-and-Play Python Integration**
37
+ Simple, modern, and extensible Python API client.
38
+ See [Quickstart](#quickstart) for usage examples.
39
+
40
+ ---
41
+
42
+ ## Table of Contents
43
+
44
+ * [Getting Started](#getting-started)
45
+ * [Authentication](#authentication)
46
+ * [API Usage](#api-usage)
47
+
48
+ * [Text Categorization](#text-categorization)
49
+ * [URL Categorization](#url-categorization)
50
+ * [Image Categorization](#image-categorization)
51
+ * [Advanced Options](#advanced-options)
52
+
53
+ * [Buyer Personas and Confidence Scores](#buyer-personas-and-confidence-scores)
54
+ * [Context Expansion](#context-expansion)
55
+ * [Error Handling](#error-handling)
56
+ * [Best Practices](#best-practices)
57
+ * [Integration Examples](#integration-examples)
58
+ * [Contact & Support](#contact--support)
59
+ * [Related Services](#related-services)
60
+ * [References](#references)
61
+
62
+ ---
63
+
64
+ ## Getting Started
65
+
66
+ Install the package via PyPI:
67
+
68
+ ```bash
69
+ pip install productcategorization
70
+ ```
71
+
72
+ Or add it to your `requirements.txt` for automatic deployment.
73
+
74
+ ---
75
+
76
+ ## Authentication
77
+
78
+ All API access is secured by a personal API key.
79
+ To obtain your API key:
80
+
81
+ 1. Sign up and purchase a subscription at [www.productcategorization.com](https://www.productcategorization.com/pricing.php
82
+ 3. Provide the API key in every request (see examples).
83
+
84
+ > **Note:** Never share your API key publicly. Store it securely as an environment variable or in your configuration files.
85
+
86
+ ---
87
+
88
+ ## API Usage
89
+
90
+ ### Text Categorization
91
+
92
+ Classify any product text (title, description, or keyword) in a single line:
93
+
94
+ ```python
95
+ from productcategorization import ProductCategorizationAPI
96
+
97
+ api = ProductCategorizationAPI(api_key="your_api_key")
98
+ result = api.categorize_text("Fluorescent Highlighters 3pc Yellow")
99
+ print(result)
100
+ ```
101
+
102
+ **Sample Response:**
103
+
104
+ ```json
105
+ {
106
+ "total_credits": 100044,
107
+ "remaining_credits": 33075,
108
+ "language": "en",
109
+ "classification": "Office Supplies > Office Instruments > Writing & Drawing Instruments",
110
+ "buyer_personas": [
111
+ "Business Professional", "Office Professional", "Administrative Coordinator", ...
112
+ ],
113
+ "buyer_personas_confidence_selection": {
114
+ "Office Professional": 0.9,
115
+ "Business Professional": 0.8,
116
+ ...
117
+ },
118
+ "ID": "977",
119
+ "status": 200
120
+ }
121
+ ```
122
+
123
+ **Parameters:**
124
+
125
+ * `query` (str): Product text for categorization.
126
+ * `confidence` (optional, int): Set to `1` to include confidence scores for each persona.
127
+ * `expand_context` (optional, int): Set to `1` to auto-generate expanded context for short/ambiguous texts.
128
+
129
+ ---
130
+
131
+ ### URL Categorization
132
+
133
+ You can also classify products by URL, leveraging our AI’s ability to extract relevant text and metadata:
134
+
135
+ ```python
136
+ result = api.categorize_url("https://www.apple.com")
137
+ print(result)
138
+ ```
139
+
140
+ **Sample Python (requests):**
141
+
142
+ ```python
143
+ import requests
144
+
145
+ payload = {'query': 'www.apple.com', 'api_key': 'your_api_key', 'data_type': 'url'}
146
+ response = requests.post("https://www.productcategorization.com/api/iab/iab_web_content_filtering_url.php", data=payload)
147
+ print(response.json())
148
+ ```
149
+
150
+ ---
151
+
152
+ ### Image Categorization
153
+
154
+ Classify products using image URLs or local image files (Shopify Taxonomy + attribute extraction):
155
+
156
+ ```python
157
+ result = api.categorize_image(image_url="https://images.com/product.jpg", text="Product title")
158
+ print(result)
159
+ ```
160
+
161
+ **Example Function:**
162
+
163
+ ```python
164
+ import requests
165
+ import io
166
+
167
+ def call_api(image_url, text, api_key):
168
+ api_endpoint = 'https://www.productcategorization.com/api/ecommerce/ecommerce_shopify_image.php'
169
+ response = requests.get(image_url)
170
+ if response.status_code != 200:
171
+ return {'error': 'Failed to download image'}
172
+ image_file = io.BytesIO(response.content)
173
+ data = {'ip': '0', 'api_key': api_key, 'login': '0', 'text': text}
174
+ files = {'image': ('image.jpg', image_file, 'image/jpeg')}
175
+ response = requests.post(api_endpoint, data=data, files=files)
176
+ return response.json()
177
+ ```
178
+
179
+ ---
180
+
181
+ ## Advanced Options
182
+
183
+ ### Buyer Personas and Confidence Scores
184
+
185
+ Our AI delivers a unique set of buyer personas for every product—ideal for market analysis, targeted marketing, or persona-based analytics.
186
+ Enable confidence scoring to obtain relevance weights for each persona:
187
+
188
+ ```python
189
+ result = api.categorize_text("Eco-Friendly Notebook", confidence=1)
190
+ print(result["buyer_personas_confidence_selection"])
191
+ ```
192
+
193
+ ### Context Expansion
194
+
195
+ For short or ambiguous inputs, enable `expand_context=1` to let our AI generate an enhanced description for improved classification accuracy:
196
+
197
+ ```python
198
+ result = api.categorize_text("3pc Yellow Highlighters", expand_context=1)
199
+ print(result["expanded_context"])
200
+ ```
201
+
202
+ ---
203
+
204
+ ## Error Handling
205
+
206
+ All API responses include a `status` code for programmatic error handling:
207
+
208
+ | Status | Meaning |
209
+ | ------ | ---------------------------------------- |
210
+ | 200 | Request was successful |
211
+ | 400 | Request malformed (check parameters) |
212
+ | 401 | Invalid API key (check or purchase key) |
213
+ | 403 | Quota exhausted (upgrade or add credits) |
214
+
215
+ Example error handling in Python:
216
+
217
+ ```python
218
+ if result["status"] != 200:
219
+ print(f"API Error: {result.get('message', 'Unknown error')}")
220
+ ```
221
+
222
+ ---
223
+
224
+ ## Best Practices
225
+
226
+ * **Monitor Remaining Credits:** Every response includes `total_credits` and `remaining_credits`. Plan your usage to avoid interruptions.
227
+ * **Respect Rate Limits:** Default is 60 requests per minute. Contact support for higher needs.
228
+ * **Secure Your API Key:** Do not embed directly in code if publishing open-source.
229
+ * **Use Context Expansion When Needed:** For short/ambiguous product titles, enable `expand_context`.
230
+ * **Batch Requests:** For large datasets, consider batching requests and handling quota gracefully.
231
+
232
+ ---
233
+
234
+ ## Integration Examples
235
+
236
+ ### Python Example
237
+
238
+ ```python
239
+ from productcategorization import ProductCategorizationAPI
240
+
241
+ api = ProductCategorizationAPI(api_key="your_api_key")
242
+ result = api.categorize_text("Fluorescent Highlighters 3pc Yellow")
243
+ print(result["classification"])
244
+ ```
245
+
246
+ ### JavaScript Example
247
+
248
+ ```javascript
249
+ const apiBaseUrl = "https://www.productcategorization.com/api/ecommerce/ecommerce_category6_get.php?";
250
+ const apiKey = "your_api_key";
251
+ const queryText = "Fluorescent Highlighters 3pc Yellow";
252
+ const encodedQueryText = encodeURIComponent(queryText);
253
+ const finalUrl = `${apiBaseUrl}query=${encodedQueryText}&api_key=${apiKey}`;
254
+
255
+ fetch(finalUrl)
256
+ .then(response => response.json())
257
+ .then(data => console.log(data));
258
+ ```
259
+
260
+ ### Ruby Example
261
+
262
+ ```ruby
263
+ require 'uri'
264
+ require 'net/http'
265
+
266
+ api_base_url = "https://www.productcategorization.com/api/ecommerce/ecommerce_category6_get.php"
267
+ api_key = "your_api_key"
268
+ query_text = "Fluorescent Highlighters 3pc Yellow"
269
+
270
+ encoded_query = URI.encode_www_form_component(query_text)
271
+ url = URI("#{api_base_url}?query=#{encoded_query}&api_key=#{api_key}")
272
+
273
+ response = Net::HTTP.get(url)
274
+ puts response
275
+ ```
276
+
277
+ ### C# Example
278
+
279
+ ```csharp
280
+ using System;
281
+ using System.Net.Http;
282
+ using System.Threading.Tasks;
283
+
284
+ class Program {
285
+ static async Task Main(string[] args) {
286
+ var apiBaseUrl = "https://www.productcategorization.com/api/ecommerce/ecommerce_category6_get.php?";
287
+ var apiKey = "your_api_key";
288
+ var queryText = "Fluorescent Highlighters 3pc Yellow";
289
+ var encodedQueryText = Uri.EscapeDataString(queryText);
290
+ var finalUrl = $"{apiBaseUrl}query={encodedQueryText}&api_key={apiKey}";
291
+
292
+ using (HttpClient client = new HttpClient()) {
293
+ var response = await client.GetStringAsync(finalUrl);
294
+ Console.WriteLine(response);
295
+ }
296
+ }
297
+ }
298
+ ```
299
+
300
+ ---
301
+
302
+ ## Contact & Support
303
+
304
+ Need a higher rate limit, a custom classifier, or additional support?
305
+ Visit [Contact](https://www.productcategorization.com/contact), or email support via your account dashboard.
306
+
307
+ ---
308
+
309
+ ## Related Services
310
+
311
+ Domain review becomes easier when analysts can reference a [domain classification database](https://webfilteringdatabase.com) for consistent category data. Strong classification coverage is useful for c
312
+ ompliance checks and internal security reviews. To operationalize those results, organizations may deploy a [managed filtering platform](https://webfilteringservice.com) across their networks.
313
+
314
+ Leverage our broader suite of AI-powered APIs to cover every aspect of your business’s data intelligence and privacy needs:
315
+
316
+ * **[Comment Moderation API](https://www.contentmoderationapi.net) – comment moderation api:**
317
+ Safeguard your community, app, or platform with industry-leading AI moderation for comments and user-generated content. Detect profanity, hate speech, spam, and toxicity in real time.
318
+
319
+ * **[Live Video Anonymization](https://www.anonymizationapi.com) – live video anonymization:**
320
+ Protect privacy with automatic anonymization of faces and sensitive objects in live video streams, supporting GDPR compliance and safeguarding user identities.
321
+
322
+ * **[Text Redaction API](https://www.redactionapi.net) – text redaction api:**
323
+ Redact personal data, financial information, or any sensitive fields from documents at scale using our high-precision redaction API.
324
+
325
+
326
+ * **[Domain Categorization Data](https://www.urlcategorizationdatabase.com) – domain categorization data:**
327
+ Access the world’s largest database of categorized domains for cybersecurity, web filtering, and content safety.
328
+
329
+
330
+ Our APIs integrate seamlessly with your product workflows, providing reliable, scalable, and secure endpoints for your business logic.
331
+
332
+ ---
333
+
334
+ ## References & Further Reading
335
+
336
+ For best-in-class taxonomy, AI, and categorization research, explore:
337
+
338
+ * [Stanford AI Lab](https://ai.stanford.edu)
339
+ * [MIT CSAIL](https://www.csail.mit.edu)
340
+ * [Berkeley AI Research](https://bair.berkeley.edu)
341
+ * [Oxford Internet Institute](https://www.oii.ox.ac.uk)
342
+ * [UCL Centre for Artificial Intelligence](https://www.ucl.ac.uk/ai)
343
+ * [Google AI Blog](https://ai.googleblog.com/)
344
+ * [Microsoft Research](https://www.microsoft.com/en-us/research/)
345
+ * [arXiv Machine Learning](https://arxiv.org/list/cs.LG/recent)
346
+
347
+ For taxonomy standards and e-commerce data:
348
+
349
+ * [Google Shopping Taxonomy](https://support.google.com/merchants/answer/6324436)
350
+ * [Shopify Product Taxonomy](https://github.com/Shopify/product-taxonomy)
351
+
352
+ ---
353
+
354
+ ## License
355
+
356
+ This library is distributed under the MIT License.
357
+
358
+ ---
359
+
360
+ ## Disclaimer
361
+
362
+ This project is unaffiliated with Google, Shopify, or Amazon.
363
+ All trademarks are property of their respective owners.
364
+
365
+ ---
366
+
367
+
368
+ Classification needs have expanded beyond products: [AI tool domain classification](https://www.aitoolsblocklist.com) 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.
369
+
370
+ # `__init__.py` Example
371
+
372
+ ```python
373
+ import requests
374
+
375
+ class ProductCategorizationAPI:
376
+ def __init__(self, api_key):
377
+ self.api_key = api_key
378
+ self.base_url = "https://www.productcategorization.com/api/"
379
+
380
+ def categorize_text(self, text, confidence=0, expand_context=0):
381
+ params = {
382
+ "query": text,
383
+ "api_key": self.api_key,
384
+ "confidence": str(confidence),
385
+ "expand_context": str(expand_context)
386
+ }
387
+ response = requests.get(self.base_url + "ecommerce/ecommerce_category6_get.php", params=params)
388
+ return response.json()
389
+
390
+ def categorize_url(self, url):
391
+ payload = {
392
+ 'query': url,
393
+ 'api_key': self.api_key,
394
+ 'data_type': 'url'
395
+ }
396
+ headers = {
397
+ 'Content-Type': 'application/x-www-form-urlencoded'
398
+ }
399
+ response = requests.post(self.base_url + "iab/iab_web_content_filtering_url.php", data=payload, headers=headers)
400
+ return response.json()
401
+
402
+ def categorize_image(self, image_url, text="", ip="0", login="0"):
403
+ # Download image to memory
404
+ image_response = requests.get(image_url)
405
+ if image_response.status_code != 200:
406
+ return {'error': 'Failed to download image'}
407
+ import io
408
+ image_file = io.BytesIO(image_response.content)
409
+ data = {
410
+ 'ip': ip,
411
+ 'api_key': self.api_key,
412
+ 'login': login,
413
+ 'text': text
414
+ }
415
+ files = {
416
+ 'image': ('image.jpg', image_file, 'image/jpeg')
417
+ }
418
+ response = requests.post(self.base_url + "ecommerce/ecommerce_shopify_image.php", data=data, files=files)
419
+ return response.json()
420
+ ```
421
+
422
+ ---
423
+ * [AI tool domain classification](https://www.aitoolsblocklist.com)
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.1
2
2
  Name: productcategorizationapi
3
- Version: 1.5
3
+ Version: 1.6
4
4
  Summary: product categorization API
5
5
  Home-page: https://www.productcategorization.com
6
6
  Author-email: info@productcategorizationapi.com
@@ -371,6 +371,9 @@ Description:
371
371
 
372
372
  ---
373
373
 
374
+
375
+ Classification needs have expanded beyond products: [AI tool domain classification](https://www.aitoolsblocklist.com) 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.
376
+
374
377
  # `__init__.py` Example
375
378
 
376
379
  ```python
@@ -424,7 +427,7 @@ Description:
424
427
  ```
425
428
 
426
429
  ---
427
-
430
+ * [AI tool domain classification](https://www.aitoolsblocklist.com)
428
431
 
429
432
  Keywords: product categorization,classification,categorization
430
433
  Platform: UNKNOWN
@@ -11,7 +11,7 @@ setup(
11
11
  name="productcategorizationapi",
12
12
 
13
13
  # The version of your project.
14
- version="1.5",
14
+ version="1.6",
15
15
 
16
16
  packages=find_packages(exclude="tests"),
17
17