Product Catalog Search Service v.2

The Product Catalog Search Service is a SOAP-based (Simple Object Access Protocol) 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. Refer to the following sections of this topic for more specific information.

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.

Note: Refer to https://product.api.cj.com for the most recent version of the Product Catalog Search Service WSDL. The WSDL provides all the programmatic information you need to use this API. The hand-edited version provides the information in a readable format; however, to ensure maximum compatibility with the system, use the AXIS version when developing your application.

Request Parameters

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

Important: You must provide all required parameters and 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

Value

Req?

Description

developerKey

String

Required

Your developer key obtained from the Web Services Developer Site.

websiteId

String

Required

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 (passed in the developerKey parameter).

advertiserIds

String

Optional

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 (notjoined) restricts the search to advertisers with which you do not have a relationship.

keywords

String

Optional

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.

 

serviceableArea

String

Optional

Limits the results to a specific set of advertisers’ targeted areas.

isbn

String

Optional

Limits the results to a specific product from multiple merchants identified by the appropriate unique identifier; ISBN.

upc

String

Optional

Limits the results to a specific product from multiple merchants identified by the appropriate unique identifier; UPC.

manufacturerName

String

Optional

Limits the results to a particular manufacturer's name.

manufacturerSku

Long

Optional

Limits the results to a particular manufacturer's SKU number.

advertiserSku

String

Optional

Limits the results to a particular advertiser SKU.

lowPrice

Double

Optional

Limits the results to products with a price greater than or equal to the lowPrice.

Tip: Use in conjunction with the highPrice to specify a specific range of prices.

highPrice

Double

Optional

Limits the results to products with a price less than or equal to the highPrice.

Tip: Use in conjunction with the lowPrice to specify a specific range of prices.

lowSalePrice

Double

Optional

Limits the results to products with a price greater than or equal to the Advertiser offered lowSalePrice.

highSalePrice

Double

Optional

Limits the results to products with a price less than or equal to the Advertiser offered highSalePrice.

currency

String

Optional

Limits the results to one of the following currencies.

  • USD

  • EUR

  • GBP

sortBy

String

Optional

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

startAt = 0

maxResults = 500

sortBy = 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 sortBy value (Price). Thus, the response includes the 500 most relevant matches, sorted by price.

sortOrder

String

Optional

Specifies the order in which the results are sorted; the following case-sensitive values are acceptable.

  • asc: ascending (default value)

  • dec: descending

startAt

String

Optional

Specifies the first record to return in the request. The first record is 0. Leaving this parameter blank assigns a default value of 0.

maxResults

String

Optional

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.

The following table provides an example of how to use startAt and maxResults values to obtain a total of 1000 results, with 250 results at a time.

Request number

startAt value

maxResults value

Request 1

0

250

Request 2

250

250

Request 3

500

250

Request 4

750

250

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

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 sensitive.

General

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

Field Name

Value

Description

count

Integer

The number of results included in the response.  This value is always less than or equal to the maxResults value.

Note: The count value may be smaller than maxResults depending on the startAt value. For example, if a particular search has 115 possible matches, and you specified a startAt value of 0 and a maxResults value of 200, the service would only return (and the count value would be equal to) the 115 possible results.

offset

Integer

This is the page number; it is equal to the startAt value you provide.

products

Array

An array of product records. Refer to the Per Record (Product) table below for the fields returned for each product record in the response.

totalResults

Integer

The total number of matching products in the index, regardless of the number of results in the actual response (the value of the maxResults 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

Value

Description

adId

String

The associated ad identification number.

advertiserId

Integer

The advertiser’s CID.

advertiserName

String

The advertiser’s name.

buyUrl

String

The URL on the advertiser's Web site where you may purchase the product.

catalogId

String

The identification number for the associated Commission Junction product catalog.

currency

String

The 3-letter currency code associated with the product.

description

String

A description of the product.

imageUrl

String

A direct link to an image of the product.

inStock

String

Displays whether the product is currently in stock.

isbn

String

Unique identifier (ISBN) for a product or products that would identify the same product from multiple merchants.

manufacturerName

String

The name of the manufacturer of the associated product.

manufacturerSku

String

The manufacturer sku number for the associated product.

name

String

The name of the product.

price

Double

The actual price of the associated product.

retailPrice

Double

The suggested retail price of the product.

salePrice

Double

The advertiser offered sale price of the product.

sku

String

The associated product’s SKU number.

upc

String

Unique identifier (UPC) for a product or products that identifies the same product from multiple merchants.

Errors

Error

Description

Not Authenticated

The system could not authenticate your developer key.