NEW Dell Studio Laptop Deal!CNET API: Reference guide
Contents
- Audience
- API resources
- Category
- Child categories
- Tech product by ID
- Tech product search
- Software product by ID
- Software product search
- Request parameters
- JSON response format
- Appendix A: Commonly used URLs
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://api.cnet.com/restApi/v1.0/category?categoryId=6475&siteId=7&partKey= [yourDeveloperKey] |
| Example XML Response |
<CNETResponse version="1.0">
<Category id="6475"
xlink:href="http://api.cnet.com/restApi/v1.0/category?categoryId=6475">
<Title>TVs</Title>
<Breadcrumb>Home Entertainment^TVs</Breadcrumb>
<Node id="6449"
xlink:href="http://api.cnet.com/restApi/v1.0/category?categoryId=6449">
<Name>Home Entertainment</Name>
</Node>
<Node id="6475"
xlink:href="http://api.cnet.com/restApi/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://api.cnet.com/restApi/v1.0/childCategories? siteId=9&partKey=[yourDeveloperKey] |
| Example XML Response |
<CNETResponse version="1.0">
<ChildCategories>
<Category id="6475"
xlink:href="http://api.cnet.com/restApi/v1.0/category?categoryId=6475">
<Title>TVs</Title>
<Breadcrumb>Home Entertainment^TVs</Breadcrumb>
</Category>
<Category id="6490"
xlink:href="http://api.cnet.com/restApi/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://api.cnet.com/restApi/v1.0/techProduct?productId=31303113&iod=hlPrice& partKey=[yourDeveloperKey] |
| Example XML Response |
<CNETResponse version="1.0">
<TechProduct id="31303113"
xlink:href="http://api.cnet.com/restApi/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://api.cnet.com/restApi/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://api.cnet.com/restApi/v1.0/techProductSearch?categoryId=6490& query=ipod&iod=hlPrice&start=0&results=1&partKey=[yourDeveloperKey] |
| Example XML Response |
<CNETResponse version="1.0">
<TechProducts start="0" numReturned="1" numFound="145">
<TechProduct id="32069546"
xlink:href="http://api.cnet.com/restApi/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://api.cnet.com/restApi/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://api.cnet.com/restApi/v1.0/softwareProduct? iod=breadcrumb%2CuserRatings&productId=10605855&partKey=[yourDeveloperKey] |
| Example XML Response |
<CNETResponse version="1.0">
<SoftwareProduct id="10605855" setId="10003164"
xlink:href="http://api.cnet.com/restApi/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://api.cnet.com/restApi/v1.0/
category?categoryId=2250">
<Title>File Compression</Title>
<Breadcrumb>Downloads^Windows^Utilities & Drivers^File Compression
</Breadcrumb>
<Node id="20" xlink:href="http://api.cnet.com/restApi/v1.0/category?
categoryId=20">
<Name>Downloads</Name>
</Node>
<Node id="2001" xlink:href="http://api.cnet.com/restApi/v1.0/category?
categoryId=2001">
<Name>Windows</Name>
</Node>
<Node id="2018" xlink:href="http://api.cnet.com/restApi/v1.0/category?
categoryId=2018">
<Name>Utilities & Drivers</Name>
</Node>
<Node id="2250" xlink:href="http://api.cnet.com/restApi/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://api.cnet.com/restApi/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://api.cnet.com/restApi/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://api.cnet.com/restApi/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.com 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:
|
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 OutputsThe XML response for Category 6449:
<CNETResponse version="1.0">
<Category id="6449"
xlink:href="http://api.cnet.com/restApi/v1.0/category?categoryId=6449">
<Title>Home Entertainment</Title>
<Breadcrumb>Home Entertainment</Breadcrumb>
<FilteredSearchURL>
http://api.cnet.com/restApi/v1.0/techProductSearch?categoryId=6449
</FilteredSearchURL>
<Node id="6449"
xlink:href="http://api.cnet.com/restApi/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:\/\/api.cnet.com\/restApi\/v1.0\/category?categoryId=6449",
"Title":{ "$":"Home Entertainment" },
"Breadcrumb":{"$":"Home Entertainment"},
"FilteredSearchURL":{
"$":"http:\/\/api.cnet.com\/restApi\/v1.0\/techProductSearch?categoryId=6449"
},
"Node":{
"@id":"6449",
"@xlink:href":
"http:\/\/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://api.cnet.com/restApi/v1.0/techProduct?productId=31518214&iod=offers&zipCode=94131&
orderBy=totalPrice&sortDesc=true&partKey=[yourDeveloperKey]
Tech Product Search by Search Term
http://api.cnet.com/restApi/v1.0/techProductSearch?&query=ipod&start=0&results=1&
partKey=[yourDeveloperKey]
Tech Product Pricing and Offer Count by Search Term
http://api.cnet.com/restApi/v1.0/techProductSearch?&query=nikon%20D50&iod=hlPrice%2CgoodBad&
start=0&results=1&partKey=[yourDeveloperKey]
Product Search by SKU
http://api.cnet.com/restApi/v1.0/techProductSearch?&query=25412&start=0&results=1&
partKey=[yourDeveloperKey]
Download.com Software Product Information
http://api.cnet.com/restApi/v1.0/softwareProduct?productSetId=10521614&
partKey=[yourDeveloperKey]
