Menu
Alexa Web Information Service
Developer Guide

CategoryListings

Description

The CategoryListings action is a directory service. For any given category, it returns a list of site listings contained within that category.

Request Parameters

The CategoryListings Action takes the following parameters. Required parameters must be provided for the request to succeed.

Name Description Required
Action

CategoryListings

Yes
ResponseGroup

Listings is the only available response group.

Yes
Path

Valid category path. Note that top-level categories will not return any listings unless Recursive=yes is specified (see below). Example values are Top/Arts, Top/Business/Automotive

Note that the value should be URL-encoded. For example, Path=Top%2FBusiness%2FConsumer_Goods_and_Services%2FElectronics

Yes
SortBy

How to sort the results returned by this service: ( Popularity | Title | AverageReview )

No
Recursive

Whether to return listings for the current category only, or for the current category plus all subcategories: (True | False)

No
Start

1-based index of result at which to start. Note: An empty document will be returned if this value exceeds the total number of available results.

No
Count

Number of results to return for this request, beginning from specified Start number (maximum 20)

No
Descriptions

Whether to return descriptions with categories: (True | False)

No

Sample Request

The following example shows a query-style request and response

Request

https://awis.amazonaws.com/api?
            Action=CategoryListings
            &ResponseGroup=Listings
            &Path=[Top/Arts, Top/Business/Automotive]
            &SortBy=[one of: ( Popularity | Title | AverageReview )]
            &Recursive=[True | False]
            &Start=[number to start at]
            &Count=[Number of results to return]
            &Descriptions=[True | False]
            

Headers

Authorization: AWS4-HMAC-SHA256 Credential=<IAM_ACCESS_KEY>/20171114/us-west-1/awis/aws4_request, SignedHeaders=host;x-amz-date, Signature=<GENERATED_AUTH_V4_SIGNATURE>
Content-Type: application/xml
X-Amz-Date: 20171114T190104Z
Accept: application/xml
        

Response

<aws:CategoryListingsResponse xmlns:aws="http://alexa.amazonaws.com/doc/2005-10-05/">
<aws:Response xmlns:aws="http://awis.amazonaws.com/doc/2005-07-11">
<aws:OperationRequest>
<aws:RequestId>0bf0a4b0-a441-49e7-9cfe-44b71e0df086</aws:RequestId>
</aws:OperationRequest>
<aws:CategoryListingsResult>
<aws:Alexa>
  
  <aws:CategoryListings>
    <aws:RecursiveCount>1804</aws:RecursiveCount>
    <aws:Count>217</aws:Count>
    <aws:Listings>
      <aws:Listing>
        <aws:DataUrl type="navigable">http://www.sony.com</aws:DataUrl>
        <aws:Title>Sony Electronics</aws:Title>
        <aws:PopularityRank>882</aws:PopularityRank>
      </aws:Listing>
      <aws:Listing>
        <aws:DataUrl type="navigable">http://www.samsung.com/</aws:DataUrl>
        <aws:Title>Samsung Electronics</aws:Title>
        <aws:PopularityRank>899</aws:PopularityRank>
      </aws:Listing>
    </aws:Listings>
  </aws:CategoryListings>
  
</aws:Alexa>
</aws:CategoryListingsResult>
<aws:ResponseStatus xmlns:aws="http://alexa.amazonaws.com/doc/2005-10-05/">
<aws:StatusCode>Success</aws:StatusCode>
</aws:ResponseStatus>
</aws:Response>
</aws:CategoryListingsResponse>