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: FirstUsed-Sort by the date the item was first used. - FirstUsed-Sort by the date the item was last used. LastUsed-Sort by the date the item was last used. - LastUsed Name-Alphabetical, A-Z. - Name-Alphabetical, Z-A. Usages-Items least used to most used 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]
&Timestamp=[YYYY-MM-DDThh:mm:ssZ]
&Signature=[Request Signature]

	Important
	You must never display customer IDs publicly. You may use them in requests only to look up information. You may associate that information with a customer's name or nickname but never his or her 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