Product Catalog Search Service (REST)

The Product Catalog Search Service is a REST API that enables developers to query and retrieve specific product information from an advertiser’s product catalogs. Developers may search by any number of criteria including price, currency, country, serviceable area and UPC.

Note: Product catalogs with ads designated as private (within the CJ Account Manager) are not available through the Product Catalog Search API. In the future, Commission Junction plans to support this functionality, in which only the advertiser-designated publishers will have access to these private product catalogs.

Commission Junction's REST Web Services use the standard HTTP Authorization header to pass authentication information.  You must provide your developer key to pass authentication. The request URI for the Publisher Lookup Service API must be properly encoded based on HTML 4 specification form content encoding rules. Please refer to http://www.w3.org/TR/REC-html40/interact/forms.html#h-17.13.4 for the standard specification.  

Note: Some languages may have built-in utility methods for encoding URIs based on RFC 1738. Unfortunately, these utility methods may not properly encode white space character and "+" character. Specifically, white space character should be encoded to "+" character, and "+" character should be encoded to "%2B".

Click the following links to display more specific information.

• Request Parameters

  Request Parameters

  Header	Description
  authorization	Your developer key obtained from the Web Services Developer Site.

  Refer to the following table for a list of the request parameters. All parameter names and values are case insensitive.

  Important: You must provide at least one of the optional parameters. Submitting an empty request does not return all possible results; an empty request returns zero results.

  Parameter Name	Description
  website-id	This value is your Web site ID (PID), which enables the system to generate the appropriate link code in the response. The PID must match the Web site PID which you used to register for the developer key.
  advertiser-ids	Limits the results to a set of particular advertisers (CIDs) using one of the following four values. CIDs: You may provide list of one or more advertiser CIDs, separated by commas, to limit the results to a specific sub-set of merchants. Empty String: You may provide an empty string to remove any advertiser-specific restrictions on the search. joined: This special value (joined) restricts the search to advertisers with which you have a relationship. notjoined: This special value (not-joined) restricts the search to advertisers with which you do not have a relationship.
  keywords	This value restricts the search results based on keywords found in the advertiser’s name, the product name or the product description. This parameter may be left blank if other parameters (such as upc, isbn) are provided. You may use simple Boolean logic operators (’r;+’, ’r;-’r;) to obtain more relevant search results. By default, the system assumes basic OR logic. The examples below illustrate how these operators affect search results. Query Results "kitchen sink" Any product with the word "kitchen" or "sink" "+kitchen +sink" Any product with the words "kitchen" and "sink" "+kitchen -sink" Any product with "kitchen" and without "sink" "kitchen +sink" All the products with the word "sink"; if they also contain "kitchen", it increases the product’s relevancy.
  serviceable-area	Limits the results to a specific set of advertisers’ targeted areas.
  isbn	Limits the results to a specific product from multiple merchants identified by the appropriate unique identifier; ISBN.
  upc	Limits the results to a specific product from multiple merchants identified by the appropriate unique identifier; UPC.
  manufacturer-name	Limits the results to a particular manufacturer's name.
  manufacturer-sku	Limits the results to a particular manufacturer's SKU number.
  advertiser-sku	Limits the results to a particular advertiser SKU.
  low-price	Limits the results to products with a price greater than or equal to the low-price. Tip: Use in conjunction with the high-price to specify a specific range of prices. Note: Only whole numbers are supported for this request parameter. The low-price parameter is inclusive, whereas the high-price parameter is exclusive. For example, using a low price of 10 and a high price of 20 will return everything from 10 to 19.99.
  high-price	Limits the results to products with a price less than or equal to the high-price. Tip: Use in conjunction with the low-price to specify a specific range of prices. Note: Only whole numbers are supported for this request parameter. The low-price parameter is inclusive, whereas the high-price parameter is exclusive. For example, using a low price of 10 and a high price of 20 will return everything from 10 to 19.99.
  low-sale-price	Limits the results to products with a price greater than or equal to the Advertiser offered low-sale-price. Note: Only whole numbers are supported for this request parameter. The low-sale-price parameter is inclusive, whereas the high-sale-price parameter is exclusive. For example, using a low sale price of 10 and a high sale price of 20 will return everything from 10 to 19.99.
  high-sale-price	Limits the results to products with a price less than or equal to the Advertiser offered high-sale-price. Note: Only whole numbers are supported for this request parameter. The low-sale-price parameter is inclusive, whereas the high-sale-price parameter is exclusive. For example, using a low sale price of 10 and a high sale price of 20 will return everything from 10 to 19.99.
  currency	Limits the results to one of the following currencies. USD EUR GBP
  sort-by	Sort the results in the response by one of the following values. Name Advertiser ID Advertiser Name Currency Price salePrice Manufacturer SKU UPC Note: Only the results returned in the particular request are sorted by the value of this parameter. The system automatically sorts all matching results in the index (not just the results in the specific request) by relevance to keyword value sent in the request. Example Sample search parameter values for this example: keywords = shoes start-at = 0 max-results = 500 sort-by = price Suppose the index contains 5,432 possible results. The system automatically sorts those results based on their relevance to the keywords value (shoes). Then, the system pulls the top 500 results and sorts those 500 results based on your sort-by value (price). Thus, the response includes the 500 most relevant matches, sorted by price.
  sort-order	Specifies the order in which the results are sorted; the following case-insensitive values are acceptable. asc: ascending (default value) dec: descending
  page-number	Specifies the first record to return in the request. The first record is 0. Leaving this parameter blank assigns a default value of 0. Please refer to the notes below the table for more information.
  records-per-page	Specifies the number of records to return in the request. Leaving this parameter blank assigns a default value of 50. Note: 1000 results is the system limit for results per request. If you request a value greater than 1000, the system only returns 1000. Please refer to the notes below the table for more information.

  Note: If page-number/records-per-page combination puts the first record requested beyond 10,000, the system will return a response with zero product found. For example, an incoming request with page-number=101 and records-per-page=100 will get a response with zero product found.

  Note: If page-number/records-per-page combination puts the page at the end over the 10,000 hit limit, the system will only return up to the 10,000th hit. For example, if an incoming request specifies page-number=34 and records-per-page=300, then the system will return records for page 34 (counting 300 records per page) but only up to 100 records in the response.

  For more information refer to the forums at the Web Services Developer Site (http://webservices.cj.com).

• Response Fields

  Response Fields

  The response includes information about the general response, as well as specific information for each record in the response. By default, the results are sorted by price, from low to high. All parameter names and values are case insensitive.

  General

  The response includes the following information about the overall set of results in the response.

  Field Name	Description
  count	The number of results included in the response.  This value is always less than or equal to the max-results value. Note: The count value may be smaller than max-results depending on the start-at value. For example, if a particular search has 115 possible matches, and you specified a start-at value of 0 and a max-results value of 200, the service would only return (and the count value would be equal to) the 115 possible results.
  offset	This is the page number; it is equal to the start-at value you provide.
  products	An array of product records. Refer to the Per Record (Product) table below for the fields returned for each product record in the response.
  total-results	The total number of matching products in the index, regardless of the number of results in the actual response (the value of the max-results parameter).

  Per Record (Product)

  The response includes the following fields for each record (i.e., product).

  Note: Product data is based on the information provided by the advertiser. Advertisers may choose to not provide some product data (for example, the upc field), and as a result, this info is also unavailable through the Product Catalog Search service.

  Field Name	Description
  ad-id	The associated ad identification number.
  advertiser-id	The advertiser’s CID.
  advertiser-name	The advertiser’s name.
  buy-url	The URL on the advertiser's Web site where you may purchase the product.
  catalog-id	The identification number for the associated Commission Junction product catalog.
  currency	The 3-letter currency code associated with the product.
  description	A description of the product.
  image-url	A direct link to an image of the product.
  in-stock	Displays whether the product is currently in stock.
  isbn	Unique identifier (ISBN) for a product or products that would identify the same product from multiple merchants.
  manufacturer-name	The name of the manufacturer of the associated product.
  manufacturer-sku	The manufacturer sku number for the associated product.
  name	The name of the product.
  price	The actual price of the associated product.
  retail-price	The suggested retail price of the product.
  sale-price	The advertiser offered sale price of the product.
  sku	The associated product’s SKU number.
  upc	Unique identifier (UPC) for a product or products that identifies the same product from multiple merchants.

• Errors

  Errors

  Error	Description
  Not Authenticated	The system could not authenticate your developer key.