Introduction to Product Categorization API
Product categorization API is one of the most accurate e-commerce categorisation services on the market.
API can be used with raw texts as well as websites. You can send full-path URLs and obtain real-time, live URL based website categorization.
We use two different taxonomies for categorizations:
- Products Taxonomy (custom, related to Google Products Taxonomy), supporting three Tiers
- IAB Taxonomy, supporting two Tiers
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.
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
You should not use multi-threading requests. Please set up your script to wait for a successful response before sending your next request. 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, Tier 1
Product categorization is based on taxonomy tailored to E-Commerce. Tier 1 categorization returns probabilities of text being classified as one of 21 possible categories.
HTTP Request
GET https://www.productcategorization.com/api/gpt/gpt_category1.php?query=polaroid land camera&api_key=b4dcde2ce5fb2d0b887b5eb6f0cd2000v
Query Parameters
Parameter | Type | Description |
---|---|---|
query | string | text to be categorized |
api_key | string | API key |
curl https://www.productcategorization.com/api/gpt/gpt_category1.php?query=polaroid land camera&api_key=b4dcde2ce5fb2d0b887b5eb6f0cd2000v
The above command returns JSON structured like this:
{
"classification": [
{
"category": "Cameras & Optics",
"value": 0.9987253421912741
},
{
"category": "Electronics",
"value": 0.000562862622295886
},
{
"category": "Home & Garden",
"value": 0.0005436545440954681
},
{
"category": "Business & Industrial",
"value": 0.00007432249947499341
},
{
"category": "Office Supplies",
"value": 0.000033526685721586356
},
{
"category": "Apparel & Accessories",
"value": 0.000027410018876003828
},
{
"category": "Arts & Entertainment",
"value": 0.000007521376738994588
},
{
"category": "Toys & Games",
"value": 0.000005882323386026919
},
{
"category": "Sporting Goods",
"value": 0.0000054131118222522225
},
{
"category": "Hardware",
"value": 0.0000033494618317838667
},
{
"category": "Baby & Toddler",
"value": 0.000002964992638430485
},
{
"category": "Food, Beverages & Tobacco",
"value": 0.0000016666852257013246
},
{
"category": "Vehicles & Parts",
"value": 0.0000011971066840144845
},
{
"category": "Media",
"value": 0.0000011131512981848846
},
{
"category": "Animals & Pet Supplies",
"value": 0.0000010786729107985125
},
{
"category": "Furniture",
"value": 8.600872153899655e-7
},
{
"category": "Luggage & Bags",
"value": 7.425740758731358e-7
},
{
"category": "Mature",
"value": 4.101005623841621e-7
},
{
"category": "Health & Beauty",
"value": 3.4821204250832534e-7
},
{
"category": "Religious & Ceremonial",
"value": 2.798537689428336e-7
},
{
"category": "Software",
"value": 5.3728060390120276e-8
}
],
"language": "en"
}
Product Categorization of Texts, Tier 2
Product categorization is based on taxonomy tailored to E-Commerce. Tier 2 categorization returns probabilities of text being classified as one of 182 possible categories.
HTTP Request
GET https://www.productcategorization.com/api/gpt/gpt_category2.php?query=polaroid camera&api_key=b4dcde2ce5fb2d0b887b5eb6f0cd2000v
Query Parameters
Parameter | Type | Description |
---|---|---|
query | string | text to be categorized |
api_key | string | API key |
curl https://www.productcategorization.com/api/gpt/gpt_category2.php?query=polaroid camera&api_key=b4dcde2ce5fb2d0b887b5eb6f0cd2000v
The above command returns JSON structured like this:
{
"classification": [
{
"category": "Cameras",
"value": 0.9160965830309336
},
{
"category": "Camera & Optic Accessories",
"value": 0.014408161930182316
},
{
"category": "Presentation Supplies",
"value": 0.013201065065928974
},
{
"category": "Video",
"value": 0.009239226281822454
},
{
"category": "Electronics Accessories",
"value": 0.00527737163793613
},
,...]
}
Product Categorization of Texts, Tier 3
Product categorization is based on taxonomy tailored to E-Commerce. Tier 1 categorization returns probabilities of text being classified as one of 1113 possible categories.
HTTP Request
GET https://www.productcategorization.com/api/gpt/gpt_category3.php?query=polaroid camera&api_key=b4dcde2ce5fb2d0b887b5eb6f0cd2000v
Query Parameters
Parameter | Type | Description |
---|---|---|
query | string | text to be categorized |
api_key | string | API key |
curl https://www.productcategorization.com/api/gpt/gpt_category3.php?query=polaroid camera&api_key=b4dcde2ce5fb2d0b887b5eb6f0cd2000v
The above command returns JSON structured like this:
{
"classification": [
{
"category": "Film Cameras",
"value": 0.5330920056393742
},
{
"category": "Digital Cameras",
"value": 0.25333581946019373
},
{
"category": "Disposable Cameras",
"value": 0.0663910677556255
},
{
"category": "Trail Cameras",
"value": 0.01740226805363727
},
{
"category": "Document Cameras",
"value": 0.015069146377420819
},
{
"category": "Surveillance Cameras",
"value": 0.011664482862068214
},
{
"category": "Borescopes",
"value": 0.008395065450695205
},
{
"category": "Video Cameras",
"value": 0.007260418504801398
},
{
"category": "Camera Lens Accessories",
"value": 0.00650744791929527
},,...]
}
Product Categorization of URLs, Tier 1
Product categorization is based on taxonomy tailored to E-Commerce. Tier 1 categorization returns probabilities of text from URL being classified as one of 21 possible categories.
HTTP Request
GET https://www.productcategorization.com/api/gpt/gpt_category1.php?query=https://eu.polaroid.com/collections/instant-cameras&api_key=b4dcde2ce5fb2d0b887b5eb6f0cd2000v&data_type=url
Query Parameters
Parameter | Type | Description |
---|---|---|
query | string | text to be categorized |
api_key | string | API key |
data_type | string | should be set to 'url' |
curl https://www.productcategorization.com/api/gpt/gpt_category1.php?query=https://eu.polaroid.com/collections/instant-cameras&api_key=b4dcde2ce5fb2d0b887b5eb6f0cd2000v&data_type=url
The above command returns JSON structured like this:
{
"classification": [
{
"category": "Cameras & Optics",
"value": 0.9992289896015756
},
{
"category": "Home & Garden",
"value": 0.0006520692868512297
},
{
"category": "Apparel & Accessories",
"value": 0.00004644383948321836
},
{
"category": "Electronics",
"value": 0.00003771973664942523
},
{
"category": "Business & Industrial",
"value": 0.000008166161487290707
},
{
"category": "Office Supplies",
"value": 0.000007549115352502271
},...]
}
Product Categorization of URLs, Tier 2
Product categorization is based on taxonomy tailored to E-Commerce. Tier 1 categorization returns probabilities of text from URL being classified as one of 186 possible categories.
HTTP Request
GET https://www.productcategorization.com/api/gpt/gpt_category2.php?query=https://eu.polaroid.com/collections/instant-cameras&api_key=b4dcde2ce5fb2d0b887b5eb6f0cd2000v&data_type=url
Query Parameters
Parameter | Type | Description |
---|---|---|
query | string | text to be categorized |
api_key | string | API key |
data_type | string | should be set to 'url' |
curl https://www.productcategorization.com/api/gpt/gpt_category2.php?query=https://eu.polaroid.com/collections/instant-cameras&api_key=b4dcde2ce5fb2d0b887b5eb6f0cd2000v&data_type=url
The above command returns JSON structured like this:
{
"classification": [
{
"category": "Cameras",
"value": 0.9245012943174596
},
{
"category": "Presentation Supplies",
"value": 0.004850704982243057
},...]
}
Product Categorization of URLs, Tier 3
Product categorization is based on taxonomy tailored to E-Commerce. Tier 1 categorization returns probabilities of text from URL being classified as one of 1113 possible categories.
HTTP Request
GET https://www.productcategorization.com/api/gpt/gpt_category3.php?query=https://eu.polaroid.com/collections/instant-cameras&api_key=b4dcde2ce5fb2d0b887b5eb6f0cd2000v&data_type=url
Query Parameters
Parameter | Type | Description |
---|---|---|
query | string | text to be categorized |
api_key | string | API key |
data_type | string | should be set to 'url' |
curl https://www.productcategorization.com/api/gpt/gpt_category3.php?query=https://eu.polaroid.com/collections/instant-cameras&api_key=b4dcde2ce5fb2d0b887b5eb6f0cd2000v&data_type=url
The above command returns JSON structured like this:
{
"classification": [
{
"category": "Film Cameras",
"value": 0.8221396513265392
},
{
"category": "Digital Cameras",
"value": 0.03174787172824993
},
{
"category": "Disposable Cameras",
"value": 0.02434788833270771
},
{
"category": "Picture Frames",
"value": 0.0020415917541745025
},
{
"category": "Watch Accessories",
"value": 0.0019267665992148237
},
{
"category": "Video Cameras",
"value": 0.0018906391929454846
},
{
"category": "Surveillance Cameras",
"value": 0.001548661227171665
},...]
}
IAB Categorization of Texts, Tier 1
IAB categorization is based on taxonomy from IAB organization.
Tier 1 categorization returns probabilities of text being classified as one of 29 possible categories.
HTTP Request
GET https://www.productcategorization.com/api/iab/gpt_category1.php?query=credit card&api_key=b4dcde2ce5fb2d0b887b5eb6f0cd2000v
Query Parameters
Parameter | Type | Description |
---|---|---|
query | string | text to be categorized |
api_key | string | API key |
curl https://www.productcategorization.com/api/iab/gpt_category1.php?query=credit card&api_key=b4dcde2ce5fb2d0b887b5eb6f0cd2000v
The above command returns JSON structured like this:
{
"classification": [
{
"category": "Personal Finance",
"value": 0.9761399141331873
},
{
"category": "Hobbies & Interests",
"value": 0.012164815580256418
},
{
"category": "Automotive",
"value": 0.0025196087021092215
},
{
"category": "Music and Audio",
"value": 0.0008752506600661922
},
{
"category": "Style & Fashion",
"value": 0.0008616063832503892
},
{
"category": "Fine Art",
"value": 0.0007356838538989182
},
{
"category": "Events and Attractions",
"value": 0.0006860379172393203
},
{
"category": "Business and Finance",
"value": 0.0006617396989540662
},
{
"category": "Shopping",
"value": 0.0005497554147123015
},
{
"category": "Sports",
"value": 0.0005244575592904009
},
{
"category": "Food & Drink",
"value": 0.0005127335219828095
},
{
"category": "Technology & Computing",
"value": 0.00047175450468135173
},
{
"category": "Medical Health",
"value": 0.00037166903273757674
},
{
"category": "Pop Culture",
"value": 0.00033420130176418624
},
{
"category": "Travel",
"value": 0.00033124861987561744
},
{
"category": "Science",
"value": 0.0003090364749867773
},
{
"category": "Movies",
"value": 0.00029288123865858144
},
{
"category": "Education",
"value": 0.0002908401351480208
},
{
"category": "News and Politics",
"value": 0.00022847415444144793
},
{
"category": "Home & Garden",
"value": 0.0002152725238608538
},
{
"category": "Pets",
"value": 0.00017486261718002182
},
{
"category": "Television",
"value": 0.000124120100803851
},
{
"category": "Healthy Living",
"value": 0.00011409833413449834
},
{
"category": "Religion & Spirituality",
"value": 0.00011219133637975148
},
{
"category": "Family and Relationships",
"value": 0.00010729327394592739
},
{
"category": "Careers",
"value": 0.00010286095832155701
},
{
"category": "Books and Literature",
"value": 0.00009633052630078263
},
{
"category": "Real Estate",
"value": 0.00008766190043931586
},
{
"category": "Video Gaming",
"value": 0.000003599541392274362
}
],
"language": "en"
}
IAB Categorization of Texts, Tier 2
IAB categorization is based on taxonomy from IAB organization.
Tier 1 categorization returns probabilities of text being classified as one of 447 possible categories.
HTTP Request
GET https://www.productcategorization.com/api/iab/gpt_category2.php?query=credit card&api_key=b4dcde2ce5fb2d0b887b5eb6f0cd2000v
Query Parameters
Parameter | Type | Description |
---|---|---|
query | string | text to be categorized |
api_key | string | API key |
curl https://www.productcategorization.com/api/iab/gpt_category2.php?query=credit card&api_key=b4dcde2ce5fb2d0b887b5eb6f0cd2000v
The above command returns JSON structured like this:
{
"classification": [
{
"category": "Personal Debt",
"value": 0.8993637222986489
},...]
}
IAB Categorization of URLs, Tier 1
IAB categorization is based on taxonomy from IAB organization.
Tier 1 categorization returns probabilities of text being classified as one of 29 possible categories.
HTTP Request
GET https://www.productcategorization.com/api/iab/iab_category1_url.php?query=https://www.elle.com/&api_key=b4dcde2ce5fb2d0b887b5eb6f0cd2000v
Query Parameters
Parameter | Type | Description |
---|---|---|
query | string | text to be categorized |
api_key | string | API key |
curl https://www.productcategorization.com/api/iab/iab_category1_url.php?query=https://www.elle.com/&api_key=b4dcde2ce5fb2d0b887b5eb6f0cd2000v
The above command returns JSON structured like this:
{
"classification": [
{
"category": "Style & Fashion",
"value": 0.7445648974299292
},
{
"category": "Pop Culture",
"value": 0.19117375948105383
},
{
"category": "Events and Attractions",
"value": 0.05735528094741476
},,...]
}
IAAB Categorization of URLs, Tier 2
IAB categorization is based on taxonomy from IAB organization.
Tier 1 categorization returns probabilities of text being classified as one of 447 possible categories.
HTTP Request
GET https://www.productcategorization.com/api/gpt/gpt_category2.php?query=https://www.elle.com/&api_key=b4dcde2ce5fb2d0b887b5eb6f0cd2000v&data_type=url
Query Parameters
Parameter | Type | Description |
---|---|---|
query | string | text to be categorized |
api_key | string | API key |
data_type | string | should be set to 'url' |
curl https://www.productcategorization.com/api/gpt/gpt_category2.php?query=https://www.elle.com/&api_key=b4dcde2ce5fb2d0b887b5eb6f0cd2000v&data_type=url
The above command returns JSON structured like this:
{
"classification": [
{
"category": "Street Style",
"value": 0.4850728519866097
},
{
"category": "Celebrity Style",
"value": 0.23190837126729394
},
{
"category": "Fashion Trends",
"value": 0.12005606546256739
},
{
"category": "Fashion Events",
"value": 0.10266536418561253
},
{
"category": "Beauty",
"value": 0.007215169792467588
},
{
"category": "Designer Clothing",
"value": 0.004916532775707807
},
{
"category": "Astrology",
"value": 0.0035571097795627895
},
{
"category": "High Fashion",
"value": 0.00282184801599979
},,...]
}
Errors
The API returns a status value in each request. Example of status returned as 200:
{"classification": [{"category": "News and Politics", "value": 0.9722175625682967},....}], "language": "en", "status": 200}
In case of error, the status error code can be interpreted using the following table
Error Code | Meaning |
---|---|
408 | URL could not be loaded |
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. |
405 | Unsupported language |
406 | You have exceeded your daily usage limit. This is returned only in case you have used an invalid API key. |
407 | Webpage did not contain enough text. |
503 | Service Unavailable -- We're temporarily offline for maintenance. Please try again later. |