MetaLocator's Where to Buy solution provides an API which returns the links, prices, product and retailer details to support a complete custom user interface or mobile app integration. The Retailer API is intented to support the creation of a UI similar to the below, which includes product details, a list of available retailers from which to purchase, links, images, stock status and prices.
The Retailer API is an extension of the PaaS API available to subscribers of Where to Buy. See the PaaS API documentation for fundamental issues like authentication and evaluating responses.
Before beginning, be sure to have your account API key at the ready.
The API provides results in various contexts based on typical use cases as described below:
SKU Context: This is the most common use case, which returns a list of retailers with links to specific product detail pages for the requested SKU.
Group Context: Useful for displaying a "Where to Buy" interface that displays all retailers which offer any product in the requested product group. These are commonly used at a product family page. The links returned in this context are also the Search URL with the Group Search Term for the product automatically substituded.
Global Context: Useful for displaying a generic "Where to Buy" display that simply displays all retailers, but does not filter by a specific product or product group. The links returned in this context correspond to the retailer Search URL and Search Term configured in the retailer profile.
SKU Context
In the SKU context, the API call will return an array containing all retailers that offer the requested SKU.
Sample API call:
https://code.metalocator.com/webapi/retailers/getretailers?apikey=NNNNNN&Itemid=XXXXXX&locale=en-US&sku[products]=YYYYY
Be sure to replace your API Key and a valid Interface ID in the API key above.
The sku[products] value should come from the SKU field in the products table as shown below:
The above API call will return an array containing all retailers in the en-US locale that currently offer the requested SKU. See the retailer onboarding article for a description of each retailer field. Essential fields are highlighted below, including name, logo URL, the price and link.
Group Context
Useful for displaying a "Where to Buy" interface that displays all retailers which offer any product in the requested product group. These are commonly used on a product family page. The product links returned in this context are the Search URL with the Group Search Term for the product automatically substituted.
Sample API call:
https://code.metalocator.com/webapi/retailers/getretailers?apikey=NNNNNN&Itemid=XXXXXX&groupid[products]=ES100
The GroupID is a string value shared among multiple products in the system.
Notice the product_link now contains the "Group Search Term" inserted into the the product link.
Global Context
In the global context, the API call will return an array containing all retailers configured in the system. This should not be used when displaying retailer links in the context of a specific product or family of products.
Sample API call:
https://code.metalocator.com/webapi/retailers/getretailers?apikey=NNNNNN&Itemid=XXXXXX
Be sure to replace your API Key and a valid Interface ID in the API key above.
The above API call will return an array containing all retailers configured in the system as below:
"name":"Retailer Display Name",
"logo":"https:\/\/ .. images\/bulk\/gallery\/logo.png",
"id":"1",
"searchurl":"https:\/\/www.retailer.com\/?searchFlag=true&text=%s",
"retailer_name":"Retailer Display Name",
"allowredirect":"0",
"locale":"en-US",
"countrycode":"us",
"campaign_lookup":"[[\"\",\"\",\"\"]]",
"urlappend":"",
"urlappendgroupid":"",
"affiliatedeeplink":"",
"marketplace":"0",
"displaylink":null,
"onlineonly":"0",
"store_locator_url":"",
"add_to_cart_url":"",
"retailer_custom_link":"",
"retailer_description":"",
"product_link":"https:\/\/www.retailer.com\/en_us\/search\/?term="
See the retailer onboarding article for a description of each field.
The product_link is the URL that should be used for the end-user