Search for specific products from a vast catalog of over 350 million products, and get back the product price, brand, merchant, category price, an image URL and an affiliate URL.
Authorization Header
You must add authorization headers to this request. Please see the Authorization section for further details.
How Filters Work
You may enter a query, use a filter, or use both. For example, requesting query=nike+running+shoes
with the filter category=Fashion
will return nike running shoes in the Fashion category. You can also pass an array for all parameters designated as an "array of strings." For example, country[]=US&country[]=CA
for United States and Canada.
Additionally, if you want to exclude terms from your search, you can pass a !
in front of your value. For example: query=running+shoes&country=!CA
to exclude products from Canadian merchants in your search.
How the Price Filter Works
The price filter allows you to match products at a specific price, above a price, below a price or between two price points. This is achieved by defining the lower and upper limit:
price=10.00 | Match products that have a specific price. |
price=10.00, | Match products that are equal to $10 or above. |
price=,10.00 | Match products that are less than or equal to $10. |
price=10,25 | Match products between and equal to $10 and $25. Notice that a decimal format is not required. |
Category Taxonomy
Categories go three levels deep from 35 root categories. You may filter your searches with any depth of these categories. While not case-sensitive, filtering by category is character and phrase sensitive. Filtering by category=Cameras & Photo
will not work, but category=Cameras and Photo
will.
Adult and Gambling
Adult and Gambling > Adult
Adult and Gambling > Gambling
Adult and Gambling > Other Adult and Gambling
Art and Entertainment
Art and Entertainment > DVDs and Videos
Art and Entertainment > Music
Art and Entertainment > Art
Art and Entertainment > Event Tickets
Art and Entertainment > Other Art and Entertainment
Automotive
Automotive > Automotive Vehicles
Automotive > Auto Electronics
Automotive > Auto Parts and Tools
Automotive > Other Auto
Cameras and Photo
Cameras and Photo > Camera Hardware and Accessories
Cameras and Photo > Video Hardware and Accessories
Cameras and Photo > Other Camera
Career and Employment
Cell Phones and Mobile
Cell Phones and Mobile > Mobile Devices
Cell Phones and Mobile > Mobile Device Accessories
Cell Phones and Mobile > Mobile Device Software
Cell Phones and Mobile > Other Mobile
Collectibles
Collectibles > Sports Memorabilia
Collectibles > Stamps
Collectibles > Coins and Paper Money
Collectibles > Other Collectibles
Computing
Computing > Computing, Hardware and Accessories
Computing > Computing Software
Computing > Other Computing
Consumer Electronics
Consumer Electronics > Home Electronics
Consumer Electronics > Portable Electronics
Consumer Electronics > Other Electronics
Dating
Education
Family and Baby
Family and Baby > Baby and Maternity Clothing
Family and Baby > Baby Other
Fashion
Fashion > Clothing
Fashion > Clothing > Men's Clothing
Fashion > Clothing > Women's Clothing
Fashion > Clothing > Kid's Clothing
Fashion > Clothing > Other Clothing
Fashion > Shoes
Fashion > Shoes > Men's Shoes
Fashion > Shoes > Women's Shoes
Fashion > Shoes > Kid's Shoes
Fashion > Shoes > Other Shoes
Fashion > Luggage and Bags
Fashion > Luggage and Bags > Women's Luggage and Bags
Fashion > Luggage and Bags > Other Luggage
Fashion > Fashion Accessories
Fashion > Fashion Accessories > Men's Fashion Accessories
Fashion > Fashion Accessories > Women's Fashion Accessories
Fashion > Fashion Accessories > Kid's Fashion Accessories
Fashion > Fashion Accessories > Other Fashion Accessories
Fashion > Other Fashion
Financial Services
Firearms and Hunting
Firearms and Hunting > Firearms
Firearms and Hunting > Knives
Firearms and Hunting > Fishing
Firearms and Hunting > Bow Hunting
Firearms and Hunting > Survival Gear
Firearms and Hunting > Other Hunting
Food and Drink
Food and Drink > Standard Food
Food and Drink > Gourmet Food
Food and Drink > Other Food and Drink
Health and Beauty
Health and Beauty > Health
Health and Beauty > Beauty
Health and Beauty > Other Health and Beauty
Home and Garden
Home and Garden > Home Decor
Home and Garden > Appliances
Home and Garden > Home Improvement
Home and Garden > Kitchen, Dining and Bar
Home and Garden > Gardening
Home and Garden > Gift
Home and Garden > Flowers
Home and Garden > Cleaning Supplies
Home and Garden > Other Home and Garden
Industrial and Supply
Industrial and Supply > Office Supplies
Industrial and Supply > Office Electronics
Industrial and Supply > Industrial
Industrial and Supply > Other Industrial and Supply
Jewelry and Watches
Jewelry and Watches > Jewelry
Jewelry and Watches > Watches
Jewelry and Watches > Other Jewelry
Lifestyle
Motorcycles and Powersports
Motorcycles and Powersports > Motorcycling
Motorcycles and Powersports > ATVs
Motorcycles and Powersports > Boating
Motorcycles and Powersports > Other Motorcycles and Powersports
Music and Musicians
Music and Musicians > Musical Instruments
Music and Musicians > Musical Accessories
Music and Musicians > Other Musical
News, Books and Magazines
News, Books and Magazines > Books and eBooks
News, Books and Magazines > Magazines and Newspaper
News, Books and Magazines > Other Books
Online Services
Other
Pets
Pets > Dogs
Pets > Fish
Pets > Cat
Pets > Birds
Pets > Other Pets
Real Estate
Religious and Ceremonial
Self-Help
Shopping and Coupons
Sports and Fitness
Sports and Fitness > Bicycling
Sports and Fitness > Water Sports
Sports and Fitness > Golfing
Sports and Fitness > Winter Sports
Sports and Fitness > Outdoor Apparel
Sports and Fitness > Camping
Sports and Fitness > Other Sports and Fitness
Toys and Hobbies
Toys and Hobbies > Toys
Toys and Hobbies > Games
Toys and Hobbies > Crafts
Toys and Hobbies > Hobbies
Toys and Hobbies > Costumes
Toys and Hobbies > Other Toys and Hobbies
Travel
Travel > Other Travel
Video Gaming
Video Gaming > Video Games
Video Gaming > Gaming Hardware
Video Gaming > Other Gaming
Faceting
Faceting is often used to create a navigation menu for product results. You can facet on merchant, brand, category1, category2, and category3. You may also nest your facets: If you want the full nested heirarchy of categories for a query, simply request facet=category1>category2>category3
separating each nested level with a >
.
A common request for facets includes merchants, brands and the full depth of categories. This can be achieved in the same request by separating each facet with a ,
. For example: facet=merchant,brand,category1>category2>category3
.
Now the facet index response will include "merchant", "brand" and "category1>category2>category3":
"facet":{
"merchant":{
"branch":"merchant",
"buckets":{
"Amazon":{
"count":2008877
},
"Walmart.com":{
"count":439688
},
[...]
}
},
"brand":{
"branch":"brand",
"buckets":{
"HP":{
"count":98931
},
"Ford":{
"count":42523
},
[...]
}
},
"category1>category2>category3":{
"branch":"category1",
"buckets":{
"Automotive":{
"count":2278172,
"category1>category2>category3":{
"branch":"category2",
"buckets":{
"Automotive > Auto Parts and Tools":{
"count":1435385
},
"Automotive > Auto Electronics":{
"count":2061
},
"Automotive > Other Auto":{
"count":243
}
}
}
},
"Fashion":{
"count":468039,
"category1>category2>category3":{
"branch":"category2",
"buckets":{
"Fashion > Clothing":{
"count":5372,
"category1>category2>category3":{
"branch":"category3",
"buckets":{
"Fashion > Clothing > Men's Clothing":{
"count":3142
},
"Fashion > Clothing > Women's Clothing":{
"count":67
}
}
}
},
"Fashion > Shoes":{
"count":543,
"category1>category2>category3":{
"branch":"category3",
"buckets":{
"Fashion > Shoes > Women's Shoes":{
"count":409
},
"Fashion > Shoes > Men's Shoes":{
"count":132
}
}
}
},
"Fashion > Fashion Accessories":{
"count":316,
"category1>category2>category3":{
"branch":"category3",
"buckets":{
"Fashion > Fashion Accessories > Men's Fashion Accessories":{
"count":291
},
"Fashion > Fashion Accessories > Women's Fashion Accessories":{
"count":25
}
}
}
},
"Fashion > Luggage and Bags":{
"count":20
},
"Fashion > Other Fashion":{
"count":9
}
}
}
},
[...]
}
}
}
How can I create a navigation menu from this?
Glad you asked! Try using this recursive function in PHP to iterate through the facets to make a nested HTML list:
<?php
function buildFacetNavigation($branch, $baseUri = '/', $level = 0, $facet = null)
{
if ($level > 0)
{
$return = null;
foreach ($branch as $label => $row)
{
$l = $label;
if (strstr($label, '>'))
{
$label = explode('>', $label);
for ($i=1;$i<=3;$i++)
{
if (key_exists($level-$i, $label))
{
$ll = $label[$level-$i];
break;
}
}
$label = trim($ll);
}
$f = explode('>', $facet);
$urlFacet = $f[$level-1];
$urlFacet = stristr($urlFacet, 'category') ? 'category' : $urlFacet;
$return .= '<li>';
$slug = ($urlFacet . '=' . urlencode($l));
$return .= '<a href="' . $baseUri . (strstr($baseUri, '?') ? '&' : '?') . $slug . '">';
$return .= $label . ' (' . number_format($row['count']) . ')';
$return .= '</a>';
if (!stristr($f[0], 'category'))
{
$appendBaseUri = '&' . $slug;
}
if (key_exists($facet, $row) && key_exists('buckets', $row[$facet]))
{
$return .= '<ul class="navigation level' . ($level + 1) . '">';
$return .= buildFacetNavigation($row[$facet]['buckets'], $baseUri . $appendBaseUri, $level + 1, $facet);
$return .= '</ul>';
}
$return .= '</li>';
}
return $return;
}
$navigation = null;
foreach ($branch as $facetName => $row)
{
$facetLabel = ucfirst(preg_replace('/[0-9]/', '', $row['branch']));
$navigation .= '<h4>' . $facetLabel . '</h4>';
if (key_exists('buckets', $row))
{
$navigation .= '<ul class="navigation level' . ($level + 1) . '">';
$navigation .= buildFacetNavigation($row['buckets'], $baseUri, $level + 1, $facetName);
$navigation .= '</ul>';
}
}
return $navigation;
}
We can now pass the facet
index from the API response to the function buildFacetNavigation
to get back HTML.
<?php
$ch = curl_init("https://rest.viglink.com/api/product/search?apiKey=e3b0bcb2925a1a09503e21df441af8aa&query=nike+running+shoes&country=us&facet=merchant,brand,category1>category2>category3");
curl_setopt($ch, CURLOPT_HTTPHEADER, 'Authorization: secret {SECRET KEY}');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
$response = curl_exec($ch);
curl_close($ch);
$json = json_decode($response, true);
$navigation = buildFacetNavigation($response['facet'], '/index?query=' . $_GET['query']);
echo $navigation;
$navigation
would now contain the HTML for a navigable menu:
<h4>Merchant</h4>
<ul class="navigation level1">
<li><a href="/index?query=nike+running+shoes&merchant=Amazon">Amazon (2,008,877)</a></li>
<li><a href="/index?query=nike+running+shoes&merchant=Walmart.com">Walmart.com (439,688)</a></li>
[...]
</ul>
<h4>Brand</h4>
<ul class="navigation level1">
<li><a href="/index?query=nike+running+shoes&brand=HP">HP (98,931)</a></li>
<li><a href="/index?query=nike+running+shoes&brand=Ford">Ford (42,523)</a></li>
[...]
</ul>
<h4>Category</h4>
<ul class="navigation level1">
<li><a href="/index?query=nike+running+shoes&category=Automotive">Automotive (2,278,172)</a>
<ul class="navigation level2">
<li><a href="/index?query=nike+running+shoes&category=Automotive+%3E+Auto+Parts+and+Tools">Automotive > Auto Parts and Tools (1,435,385)</a></li>
<li><a href="/index?query=nike+running+shoes&category=Automotive+%3E+Auto+Electronics">Automotive > Auto Electronics (2,061)</a></li>
<li><a href="/index?query=nike+running+shoes&category=Automotive+%3E+Other+Auto">Automotive > Other Auto (243)</a></li>
</ul>
</li>
<li><a href="/index?query=nike+running+shoes&category=Fashion">Fashion (468,039)</a></li>
[...]
</ul>