The Catalog API gives you all the tools you need to build a rich shopping experience. Return results in XML, JSON, or JSONP. To track your traffic efficiently, please see our redirect tracking parameters documentation here.
The Product Service allows your application to leverage our deep catalog of products and offers. It returns two major types of data elements: Product and Offer. A Product is an idealized, canonical representation of a real-world product. The Product exists independent of the merchants who may sell it. An Offer represents an actual item for sale by a merchant, which may or may not be aligned to a specific Product in our catalog. An Offer element that does not have a productId attribute is a stand-alone Offer with no relationship to any specific Product.
Correspondingly, this service can be used for three major types of queries:
Within the price element of an offer response, this service will allow display of an offer's current price, original price, and percentage the current price has been marked down from the original price.
In addition to the product and offer data, this service also returns some additional meta data in the form of a Classification element which contains some information about the search quality of the keyword, and an optional list of related Attributes which can be used to build an attribute filter (attFilter) parameter for subsequent requests. For more comprehensive attribution data to allow you to limit your queries by attribute, explore our Attribute Service.
Data Refresh: Product Service content should be cached for no more than six (6) hours.
Note that though all three of the categoryId, keyword and productId parameters are listed as optional, at least one of them must be specified.
parameter | value | description |
---|---|---|
apiKey |
string (required) |
Key used to authenticate the publisher request. |
publisherId |
unsignedint (required) |
Publisher id used to track which publisher is requesting content. |
placementId |
Default: 1 |
Placement IDs can be used to track the effectiveness of your chosen assets or their placement on your website. You can view your traffic by Placement ID under View Reports.This parameter is restricted to 50 alphanumeric (letters and numbers [a-zA-Z] and [0-9] and special characters - . _ ) characters. Will not work with special characters such as & / + " Placement IDs will be reported under the default value of 1 if no value is provided. |
categoryId |
Integer value which uniquely identifies a category. Values can be discovered through the Taxonomy Service. |
|
keyword |
A keyword to use in searching for products. |
|
productId |
Unique identifier for a product. For multiple results, use a semicolon-separated list (up to 20 items). When using this parameter, the categoryId, keyword and various results-filtering parameters (minPrice, maxPrice, attFilter, etc) will be ignored. Also note that the only way to get the "longDescription" element populated in a Product element is to look up the product using a Connexity Product Id. |
|
productIdType |
One of:
|
This parameter controls how the productId parameter is interpreted.
|
offersOnly |
Default: false |
Query only for offers, and omit product data. |
merchantId |
Filter results using the unique integer identifier that Connexity assigns to a particular merchant. Values for this parameter can be discovered through the RelatedAttributes element returned when the showAttributes parameter has the value "true". |
|
brandId |
Filter results based on brand. The value of this parameter must be a valid brand id as defined in our system. Values for this parameter can be discovered either through the RelatedAttributes element returned when the showAttributes parameter has the value "true", or in more depth through the Brand Service. |
|
biddedOnly |
Default: true |
Query only for bidded CPC offers and products which have bidded CPC offers. Note, this filter does not apply to search queries by Connexity Offer Id ("SZOID"). biddedOnly=false will include offers that do not monetize. |
minPrice |
The minimum boundary (inclusive) of a price range to limit the results by. Price is the current price. Must be used in tandem with maxPrice. The value should be in the smallest integral unit of currency (e.g. cents in US dollars); $19.99 would be entered as "1999". |
|
maxPrice |
|
|
minMarkdown |
|
|
zipCode |
U.S. 5-digit zip code; required to see shipping costs. |
|
freeShipping |
Default: false |
Filter results based on availability of free shipping. When returning a product and its aligned offers, products which contain at least one free shipping offer will be returned. |
start |
Default: 0 |
Paging start parameter for Products (or Offers if the offersOnly parameter is "true") |
results |
Default: 10 |
Determines page size, or the number of products (or Offers if the offersOnly parameter is "true") to display in results. Maximum is 250. |
startOffers |
Default: 0 |
Paging start parameter for Offers aligned under a Product. |
resultsOffers |
Default: 0 |
Determines page size for Offers aligned under a Product. Maximum is 250, but in practice, the average number of offers per Product is much lower than that. |
sort |
One of:
|
Controls the sort order of the results. Note that aside from the default sort order ("relevancy_desc"), the sort orders are applied only to the current page of results.
|
attFilter |
Filter results based on attributes. This parameter takes a specially formatted value, the format of which is: attrId + ':' + attrValue (+ ';' + attrId + ':' + attrValue)*. An example would be: attFilter=259:12345;402:19874. Values for this parameter can be discovered through the RelatedAttributes element returned when the showAttributes parameter has the value "true". Maximum is 20. |
|
attWeights |
Apply weights to the attributes. This parameter takes a specially formatted value, the format of which is: attrId + ':' + attrValue + ':' attrWeight (+ ';' + attrId + ':' + attrValue + ':' attrWeight)*. An example would be: attrWeight=259:12345:100;402:19874:200. Values for this parameter can be discovered through the RelatedAttributes element returned when the showAttributes parameter has the value "true". Weight must be a number between 0 and 100000. A weight of 0 will effectively exclude products/offers that match the specified attribute value, eg. 259:12345:0 translates to exclude products/offers having brand id 12345. Maximum is 20. |
|
attributeId |
The attributeId parameter is used to exercise precise control over which attributes are queried in a few different scenarios:
The attributeId parameter can play both of those roles simultaneously in a single request. The parameter accepts a semicolon-separated(;) list of multiple ids. eg: 259;296935 i.e. 259 = brand and 296935 = store(merchant). |
|
resultsAttribute |
Default: 10 |
Maximum number of attributes to return in response when the showAttributes parameter has the value "true". Maximum is 50. |
resultsAttributeValues |
Default: 10 |
Maximum number of attribute values to return for all attributes in response when the showAttributes parameter has the value "true". The maximum number of attribute values that can be returned in a single attribute is 512. |
showAttributes |
Default: false |
Show a list of product attributes related to your query which you could use to further refine your request. This parameter can be used in conjunction with the attributeId or resultsAttribute parameters to control which or how many attributes are queried, respectively. It can also be used in conjunction with resultsAttributeValues to control how many attribute values are returned per attribute. This parameter is ignored for queries that have a productId parameter. |
showProductAttributes |
Default: false |
Will display additional detailed attributes for a specific product or offer. Used either in conjunction with the productId parameter and a productIdType of "SZPID" or in conjunction with offersOnly=true and the attributeId parameter. Note that not all products or offers have detailed attribute data. |
minRelevancyScore |
Default: 100 |
@Deprecated. The minimum relevancyScore value for which you want to return results. Should be a value from 1 to 1000. The relevancyScore is a measure of how relevant a keyword is to shopping. Therefore, this parameter only applies to requests that include a keyword. It applies to the request as a whole, not individual results. |
maxAge |
One of:
|
Filter results based on offer age. Age is determined by an offer's introduction to the Connexity, Inc. universe. Whole values must be 1, 2, 3, 7, or 30.
|
showRawUrl |
Default: false |
Show raw merchant offer URL. Note that this URL should not be used in your production integration as it does not include necessary tracking parameters. You will not generate revenue from traffic driven through this URL. |
showUnitPricing |
Default: false |
Show unit pricing data if available. |
useSecureImageDomain |
Default: false |
Will generate all URLs to images using the secure HTTPS protocol. |
useSecureLinkDomain |
Default: false |
Will generate redirect links to merchant offers using the secure HTTPS protocol. |
reviews |
One of:
|
Controls whether the results include the count of product reviews available for the products in the results. Note that not all products will have reviews available, and that reviews are at the level of products not offers.
|
format |
One of:
|
Select the format for the response, xml is the default
|
callback |
Default: callback |
Used as a function name to wrap JSONP. Note, this parameter only applies to responses in JSONP format. |
available response representations:
potential faults:
The Brand Service allows your application to search and explore our available brands.
It can be used for three major types of queries:
Data Refresh: Brand Service content should be cached for no more than one (1) day.
We recommend you use one of the parameters categoryId, keyword, or brandName.
parameter | value | description |
---|---|---|
apiKey |
string (required) |
Key used to authenticate the publisher request. |
publisherId |
unsignedint (required) |
Publisher id used to track which publisher is requesting content. |
placementId |
Default: 1 |
Placement IDs can be used to track the effectiveness of your chosen assets or their placement on your website. You can view your traffic by Placement ID under View Reports.This parameter is restricted to 50 alphanumeric (letters and numbers [a-zA-Z] and [0-9] and special characters - . _ ) characters. Will not work with special characters such as & / + " Placement IDs will be reported under the default value of 1 if no value is provided. |
categoryId |
Integer value which uniquely identifies a category. |
|
keyword |
A product keyword to use in searching for brands associated with that product keyword. |
|
brandName |
Query for brands by brand name, in full or part. To return an alphabetical directory of all brands for a given letter, enter only that letter. |
|
start |
Default: 0 |
Paging start parameter for brand results. |
results |
Default: 10 |
Determines page size for brands element. The maximum number of brands that can be returned in a single call is 512. |
attFilter |
Filter results based on attributes. This parameter takes a specially formatted value, the format of which is: attrId + ':' + attrValue (+ ';' + attrId + ':' + attrValue)*. An example would be: attFilter=259:12345;402:19874. Values for this parameter can be discovered through Attribute Service. Maximum is 50. |
|
format |
One of:
|
Select the format for the response, xml is the default
|
callback |
Default: callback |
Used as a function name to wrap JSONP. Note, this parameter only applies to responses in JSONP format. |
available response representations:
potential faults:
The Attribute Service allows your application to search and explore our available attributes.
It can be used for three major types of queries:
Data Refresh: Attribute Service content should be cached for no more than one (1) day.
We recommend you use categoryId for search.
parameter | value | description |
---|---|---|
apiKey |
string (required) |
Key used to authenticate the publisher request. |
publisherId |
unsignedint (required) |
Publisher id used to track which publisher is requesting content. |
placementId |
Default: 1 |
Placement IDs can be used to track the effectiveness of your chosen assets or their placement on your website. You can view your traffic by Placement ID under View Reports.This parameter is restricted to 50 alphanumeric (letters and numbers [a-zA-Z] and [0-9] and special characters - . _ ) characters. Will not work with special characters such as & / + " Placement IDs will be reported under the default value of 1 if no value is provided. |
categoryId |
Integer value which uniquely identifies a category. |
|
keyword |
A product keyword to use in searching for attributes associated with that product keyword. |
|
attributeId |
Query for attributes by attributeId and can optionally be a semicolon-separated(;) list of multiple ids. eg: 259;296935 i.e. 259 = brand and 296935 = store(merchant). If not specified, up to 10 will be returned. |
|
attFilter |
Filter results based on attributes. This parameter takes a specially formatted value, the format of which is: attrId + ':' + attrValue (+ ';' + attrId + ':' + attrValue)*. An example would be: attFilter=259:12345;402:19874. Maximum is 50. |
|
minPrice |
The minimum boundary (inclusive) of a price range to limit the results by. Price is the current price. Must be used in tandem with maxPrice. The value should be in the smallest integral unit of currency (e.g. cents in US dollars); $19.99 would be entered as "1999". |
|
maxPrice |
|
|
results |
Default: 10 |
Maximum number of attributes to return in response. Maximum is 50. |
resultsAttributeValues |
Default: 10 |
Maximum number of attribute values to return for all attributes in response. The maximum number of attribute values that can be returned in a single attribute is 512. |
minMarkdown |
|
|
maxAge |
One of:
|
Filter results based on offer age. Age is determined by an offer's introduction to the Connexity, Inc. universe. Whole values must be 1, 2, 3, 7, or 30.
|
format |
One of:
|
Return your query response in XML, JSON, or JSONP.
|
callback |
Default: callback |
Used as a function name to wrap JSONP. Note, this parameter only applies to responses in JSONP format. |
available response representations:
potential faults:
The Taxonomy Service allows your application to search and explore our hierarchy of categories.
It can be used for four major types of queries:
Data Refresh: Taxonomy Service content should be cached for no more than one (1) day.
parameter | value | description |
---|---|---|
apiKey |
string (required) |
Key used to authenticate the publisher request. |
publisherId |
unsignedint (required) |
Publisher id used to track which publisher is requesting content. |
placementId |
Default: 1 |
Placement IDs can be used to track the effectiveness of your chosen assets or their placement on your website. You can view your traffic by Placement ID under View Reports.This parameter is restricted to 50 alphanumeric (letters and numbers [a-zA-Z] and [0-9] and special characters - . _ ) characters. Will not work with special characters such as & / + " Placement IDs will be reported under the default value of 1 if no value is provided. |
categoryId |
Integer value which uniquely identifies a category. |
|
keyword |
A product keyword to use in searching for categories associated with that product keyword. |
|
ancestors |
Used only in conjunction with the categoryId parameter. A "true" value will instruct the service to append the path from the root category to the target category. |
|
results |
Default: 10 |
Determines page size, or the number of categories to display in results. Maximum is 20. |
sort |
One of:
|
Controls the sort order of the results. Used only in conjunction with keyword searches.
|
attFilter |
Filter results based on attributes. This parameter takes a specially formatted value, the format of which is: attrId + ':' + attrValue (+ ';' + attrId + ':' + attrValue)*. An example would be: attFilter=259:12345;402:19874. Values for this parameter can be discovered through Attribute Service. Maximum is 50. |
|
format |
One of:
|
Select the format for the response, xml is the default
|
callback |
Default: callback |
Used as a function name to wrap JSONP. Note, this parameter only applies to responses in JSONP format. |
showAtoms |
Default: false |
Include atoms in the category tree (when ancestors=false and keyword=null). |
available response representations:
potential faults:
The Merchant Service allows your application to access data about our merchants. Within the Merchant Info element, this service returns basic merchant data, a logo URL, as well as detailed meta data. The activeOnly parameter can also be used to lookup all active merchants for your specific account.
Correspondingly, this service can be used to query for:
Data Refresh: Merchant Service content should be cached for no more than two (2) hours.
*Note: The merchant ratings and reviews data have been deprecated as of April 1st, 2021. If this presents any concern for you, please contact us.
parameter | value | description |
---|---|---|
apiKey |
string (required) |
Key used to authenticate the publisher request. |
publisherId |
unsignedint (required) |
Publisher id used to track which publisher is requesting content. |
placementId |
Default: 1 |
Placement IDs can be used to track the effectiveness of your chosen assets or their placement on your website. You can view your traffic by Placement ID under View Reports.This parameter is restricted to 50 alphanumeric (letters and numbers [a-zA-Z] and [0-9] and special characters - . _ ) characters. Will not work with special characters such as & / + " Placement IDs will be reported under the default value of 1 if no value is provided. |
merchantId |
Filter results using the unique integer identifier that Connexity assigns to a particular merchant, or a merchant text name. If using merchantID, can optionally be a comma-separated(,) list of multiple ids; maximum is 10. If using merchant text name, maximum is 1. If merchant text name is numeric, merchant name should be entered in double quotes("). This field is required unless activeOnly is set to true. |
|
showMerchantDetails |
Default: false |
Show merchant meta data including merchant description, physical address, and shipping options. |
activeOnly |
Default: false |
Filter results by merchants who are currently active in the Connexity system. This parameter will override other query parameters to only return basic merchant data about all active merchants. There are small windows of time when a merchant may become active in our system but their offers are not yet available. If you see a merchant as active but no offers appearing, please check back later in the day for live offers. |
useSecureImageDomain |
Default: false |
Will generate all URLs to images using the secure HTTPS protocol. |
useSecureLinkDomain |
Default: false |
Will generate redirect links to merchant offers using the secure HTTPS protocol. |
format |
One of:
|
Select the format for the response, xml is the default
|
callback |
Default: callback |
Used as a function name to wrap JSONP. Note, this parameter only applies to responses in JSONP format. |
available response representations:
potential faults:
The Product Review Service allows your application to search and explore our available product reviews.
*Note: The product review service has been deprecated as of May 1st, 2021. If this presents any concern for you, please contact us.
It can be used for two major types of queries:
Product Review ratings are on a scale of 0 to 5.
Data Refresh: Product Review Service content should be cached for no more than one (1) day.
parameter | value | description |
---|---|---|
apiKey |
string (required) |
Key used to authenticate the publisher request. |
publisherId |
unsignedint (required) |
Publisher id used to track which publisher is requesting content. |
placementId |
Default: 1 |
Placement IDs can be used to track the effectiveness of your chosen assets or their placement on your website. You can view your traffic by Placement ID under View Reports.This parameter is restricted to 50 alphanumeric (letters and numbers [a-zA-Z] and [0-9] and special characters - . _ ) characters. Will not work with special characters such as & / + " Placement IDs will be reported under the default value of 1 if no value is provided. |
productId |
string (required) |
Unique identifier for a product. Only one value at a time will be accepted initially; support for a semicolon-separated list is a planned future expansion. |
reviews |
One of:
|
Selects the format for the response, detailed is the default
|
start |
Default: 0 |
Paging start parameter for product review results. |
results |
Default: 3 |
Determines page size for product review results. The maximum number of reviews that can be returned in a single call is 250. |
sort |
One of:
|
Controls how the reviews are sorted.
|
useSecureLinkDomain |
Default: false |
Will generate redirect links to merchant offers using the secure HTTPS protocol. |
format |
One of:
|
Selects the format for the response; xml is the default.
|
callback |
Default: callback |
Used as a function name to wrap JSONP. Note, this parameter only applies to responses in JSONP format. |
available response representations:
potential faults:
Source: service.xsd
<xs:element name="ProductResponse"> <xs:annotation> <xs:documentation>Top-level container element for responses from the Product Service</xs:documentation> </xs:annotation> <xs:complexType> <xs:sequence> <xs:element name="Classification" minOccurs="0"> <xs:annotation> <xs:documentation> The Classification element is a container for analysis about the request. </xs:documentation> </xs:annotation> <xs:complexType> <xs:sequence> <xs:element name="relevancyScore" minOccurs="0" type="xs:unsignedInt"> <xs:annotation> <xs:documentation>Ranges from 1 to 1000, with 1000 being the "most relevant". </xs:documentation> </xs:annotation> </xs:element> <xs:element name="searchUrl" minOccurs="0" type="xs:anyURI"> <xs:annotation> <xs:documentation>Direct Site URL with publisher params. </xs:documentation> </xs:annotation> </xs:element> </xs:sequence> </xs:complexType> </xs:element> <xs:element name="RelatedAttributes" minOccurs="0"> <xs:annotation> <xs:documentation> RelatedAttributes contains a set of product Attributes that are related to the request, and may be used to further filter subsequent requests. </xs:documentation> </xs:annotation> <xs:complexType> <xs:sequence> <xs:element name="Attribute" minOccurs="0" maxOccurs="unbounded" type="AttributeType"/> </xs:sequence> </xs:complexType> </xs:element> <xs:element name="Products" minOccurs="0"> <xs:annotation> <xs:documentation> Products contains Products or Offers that matched the specified criteria. It is omitted if the request specifies that only offers should be returned. </xs:documentation> </xs:annotation> <xs:complexType> <xs:sequence> <xs:element name="PriceSet" minOccurs="0" maxOccurs="1" type="PriceSetType"> <xs:annotation> <xs:documentation> Gives the min and max price boundaries for the result set. Not included if there are no results. </xs:documentation> </xs:annotation> </xs:element> <xs:choice minOccurs="0" maxOccurs="unbounded"> <xs:annotation> <xs:documentation> The search results will be a mix of Products and Offers which are not aligned to any Product. </xs:documentation> </xs:annotation> <xs:element name="Product" type="ProductType"/> <xs:element name="Offer" type="OfferType"/> </xs:choice> </xs:sequence> <xs:attributeGroup ref="ResultsGroup"/> <xs:attribute name="backfillResults" type="xs:long"/> </xs:complexType> </xs:element> <xs:element name="Offers" minOccurs="0"> <xs:annotation> <xs:documentation> Offers contains data for offers that matched the specified criteria. It is omitted unless the request specifies that only offers should be returned. </xs:documentation> </xs:annotation> <xs:complexType> <xs:sequence> <xs:element name="PriceSet" minOccurs="0" maxOccurs="1" type="PriceSetType"> <xs:annotation> <xs:documentation> Gives the min and max price boundaries for the result set. Not included if there are no results. </xs:documentation> </xs:annotation> </xs:element> <xs:element name="Offer" type="OfferType" minOccurs="0" maxOccurs="unbounded"/> </xs:sequence> <xs:attributeGroup ref="ResultsGroup"/> <xs:attribute name="backfillResults" type="xs:long"/> </xs:complexType> </xs:element> </xs:sequence> </xs:complexType> </xs:element>
Source: service.xsd
<xs:element name="BrandsResponse"> <xs:annotation> <xs:documentation> Top-level container element for responses from the Brand Service. </xs:documentation> </xs:annotation> <xs:complexType> <xs:sequence> <xs:element name="Brands" type="BrandsType" minOccurs="0" maxOccurs="1"> </xs:element> </xs:sequence> </xs:complexType> </xs:element>
Source: service.xsd
<xs:element name="AttributeResponse"> <xs:annotation> <xs:documentation>Top-level container element for responses from the Attribute Service</xs:documentation> </xs:annotation> <xs:complexType> <xs:sequence> <xs:element name="Attributes" minOccurs="0"> <xs:annotation> <xs:documentation> Attributes contains a set of product Attributes that match the query </xs:documentation> </xs:annotation> <xs:complexType> <xs:sequence> <xs:element name="Attribute" minOccurs="0" maxOccurs="unbounded" type="AttributeType"/> </xs:sequence> </xs:complexType> </xs:element> </xs:sequence> <xs:attribute name="includedResults" type="xs:long"/> </xs:complexType> </xs:element>
Source: service.xsd
<xs:element name="TaxonomyResponse"> <xs:annotation> <xs:documentation> Top-level container element for responses from the Taxonomy Service. </xs:documentation> </xs:annotation> <xs:complexType> <xs:sequence> <xs:element name="Taxonomy" minOccurs="0" maxOccurs="1"> <xs:annotation> <xs:documentation>Taxonomy contains a list of Category elements, which can constitute a tree, a forest or simply a flat list. Most commonly, it is a list (in the case of search results) or a tree (in the case of lookups on categoryIds). </xs:documentation> </xs:annotation> <xs:complexType> <xs:sequence> <xs:element name="Categories" type="CategoriesType"/> </xs:sequence> </xs:complexType> </xs:element> </xs:sequence> </xs:complexType> </xs:element>
Source: service.xsd
<xs:element name="MerchantsResponse"> <xs:complexType> <xs:sequence> <xs:element name="Merchant" minOccurs="0" maxOccurs="unbounded"> <xs:complexType> <xs:sequence> <xs:element name="MerchantInfo" type="MerchInfoType" minOccurs="0" maxOccurs="1"> </xs:element> </xs:sequence> <xs:attribute name="mid" type="xs:long" use="required"/> </xs:complexType> </xs:element> </xs:sequence> <xs:attribute name="totalMerchants" type="xs:long" use="optional"/> </xs:complexType> </xs:element>
Source: service.xsd
<xs:element name="ProductReviewsResponse"> <xs:annotation> <xs:documentation>Top-level container element for responses from the Product Reviews Service</xs:documentation> </xs:annotation> <xs:complexType> <xs:sequence> <xs:element name="productId" type="uid"> <xs:annotation> <xs:documentation>Identifies the product for which these reviews apply.</xs:documentation> </xs:annotation> </xs:element> <xs:element name="reviewRatingAvg" type="xs:float"> <xs:annotation> <xs:documentation>Average 5-star rating from all reviews (value between 0 and 5).</xs:documentation> </xs:annotation> </xs:element> <xs:element name="reviewCount" type="xs:long"> <xs:annotation> <xs:documentation>Total number of reviews available (may be larger than the number actually returned). </xs:documentation> </xs:annotation> </xs:element> <xs:element name="ProductReview" type="ProductReviewType" minOccurs="0" maxOccurs="unbounded"> <xs:annotation> <xs:documentation>The detailed information for an individual product review.</xs:documentation> </xs:annotation> </xs:element> </xs:sequence> </xs:complexType> </xs:element>
Message explaining the reason for the fault -- typically invalid input.
Message explaining the reason for the fault -- too many requests per second.
Message explaining the reason for the fault -- typically invalid input.
Message explaining the reason for the fault -- too many requests per second.
Message explaining the reason for the fault -- typically invalid input.
Message explaining the reason for the fault -- too many requests per second.
Message explaining the reason for the fault -- typically invalid input.
Message explaining the reason for the fault -- too many requests per second.
Message explaining the reason for the fault -- typically invalid input.
Message explaining the reason for the fault -- too many requests per second.
Message explaining the reason for the fault -- typically invalid input.
Message explaining the reason for the fault -- too many requests per second.