Real-Time Catalog Instructions
The SourceKnowledge Real-Time Catalog Feed allows partners to query SourceKnowledge’s store of catalogs in real time.
Endpoint
Your endpoint should look as follows:
http://catalog.provenpixel.com/pf/PARTNER-NAME/json?q=YOUR QUERY&n=10&EXTRA_PARAMETERS
The actual URL you should use will be provided by your account manager and will contain the correct PARTNER-NAME in the URL. The results are in JSON format.
Other Formats
To view the catalog results in a friendlier format for a quick check, you can use:
http://catalog.provenpixel.com/pf/PARTNER-NAME/?q=YOUR QUERY&n=10&EXTRA_PARAMETERS
This provides a very basic browse-able HTML view of the catalog results.
Query Parameters
The following query parameters are accepted:
q - A query string, used to text match against titles, descriptions and brands in the catalog store
n - Number of results to return, an integer
The q parameter defines the main "query" constituting the essence of the search. The + and - characters are treated as "mandatory" and "prohibited" modifiers for terms. Text wrapped in balanced quote characters (for example, "San Jose") is treated as a phrase. It is strongly advised to always url encode the query parameters.
Examples:
Query | Summary | Encoded Example |
yellow hat | Can contain either yellow or hat | q=yellow+hat |
+yellow +hat | Must contain both yellow and hat | q=%2Byellow+%2Bhat |
title:blue | Title must contain blue | q=title%3Ablue |
title:red | Title must not contain red | q=-title%3Ared |
It is also possible to use the following query parameters:
Name | Summary | Example |
q.title | Title of the product | q.title=cabinet |
q.description | Description of the product | q.description=jeans |
q.brand | Brand of the product | q.brand=good+american |
q.shop | Name of the shop | q.shop=caskers |
q.productType | Product Type of the product | q.productType=shirt |
q.category | Category of the product | q.category=Home+%26+Garden+>+Decor |
q.price | Price of the product in $ | q.price=24.99 |
q.salePrice | Sale Price of the product in $ | q.salePrice=[20 TO 50] |
q.discountRate | Discount Rate of the product in % | q.discountRate=[25 TO *] |
q.discountValue | Discount Value of the product in $ | q.discountValue=[50 TO 100] |
Please note the following:
category must be URL encoded if an ampersand is present
price, salePrice, discountRate and discountValue offer better results when a range is used:
q.salePrice=[10 TO 20](Between 10 and 20$)q.discountRate=[25 TO *](Higher than 25% off)
EXTRA_PARAMETERS (Macros):
You can send us more information by adding extra parameters e.g.
_m_device_ip=USER_IP_ADDRESS - end user IP address
_m_site_publisher_id=PUBLISHER_SUBID - sub-publisher info
E.g. http://catalog.provenpixel.com/pf/PARTNER-NAME/json?q=YOUR_QUERY&n=10&_m_site_publisher_id=PUBLISHER_SUBID
Following is list of all available macros:
Sub-Publisher Info
Macro | Description |
_m_site_publisher_id | sub-publisher info |
Geo Macros
Macro | Description |
_m_device_geo_country | Country |
_m_device_geo_city | City |
_m_device_geo_zip | Postal Code |
_m_device_geo_ext_dma_code | DMA area code |
_m_device_geo_lon | Longitude |
_m_device_geo_lat | Latitude |
_m_device_geo_ext_lon | Longitude ( non-precise version ) |
_m_device_geo_ext_lat | Latitude ( non-precise version ) |
Device Macros
Macro | Description |
_m_device_ua | User agent |
_m_ device_ip | IP address |
_m_device_make | Device Make ( e.g. Samsung ) |
_m_device_os | Operating System |
_m_device_osv | Operating System Version |
_m_device_dpidmd5 | MD5 hashed platform-specific ID (e.g., Android ID or UDID for iOS) |
_m_device.dpidsha1 | SHA1 hashed platform-specific ID (e.g., Android ID or UDID for iOS) |
_m_device_model | Device Model ( e.g. iPhone ) |
_m_device_carrier | Network Carrier ( e.g. ATT, Bell ) |
_m_device_connectiontype | An integer describing how the device is connected ( e.g. wifi, mobile data.. etc) |
Site Macros
Macro | Description |
_m_site_page | Page URL |
_m_site_name | Site Name |
_m_site_id | Site ID |
_m_site_ref | Referral URL |
_m_site_domain | Domain Name |
Misc. Macros
_m_timestamp | A UNIX timestamp |
_m_random | A random string ( a.k.a cache-buster) |
_m_user_id | The detected user ID. It can the 3rd party user ID |
Example of JSON Output
Below is a sample of the JSON format. It contains two top level elements, the query string used to generate the results, and a product list.
http://catalog.provenpixel.com/pf/<partner-name>/json?q=%2Bblue+%2Bshirt
{
"query": "+blue +shirt",
"products": [
{
"title": "Blue Island Women's Swimsuit Coverups RUN - White & Gold Branch Shirt Cover-Up",
"description": "White & Gold Branch Shirt Cover-Up - Women. Making a statement is a cinch in this sun-ready dress boasting trend-right details and a soft feel. ",
"link": "https://catalog.provenpixel.com/fc2/ck.php? zoneid=2678&oadest=https%3A%2F%2Fwww.merchant.com",
"price": 46,
"salePrice": 16.99,
"imageLink": "https://htdata.provenpixel.com/img/merchant/1/276735/1519325349.jpg",
"availability": "in stock",
"condition": "new",
"mpn": "3669-248_WHITEGOLD_S",
"brand": "Blue Island",
"category": "Apparel & Accessories > Clothing > Swimwear",
"merchant": "Merchant Name",
"discount": true,
"discountValue": 29.01,
"discountRate": 63,
"id": "merchant-55079121",
"logo": "https://pf.provenpixel.com/assets/images/logos/merchant.png"
},