TagLookup
Description
The TagLookup
operation returns entities based on specifying
one to five tags. A tag is a descriptive word that a customer uses to label entities on
Amazon's retail web site. Entities can be items for sale, Listmania lists, guides, and so
forth. For example, a customer might tag a given entity with the phrase, “BestCookbook.” For
more information, see Tags.
In the tag-related response groups, Tags and TagSummary specify the amount of information returned. The other tag-related response groups, TaggedGuides, TaggedItems, and Tagged listmaniaLists, specify the kind of entity tagged.
Availability
US only.
Request Parameters
Name | Description | Required |
---|---|---|
Count
|
Number of tagged entities to return per tag. The default is 5; the maximum is 20. Type: Integer Default: None |
No |
CustomerId
|
Alphanumeric token that uniquely identifies a customer. This parameter limits the tags returned to those provided by a single customer. Type: String Default: None |
No |
Item |
Container for attributes that describe an item. This parameter is valid in SOAP
requests only. Constraint: SOAP requests only |
Conditional |
Items |
Container for one or more Item objects. This parameter is valid in SOAP requests
only. Constraint: SOAP requests only |
Conditional |
TagPage
|
Specifies the page of results to return. There are twenty results on a page. Type: Integer Default: None |
No |
TagName |
Comma separated list of tag names. Up to five tags can be included in a request. Type: String Default: None |
Yes |
TagSort
|
Specifies the sorting order for the results. Type: String Default: -Usages Valid Values:
To sort items in descending order, prefix the previous values with a negative sign (-). |
No |
ResponseGroup
|
Specifies the types of values to return. You can specify multiple response groups in one request by separating them with commas. Type: String Default: Request | TagsSummary | TaggedItems Valid Values: EditorialReview | ItemAttributes | ItemIds | Large | Medium | Small | TaggedGuides | TaggedListmaniaLists | Tags | |
No |
TagLookup
also accepts the parameters that all operations can use.
For more information, see, Common Request
Parameters.
Response
Name | Description |
---|---|
ASIN | Alphanumeric token that identifies items for sale. |
CustomerId | Alphanumeric token that uniquely identifies a customer. |
DistinctUsers | Number of different users that created tags for entity. |
FirstTagging | Container for information relating to the first time the entity was tagged. |
Item | Container for information about an item. |
LastTagging | Container for information relating to the last time the entity was tagged. |
Name | Tag name. |
Tag | Container for information related to Tags |
TaggedItems | Container for Tag elements, such as Item and DistinctUsers. |
TagName | TAg name. |
Tags | Container for all Tag elements. |
TagType | Describes the entity tagged, for example, Items. |
Time | The time an entity was tagged. |
TotalUsages | Number of times tag was accessed. |
UserId | Same as the customer ID. |
For more information about the parent elements of these tags, see the appropriate response group in Response Groups.
Examples
Find items tagged by a specific customer
http://ecs.amazonaws.com/onca/xml? Service=AWSECommerceService& AWSAccessKeyId=[Access Key ID]
& AssociateTag=[Associate Tag]
& Operation=TagLookup& ItemId=0545010225& ResponseGroup=Tags& Marketplace=us& Version=2008-08-19& TagName=tai& CustomerId=[Customer ID]
The response to this request is shown in, Response to Sample Request.
Sample Response
The following XML is a snippet of the full response to the first sample request.
<Tag> <Name>tai</Name> <TagType>Items</TagType> <DistinctItems>1</DistinctItems> <DistinctUsers>1</DistinctUsers> <TotalUsages>1</TotalUsages> <FirstTagging> <EntityId>B00005A1UV</EntityId> <UserId>A2ELLA3OQ06A6Z</UserId> <Time>2005-12-07 14:41:52</Time> </FirstTagging> <LastTagging> <EntityId>B00005A1UV</EntityId> <UserId>A2ELLA3OQ06A6Z</UserId> <Time>2005-12-07 14:41:52</Time> </LastTagging> <TaggedItems> <Item> <ASIN>B00005A1UV</ASIN> </Item> </TaggedItems> </Tag>
Related Operations
-
ItemLookup using the Tags and TagSummary response groups
-
ItemSearch using the Tags and TagSummary response groups