CNET API: Reference Guide

Contents

Audience

This document is intended for developers who want to integrate the CNET API into their websites. It assumes you are familiar with the basic concepts of APIs, XML, HTTP request methods, and the REST style of software architecture. In addition, the document assumes you have familiarized yourself with the concepts discussed in the developer's guide.

For a basic overview of the CNET API, see the quick start guide.

API resources

For an introduction to the currently available CNET API entry points or resources, see the developer's guide. The following tables provide summaries of the resources, including their usage, required and optional parameters, example URLs, and example XML responses.

Note: The top-level response nodes shown are the children of the standard <CNETResponse> root node. For brevity's sake, CDATA tags are not shown in the example responses.

Category

Resource Name /category
Description Returns product category information for a given category ID.
Required Parameters categoryId
Optional Parameters siteId (defaults to 7, see Request Parameters)
Top-Level Response Node <Category>
Example Request URL http://developer.api.cnet.com/rest/v1.0/category?categoryId=6475&siteId=7&partTag=
[yourDeveloperKey]
Example XML Response 
<CNETResponse version="1.0">
   <Category id="6475"
      xlink:href="http://developer.api.cnet.com/rest/v1.0/category?categoryId=6475">
      <Title>TVs</Title>
      <Breadcrumb>Home Entertainment^TVs</Breadcrumb>

      <Node id="6449"
         xlink:href="http://developer.api.cnet.com/rest/v1.0/category?categoryId=6449">
         <Name>Home Entertainment</Name>
      </Node>
      <Node id="6475"
         xlink:href="http://developer.api.cnet.com/rest/v1.0/category?categoryId=6475">
         <Name>TVs</Name>

      </Node>
   </Category>
</CNETResponse>


Commonly used categories

The following table lists commonly used CNET categories and their corresponding IDs.

Category Category ID
Cell Phones 6454
Components 3001
Desktops 3118
Digital Camcorders 6500
Digital Cameras 6501
Laptops 3121
MP3 Players 6490
Printers 3155
TVs 6475


Child categories

Resource Name /childCategories
Description For a given category ID, returns that category's children. If a category ID is not passed, returns the top-level categories for the site.
Required Parameters None
Optional Parameters siteId (defaults to 7) and categoryId.
Top-Level Response Nodes <ChildCategories>
Example Request URL http://developer.api.cnet.com/rest/v1.0/childCategories?siteId=9&partTag=[yourDeveloperKey]
Example XML Response 
<CNETResponse version="1.0">
   <ChildCategories>
      <Category id="6475"
         xlink:href="http://developer.api.cnet.com/rest/v1.0/category?categoryId=6475">
         <Title>TVs</Title>
         <Breadcrumb>Home Entertainment^TVs</Breadcrumb>

      </Category>
      <Category id="6490"
         xlink:href="http://developer.api.cnet.com/rest/v1.0/category?categoryId=6490">
         <Title>MP3 players</Title>
         <Breadcrumb>
            Mobile Connectivity and Entertainment^Portable Audio Devices^
            MP3 players
         </Breadcrumb>

      </Category>
   </ChildCategories>
</CNETResponse>

 

Tech product by ID

Resource Name /techProduct
Description Returns tech products by product ID.
Required Parameters productId or comma-separated productIds
Optional Parameters iod, orderBy, sortDesc and zipCode.

iod=(breadcrumb | goodBad | hlPrice | offers).
iod accepts multiple, comma-separated values.

orderBy=(availability | price | storeName | storeRating
| totalPrice). orderBy accepts one value.

sortDesc=(true | false)
Top-Level Response Nodes <TechProduct> if productId is submitted, or <TechProducts> if productIds is submitted.
Example Request URL http://developer.api.cnet.com/rest/v1.0/techProduct?productId=31303113&iod=hlPrice&
partTag=[yourDeveloperKey]
Example XML Response 
<CNETResponse version="1.0">
   <TechProduct id="31303113"
      xlink:href="http://developer.api.cnet.com/rest/v1.0/techProduct?productId=31303113&
      iod=offers">
      <Name>Canon Digital Rebel XT (body only - silver)</Name>
      <ImageURL width="60">

         http://i.i.com.com/cnwk.1d/sc/31303113-2-60-0.gif
      </ImageURL>
      <ImageURL width="120">
         http://i.i.com.com/cnwk.1d/sc/31303113-2-120-0.gif
      </ImageURL>
      <PriceURL>
         http://shopper.cnet.com/4014-6501_9-31303113.html?ttag=api
      </PriceURL>

      <ReviewURL>
         http://reviews.cnet.com/4505-6501_7-31303113.html
      </ReviewURL>
      <Manufacturer id="275062">
         <Name>Canon USA, Inc.</Name>
      </Manufacturer>

      <SKU>0206B001</SKU>
      <EditorsChoice>false</EditorsChoice>
      <EditorsRating outOf="10">8.0</EditorsRating>
      <LowPrice>$428.95</LowPrice>

      <HighPrice>$839.99</HighPrice>
      <PreferredNode id="6501"/>
      <Category id="6501"
         xlink:href="http://developer.api.cnet.com/rest/v1.0/category?categoryId=6501"/>
      <Offers start="0" numReturned="0" numFound="10"/>
   </TechProduct>
</CNETResponse>

 

Tech product search

Resource Name /techProductSearch
Description Returns related categories and tech products for a given combination of category and keywords.
Required Parameters Either categoryId or query.
Optional Parameters categoryId, query, iod, criteria, orderBy, sortDesc, start and results.

iod=(breadcrumb | relatedCats | hlPrice | offers | goodBad).
iod accepts multiple, comma-separated values.

orderBy=(popularity | editorsRating | price | manufacturerName | productName). orderBy accepts one value.

sortDesc=(true | false)

Multiple pipe-delimited values may be passed for criteria: minOffers=[N], minOffers=[N] and/or hasGoodBad=true.
Top-Level Response Nodes <TechProducts>, as well as <RelatedCategories> if iod=relatedCats is submitted, and <CategoryInfo> if categoryId and iod=breadcrumb are submitted.
Example Request URL http://developer.api.cnet.com/rest/v1.0/techProductSearch?categoryId=6490&
query=ipod&iod=hlPrice&start=0&results=1&partTag=[yourDeveloperKey]
Example XML Response 
<CNETResponse version="1.0">
   <TechProducts start="0" numReturned="1" numFound="145">
      <TechProduct id="32069546"
         xlink:href="http://developer.api.cnet.com/rest/v1.0/techProduct?
         productId=32069546&iod=hlPrice">

         <Name>Apple iPod (fifth-generation update, 80GB, black)</Name>
         <ImageURL width="60">
            http://i.i.com.com/cnwk.1d/sc/32069546-2-60-0.gif
         </ImageURL>
         <ImageURL width="120">
            http://i.i.com.com/cnwk.1d/sc/32069546-2-120-0.gif
         </ImageURL>

         <PriceURL>
            http://shopper.cnet.com/4014-6490_9-32069546.html?ttag=api
         </PriceURL>
         <ReviewURL>
            http://reviews.cnet.com/4505-6490_7-32069546.html
         </ReviewURL>
         <Manufacturer id="272829">

            <Name>Apple Computer, Inc.</Name>
         </Manufacturer>
         <SKU>MA450LL/A</SKU>
         <Specs>
            Digital player, WAV, MP3, AIFF, Apple Lossless,AAC, Audible,
            80 GB, Lithium ion Rechargeable Player batteryIntegrated
         </Specs>

         <EditorsChoice>true</EditorsChoice>
         <EditorsRating outOf="10">8.3</EditorsRating>
         <LowPrice>$299.00</LowPrice>
         <HighPrice>$352.00</HighPrice>

         <PreferredNode id="6490"/>
         <Category id="6490"
            xlink:href="http://developer.api.cnet.com/rest/v1.0/category?
            categoryId=6490"/>
         <Offers start="0" numReturned="0" numFound="12"/>
      </TechProduct>
   </TechProducts>
</CNETResponse>

 

Software product by ID

Resource Name /softwareProduct
Description Returns software products by product ID or product set ID.
Required Parameters productId | productSetId or productIds | productSetIds (comma-separated)
Optional Parameters iod=(breadcrumb | userRatings).
iod accepts multiple, comma-separated values.
Notes If a product set ID is submitted, the current version of the software product in the set is returned. (There is one live product per product set, which is the most recent release or version of the software.)
Top-Level Response Nodes <SoftwareProduct> if productId or productSetId is submitted, or <SoftwareProducts> if productIds or productSetIds is submitted.
Example Request URL http://developer.api.cnet.com/rest/v1.0/softwareProduct?
iod=breadcrumb%2CuserRatings&productId=10605855&partTag=[yourDeveloperKey]
Example XML Response 
<CNETResponse version="1.0">
   <SoftwareProduct id="10605855" setId="10003164"
      xlink:href="http://developer.api.cnet.com/rest/v1.0/softwareProduct
      ?productSetId=10003164&iod=all">
      <Name>WinZip</Name>

      <Version>11</Version>
      <LinkURL>http://www.download.com/3000-2250_4-10003164.html</LinkURL>
      <Publisher id="50220">
         <Name>WinZip Computing</Name>

         <LinkURL>http://www.winzip.com/</LinkURL>
      </Publisher>
      <License>Free to try</License>
      <Price>$29.95</Price>

      <Summary>
         Handle ZIP files with ease with this popular utility.
      </Summary>
      <Description>
         <p>WinZip is the original and most popular of all Windows
         ZIP file utilities.  Wizard/Classic interfaces accommodate both
         first-time and experienced users. With WinZip you can quickly and
         easily compress and decompress files, folders, and entire folder
         trees to save storage space and reduce e-mail-transmission time,
         as well as encrypt and decrypt your sensitive documents. Features
         include tight integration with Windows Explorer, support for most
         Internet file formats, and one-click zipping and e-mail. Version 11
         improves the Job Wizard and adds a number of compression and
         usability enhancements, as well as the ability to open BZ2 and RAR
         files.</p>
         <p><b>Note:</b> WinZip is now bundled with Google Toolbar
         and Google Desktop Search. Installation of these components is
         optional.</p>

      </Description>
      <Requirements>Windows 98/Me/2000/XP</Requirements>
      <PreferredNode id="2250"/>
      <Category id="2250" xlink:href="http://developer.api.cnet.com/rest/v1.0/
         category?categoryId=2250">
         <Title>File Compression</Title>

         <Breadcrumb>Downloads^Windows^Utilities & Drivers^File Compression
         </Breadcrumb>
         <Node id="20" xlink:href="http://developer.api.cnet.com/rest/v1.0/category?
            categoryId=20">
            <Name>Downloads</Name>
         </Node>

         <Node id="2001" xlink:href="http://developer.api.cnet.com/rest/v1.0/category?
            categoryId=2001">
            <Name>Windows</Name>
         </Node>
         <Node id="2018" xlink:href="http://developer.api.cnet.com/rest/v1.0/category?
            categoryId=2018">
            <Name>Utilities & Drivers</Name>

         </Node>
         <Node id="2250" xlink:href="http://developer.api.cnet.com/rest/v1.0/category?
            categoryId=2250">
            <Name>File Compression</Name>
         </Node>
      </Category>

      <UserRatingSummary>
         <Rating outOf="5">3.7</Rating>
         <TotalVotes>665</TotalVotes>
      </UserRatingSummary>
   </SoftwareProduct>

</CNETResponse>

 

Software product search

Resource Name /softwareProductSearch
Description Returns software products for a given combination of category and keywords.
Required Parameters Either categoryId or query.
Optional Parameters categoryId, query, iod, orderBy, sortDesc, start and results.

iod=(breadcrumb | userRatings). iod accepts multiple, comma-separated values.

orderBy=( popularity | editorsRating | downloadCount | publisherName | productName). orderBy accepts one value.
Top-Level Response Nodes <SoftwareProducts>
Example Request URL http://developer.api.cnet.com/rest/v1.0/softwareProductSearch?
&categoryId=2250&query=winzip&iod=none&start=0&results=1
Example XML Response 
<CNETResponse version="1.0">
  <SoftwareProducts start="0" numReturned="1" numFound="25">
    <SoftwareProduct id="10665474" setId="10003164"
      xlink:href="http://developer.api.cnet.com/rest/v1.0/softwareProduct?
      productSetId=10003164">
      <Name>WinZip</Name>

      <Version>11.1</Version>
      <LinkURL>http://www.download.com/3000-2250_4-10003164.html</LinkURL>
      <Publisher id="50220">
        <Name>WinZip Computing</Name>

        <LinkURL>http://www.winzip.com/</LinkURL>
      </Publisher>
      <License>Free to try</License>
      <Price>$29.95</Price>

      <Summary>
        Zip and unzip your files quickly to conserve disk space and greatly
        reduce e-mail transmission time.
      </Summary>
      <Description>
        <p>WinZip is the original and most popular of all Windows ZIP
    file utilities. Wizard/Classic interfaces accommodate both first-time
    and experienced users. With WinZip you can quickly and easily compress
    and decompress files, folders, and entire folder trees to save storage
    space and reduce e-mail-transmission time, as well as encrypt and
    decrypt your sensitive documents. Features include tight integration
    with Windows Explorer, support for most Internet file formats, and
    one-click zipping and e-mail. Version 11.1 adds Vista compatibility.
    </p> <p><b>Note:</b> WinZip is now bundled
    with Google Toolbar and Google Desktop Search. Installation of these
    components is optional.</p>

      </Description>
      <Requirements>Windows 98/Me/2000/XP/Vista</Requirements>
      <EditorsRating outOf="5">5.0</EditorsRating>
      <PreferredNode id="2250"/>
      <Category id="2250" xlink:href="http://developer.api.cnet.com/rest/v1.0/category?
      categoryId=2250&siteId=4"/>

    </SoftwareProduct>
  </SoftwareProducts>
</CNETResponse>

 

Request parameters

The following table provides descriptions and value types for the request parameters. An O indicates the parameter is optional for the named resource; an R indicates it is required.

Parameter Description Value Type REST Resource
Category Child Categories Tech Product Search Tech Product by ID Software Product by ID Software Product Search
categoryId The ID of a given product category. numeric R --- R1 --- --- R1
callback Specifies a method to pass the JSON object to. Used with viewType=json. string O O O O O ---
criteria Multiple pipe-delimited sets of values may be passed for criteria in the form criteriaName=criteriaValue.

Possible values include minOffers=[N], minOffers=[N] and/or hasGoodBad=true.

For example: minOffers=1|hasGoodBad=true		 string --- --- O --- --- ---
iod Include Optional Data parameter. See below for supported iod values. string --- --- O O O O
orderBy Changes the order of the returned results. See below for supported orderBy values. string --- --- O O --- O
partKey Your Developer Key. To get one, sign up for a free CNET API membership. numeric R R R R R ---
productId The ID of the product being requested. numeric --- --- --- R1 R1 ---
productIds The IDs of the products being requested, comma-separated. numeric --- --- --- R1 R1 ---
productSetId The product set ID of the product being requested. numeric --- --- --- --- R1 ---
productSetIds The product set IDs of the products being requested, comma-separated. numeric --- --- --- --- R1 ---
query Search terms for a text search. string --- --- R1 --- --- R1
results The number of results to return in a result set. numeric --- --- O --- --- O
siteId The ID of the CNET site being queried. Currently these include:
  • 4 - Download
  • 7 - Reviews
  • 9 - Shopper
 numeric O O --- --- --- ---
sortDesc Reverses the returned order of results. sortDesc=(true | false) string --- --- --- O --- O
start The first result to return in a result set. numeric --- --- O --- --- O
viewType Requests a specific response type (the default is xml). (xml|json) string O O O O O ---
zipCode Returns localized tax and shipping costs. numeric --- --- --- O --- ---


1 At least one of the parameters marked as R1 is required for this resource.

The iod parameter

The iod (Include Optional Data) parameter is used to request that specific optional response data is returned. It accepts multiple, comma-separated values.

The table below provides descriptions of the various iod values. An O indicates the iod value is optional for the named API resource.

iod Value Description REST Resource
Tech Product Search Tech Product by ID Software Product by ID Software Product Search
breadcrumb Include category and product hierarchy for the requested product. O O O O
goodBad Include the editor's good, bad, and bottom line for the product. O O --- ---
hlPrice Include high and low pricing information. O O --- ---
none Displays basic product information if no values are selected. This is the default. --- --- --- ---
offers Include offers for a given product. O O --- ---
relatedCats Include related categories. O --- --- ---
userRatings Include the rating summary for the product. --- --- O O



The orderBy parameter

The orderBy parameter is used to change the order of the returned results. orderBy accepts one value at any given time. In the table below, an O indicates which orderBy value is optional for which API resource.

iod Value REST Resource
Tech Product Search Tech Product by ID Software Product Search
availability --- O ---
downloadCount --- --- O
editorsRating O --- O
manufacturerName O --- ---
popularity O --- O
price O O ---
productName --- --- O
publisherName --- --- O
storeName --- O ---
storeRating --- O ---
totalPrice Total price includes tax and shipping costs. Used with the zipCode parameter. --- O ---

 

JSON response format

For easy JavaScript integration, the CNET API supports JSON as a response format. The structure of a JSON request URL is the same as that of an XML request, with the addition of &viewtype=json. In addition, the callback parameter can be passed in the request URL. The callback parameter specifies a method to pass the JSON object to in the response.

The response object is a JSON representation of the corresponding XML response, built using the BadgerFish convention. The text body of an XML element becomes a child JSON string named '$'. The attributes of an XML element also become child strings, with an ampersand (@) prepended to the attribute name. Child XML elements become child JSON objects.

For additional information, including examples, see the BadgerFish site.

Comparison of XML and JSON Outputs

The XML response for Category 6449:

<CNETResponse version="1.0">

    <Category id="6449"
    xlink:href="http://developer.api.cnet.com/rest/v1.0/category?categoryId=6449">
    <Title>Home Entertainment</Title>
    <Breadcrumb>Home Entertainment</Breadcrumb>
    <FilteredSearchURL>
    http://developer.api.cnet.com/rest/v1.0/techProductSearch?categoryId=6449
    </FilteredSearchURL>

    <Node id="6449"
    xlink:href="http://developer.api.cnet.com/rest/v1.0/category?categoryId=6449">
    <Name>Home Entertainment</Name>
    </Node>
    </Category>
    </CNETResponse>

The corresponding JSON response for Category 6449 with callback=processReturnedCategory:

callback=processReturnedCategory:
processReturnedCategory(
{"CNETResponse":{
  "@version":"1.0",
  "Category":{
    "@id":"6449",
    "@xlink:href":
    "http:\/\/developer.api.cnet.com\/restApi\/v1.0\/category?categoryId=6449",
    "Title":{ "$":"Home Entertainment" },
    "Breadcrumb":{"$":"Home Entertainment"},
    "FilteredSearchURL":{
       "$":"http:\/\/developer.api.cnet.com\/restApi\/v1.0\/techProductSearch?categoryId=6449"
    },
    "Node":{
      "@id":"6449",
      "@xlink:href":
      "http:\/\/developer.api.cnet.com\/restApi\/v1.0\/category?categoryId=6449",
      "Name":{"$":"Home Entertainment"}
    }
  }
}}
)

Appendix A: Commonly used URLs

All Merchant Offers for a Given Product

http://developer.api.cnet.com/rest/v1.0/techProduct?productId=31518214&iod=offers&zipCode=94131&
orderBy=totalPrice&sortDesc=true&partTag=[yourDeveloperKey]

Tech Product Search by Search Term

http://developer.api.cnet.com/rest/v1.0/techProductSearch?&query=ipod&start=0&results=1&
partTag=[yourDeveloperKey]

Tech Product Pricing and Offer Count by Search Term

http://developer.api.cnet.com/rest/v1.0/techProductSearch?&query=nikon%20D50&iod=hlPrice%2CgoodBad&
start=0&results=1&partTag=[yourDeveloperKey]

Product Search by SKU

http://developer.api.cnet.com/rest/v1.0/techProductSearch?&query=25412&start=0&results=1&
partTag=[yourDeveloperKey]

Download.com Software Product Information

http://developer.api.cnet.com/rest/v1.0/softwareProduct?productSetId=10521614&
partTag=[yourDeveloperKey]

 Return to top

 

version 9 as of 4 months ago by Adam Goldband

Comments

New comments are not being accepted at this time.