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