List and Search

list and search categories get get /categories the categories api exposes just one endpoint /categories categories are expressed in a hierarchical structure, each category may have one or more child categories as determined by the has children property you can retrieve the child categories of a given category by passing the parent category id in the parent id parameter to retrieve the top level categories make a request without any parent id top level categories have their is root=true property set to true parameters the following querystring (http get) parameters allow you to refine the results returned by the categories api parameter required description api key required the api key for your account id optional a single id of the category to retrieve note that id cannot be used when parent id or search term are used parent id optional the id of the parent category to retrieve child categories for note that parent id cannot be used when id or search term are used search term optional searches the entire category hierarchy for categories containing the search term i e search term=appliances (to return only categories containing the string appliances ) note that search term cannot be used when id or parent id are used results the categories api returns the following properties property type description categories array an array of category objects containing details of a given category the categories array is present when either the parent id or search term request parameters are used id string the id of the category can be passed into the category id parameter of a subsequent category https //docs trajectdata com/redcircleapi/product data api/parameters/category api request name string the name of the category has children boolean true/false as to whether this category has child categories is root boolean true/false as to whether this category is a top level (root) category path string the fully qualified path to the category in the category hierarchy, delimited by ">" characters for example category 1 > category 2 > category 3 current category object an object with the same properties as the category objects in the categories array showing details of the current category note that current category is only present when a request is made using the parent id request parameter (i e when retrieving child categories for a given parent id ) parent category object an object with the same properties as the category objects in the categories array showing details of the parent category note that parent category is only present when a request is made using the parent id request parameter (i e when retrieving child categories for a given parent id ) parent category shows details of the category that is the parent of the category specified in parent id note parent category is not returned if the category specified in the parent id request parameter is is root=true category object an object with the same properties as the category objects in the categories array showing details of the single category requested by the id parameter note that category is only present when a request is made using the id request parameter (i e when retrieving details of a single category) example listing root categories in the example below we retrieve all top level (root) categories curl l get https //api redcircleapi com/categories \\ d api key="demo"const axios = require('axios'); axios get('https //api redcircleapi com/categories?api key=demo') then(response => { const apiresponse = response data; console log("categories ", json stringify(apiresponse, 0, 2); }) catch(error => { console error(error); });import requests import json params = { 'api key' 'demo' } api result = requests get('https //api redcircleapi com/categories', { params }) api response = api result json() print "categories ", json dumps(api response)\<?php $querystring = http build query(\[ 'api key' => 'demo' ]); $ch = curl init('https //api redcircleapi com/categories', $querystring); curl setopt($ch, curlopt returntransfer, true); curl setopt($ch, curlopt followlocation, true); \# the following options are required if you're using an outdated openssl version \# more details https //www openssl org/blog/blog/2021/09/13/letsencryptrootcertexpire/ curl setopt($ch, curlopt ssl verifyhost, false); curl setopt($ch, curlopt ssl verifypeer, false); curl setopt($ch, curlopt timeout, 180); $json = curl exec($ch); curl close($ch); $api result = json decode($json, true); print r($api result); ?> the categories api responds with the top level (root) categories in the categories property { "request info" { "success" true }, "categories" \[ { "id" "5xt1a", "name" "grocery", "has children" true, "is root" true, "path" "grocery", "link" "https //www target com/c/grocery/ /n 5xt1a", "type" "standard", "domain" "target com" }, { "id" "5xsz1", "name" "household essentials", "has children" true, "is root" true, "path" "household essentials", "link" "https //www target com/c/household essentials/ /n 5xsz1", "type" "standard", "domain" "target com" }, { "id" "5xtb0", "name" "toys", "has children" true, "is root" true, "path" "toys", "link" "https //www target com/c/toys/ /n 5xtb0", "type" "standard", "domain" "target com" }, { "id" "5xtg5", "name" "video games", "has children" true, "is root" true, "path" "video games", "link" "https //www target com/c/video games/ /n 5xtg5", "type" "standard", "domain" "target com" }, { "id" "5xsxe", "name" "movies, music & books", "has children" true, "is root" true, "path" "movies, music & books", "link" "https //www target com/c/movies music books/ /n 5xsxe", "type" "standard", "domain" "target com" }, { "id" "5xt85", "name" "sports & outdoors", "has children" true, "is root" true, "path" "sports & outdoors", "link" "https //www target com/c/sports outdoors/ /n 5xt85", "type" "standard", "domain" "target com" }, { "id" "55r1x", "name" "beauty", "has children" true, "is root" true, "path" "beauty", "link" "https //www target com/c/beauty/ /n 55r1x", "type" "standard", "domain" "target com" }, { "id" "5xtnr", "name" "furniture", "has children" true, "is root" true, "path" "furniture", "link" "https //www target com/c/furniture/ /n 5xtnr", "type" "standard", "domain" "target com" }, { "id" "hz89j", "name" "kitchen & dining", "has children" true, "is root" true, "path" "kitchen & dining", "link" "https //www target com/c/kitchen dining/ /n hz89j", "type" "standard", "domain" "target com" }, { "id" "5xtg6", "name" "electronics", "has children" true, "is root" true, "path" "electronics", "link" "https //www target com/c/electronics/ /n 5xtg6", "type" "standard", "domain" "target com" }, { "id" "xcoz4", "name" "kids", "has children" true, "is root" true, "path" "kids", "link" "https //www target com/c/kids/ /n xcoz4", "type" "standard", "domain" "target com" } ] } example listing child categories in the example below we retrieve child categories for a parent category with id 5xtg6 curl l get https //api redcircleapi com/categories \\ d api key="demo" \\ d parent id="5xtg6"const axios = require('axios'); axios get('https //api redcircleapi com/categories?api key=demo\&parent id=5xtg6') then(response => { const apiresponse = response data; console log("categories ", json stringify(apiresponse, 0, 2); }) catch(error => { console error(error); });import requests import json params = { 'api key' 'demo', 'parent id' '5xtg6' } api result = requests get('https //api redcircleapi com/categories', { params }) api response = api result json() print "categories ", json dumps(api response)\<?php $querystring = http build query(\[ 'api key' => 'demo', 'parent id' => '5xtg6' ]); $ch = curl init('https //api redcircleapi com/categories', $querystring); curl setopt($ch, curlopt returntransfer, true); curl setopt($ch, curlopt followlocation, true); \# the following options are required if you're using an outdated openssl version \# more details https //www openssl org/blog/blog/2021/09/13/letsencryptrootcertexpire/ curl setopt($ch, curlopt ssl verifyhost, false); curl setopt($ch, curlopt ssl verifypeer, false); curl setopt($ch, curlopt timeout, 180); $json = curl exec($ch); curl close($ch); $api result = json decode($json, true); print r($api result); ?> the categories api responds with the child categories for parent category with id 5xtg6 in the categories property { "request info" { "success" true }, "current category" { "id" "5xtg6", "name" "electronics", "has children" true, "is root" true, "path" "electronics", "link" "https //www target com/c/electronics/ /n 5xtg6", "type" "standard", "domain" "target com" }, "categories" \[ { "id" "5xtez", "name" "cameras", "has children" true, "is root" false, "path" "electronics > cameras", "link" "https //www target com/c/cameras camcorders electronics/ /n 5xtez", "parent id" "5xtg6", "parent name" "electronics", "type" "standard", "domain" "target com" }, { "id" "5xte8", "name" "cell phones", "has children" true, "is root" false, "path" "electronics > cell phones", "link" "https //www target com/c/cell phones electronics/ /n 5xte8", "parent id" "5xtg6", "parent name" "electronics", "type" "standard", "domain" "target com" }, { "id" "5xtfc", "name" "computers & office", "has children" true, "is root" false, "path" "electronics > computers & office", "link" "https //www target com/c/computers office electronics/ /n 5xtfc", "parent id" "5xtg6", "parent name" "electronics", "type" "standard", "domain" "target com" }, { "id" "5xte2", "name" "speakers & audio systems", "has children" true, "is root" false, "path" "electronics > speakers & audio systems", "link" "https //www target com/c/speakers audio systems electronics/ /n 5xte2", "parent id" "5xtg6", "parent name" "electronics", "type" "standard", "domain" "target com" }, { "id" "551ss", "name" "wearable technology", "has children" true, "is root" false, "path" "electronics > wearable technology", "link" "https //www target com/c/wearable technology electronics/ /n 551ss", "parent id" "5xtg6", "parent name" "electronics", "type" "standard", "domain" "target com" }, { "id" "5xteg", "name" "headphones", "has children" true, "is root" false, "path" "electronics > headphones", "link" "https //www target com/c/headphones electronics/ /n 5xteg", "parent id" "5xtg6", "parent name" "electronics", "type" "standard", "domain" "target com" } ] } next steps categories api overview https //docs trajectdata com/redcircleapi/categories api/overview