[asa2_keywords]

Since version: 1.13.0

Introduction

With the shortcode [asa2_keywords] you can dynamically display the results of an Amazon product search on your site.

The supported Options are documented on this page.

Note

Expert knowledge: The keywords feature internally uses the PA API operation SearchItems and therefore supports the capabilities of this product search function to the greatest extent possible.

Basic usage

The keywords for the product search must be placed between the shortcodes.

[asa2_keywords]keywords[/asa2_keywords]

// Example:
[asa2_keywords]nintendo switch lite[/asa2_keywords]

Advanced usage

But the full power of the feature only takes effect when you use and combine its search filters and display the result with a grid-compatible ASA2 template, such as Flex_1.

The most useful filters are:

  • Price filters min_price and max_price, with which you can determine the price range of the results.

  • Sorting filter sort_by It allows you to sort not only by price, but also by type of products, such as new releases.

  • Rating filter min_reviews_rating which considers the customer ratings.

  • Search Index filter shortcodes_asa2_keywords_option_search_index to narrow down the search range.

  • Savings filter min_saving_percent to include products with special offer price.

  • Delivery program filters delivery_flags to filter by a delivery type, like “Prime”.

Product transfer

Expert hint: The products delivered by the keywords search can be stored in the Products section. The option Store results must be activated for this.

Useful options in dealing with product transfer:

Advanced usage example

To illustrate the combination of filters, here is a good example.

This following shortcode shows

  • new products

  • from the category “Beauty

  • for the search term “perfume”,

  • which cost between 10 and 30 currency units

  • and have some special offer prices included, at least 5%

[asa2_keywords search_index="Beauty" sort_by="NewestArrivals" min_price="1000" max_price="3000" min_saving_percent="5" tpl="Flex_1" limit="3"]perfume[/asa2_keywords]
Keywords advanced usage

In the following you will find a detailed description of all options that the shortcode [asa2_keywords] supports:

Options

associate_id_set

Defines which Associate ID set to use. The Associate ID of a product’s country code will be used if it was found in the set.

Note

Option tracking_id is dominant, meaning that if you set tracking_id, this ID will be used and associate_id_set will be ignored.

associate_id_set example

[asa2_keywords associate_id_set="my-other-partner-ids"]nintendo switch lite[/asa2_keywords]

actor

If you want to limit the search results by actor, you can use the “actor” option. This is very suitable for movies.

  • Value Type: String (Non-Empty)

  • Default Value: None

actor example

To display movies with Sandra Bullock available on Blu-ray, use this shortcode:

[asa2_keywords actor="Sandra Bullock" search_index="MoviesAndTV"]bluray[/asa2_keywords]
Keywords option actor

artist

If you want to limit the search results by artist, you can use the “artist” option. This is very suitable for music.

  • Value Type: String (Non-Empty)

  • Default Value: None

artist example

To display live albums from Coldplay, use this shortcode:

[asa2_keywords artist="Coldplay" search_index="Music"]live album[/asa2_keywords]
Keywords option artist

author

If you want to limit the search results by author, you can use the “author” option. This is very suitable for books.

  • Value Type: String (Non-Empty)

  • Default Value: None

author example

If you want to display books on the topic Siddhartha by Hermann Hesse only, the following shortcode will lead you to the goal.

[asa2_keywords search_index="Books" author="Hermann Hesse"]siddhartha[/asa2_keywords]
Keywords option author

brand

If you want to limit the search results by brand, you can use the “brand” option.

  • Value Type: String (Non-Empty)

  • Default Value: None

brand example

To display smartphones from Sony, use this shortcode:

[asa2_keywords brand="Sony" search_index="Electronics"]smartphone[/asa2_keywords]
Keywords option artist

browse_node_id

If you want to limit the search results by browse node ID, you can use the “browse_node_id” option. It is a unique ID assigned by Amazon that identifies a product category/sub-category.

browse_node_id example

[asa2_keywords browse_node_id="290060"]search term[/asa2_keywords]

condition

If you want to limit the search results by product condition, you can use the “condition” option.

  • Value Type: String

  • Default Value: Any

Supported Values

Description

Any (Default)

Offer Listings for items across any condition

New

Offer Listings for New items

Used

Offer Listings for Used items

Collectible

Offer Listings for Collectible items

Refurbished

Offer Listings for Certified Refurbished items

condition example

To display collectibles of Goethe’s Faust use this shortcode:

[asa2_keywords condition="Collectible" search_index="Books"]goethe faust[/asa2_keywords]
Keywords option condition

country_code

Use a valid Amazon country code to retrieve only products from that country store.

country_code example

This example will only show products from the “US” Amazon store.

[asa2_keywords country_code="US"]nintendo switch lite[/asa2_keywords]

delivery_flags

Use this option to filter products for certain delivery programs promoted by the specific Amazon Marketplace.

  • Value Type: List of Strings (comma separated)

  • Default Value: None

Supported Values

Description

AmazonGlobal

A delivery program featuring international shipping to certain Exportable Countries

FreeShipping

A delivery program featuring free shipping of an item

FulfilledByAmazon

Fulfilled by Amazon indicates that products are stored, packed and dispatched by Amazon

Prime

An offer for an item which is eligible for Prime Program

delivery_flags example

This example will only show business coats for women that are eligible for Prime Program.

[asa2_keywords search_index="Apparel" delivery_flags="Prime"]business coat woman[/asa2_keywords]
Keywords option delivery flags

You can combine values:

[asa2_keywords search_index="Apparel" delivery_flags="FreeShipping,FulfilledByAmazon"]business coat woman[/asa2_keywords]

id

With the option “id” you can define a unique identifier for a shortcode, under which ASA2 can remember it, in order to refresh the result for this shortcode before the cache expires.

IDs may only contain alphanumeric letters, numbers, underscores and hyphens (no spaces).

More details about the keywords preloading function, you can find in the Keywords section.

[asa2_keywords id="business-coats-woman" search_index="Apparel"]business coat woman[/asa2_keywords]

[asa2_keywords id="bluray-sandra-bullock" search_index="MoviesAndTV"]sandra bullock bluray[/asa2_keywords]

[asa2_keywords id="beauty-products-new-arrivals" search_index="Beauty" sort_by="NewestArrivals"]perfume[/asa2_keywords]

limit

To limit the result of a keyword search, use the limit option. The default limit is 10. Also the maximum is 10 as this is the maximum result for a PA API product search.

  • Value Type: Integer (Between 1 to 10)

  • Default Value: 10

The following example will generate a list of 6 products if the search was successful.

[asa2_keywords limit="6"]nintendo switch lite[/asa2_keywords]

max_price

If you want to give the search results a maximum price, you can use the max_price option. The search results will have at least one offer price below the specified price.

Note

The maximum price must be given as an integer with decimal places, but without decimal point.

  • Value type: Positive Integer

  • Default Value: None

So if you want to define a maximum price of $25, the correct value is 2500.

$25 = 2500

19.99 € = 1999

… and so on.

max_price example

To display playstation 4 products cheaper than 20.00 sorted by user rating, use this shortcode:

[asa2_keywords search_index="VideoGames" max_price="2000" sort_by="AvgCustomerReviews"]playstation 4[/asa2_keywords]
Keywords option max_price

merchant

With the option “merchant” you can filter the search results by merchant.

  • Value Type: String

  • Default Value: All

Supported Values

Description

All (Default)

List Offers from all Merchants

Amazon

List Offers only from Amazon

merchant example

To display offers only from Amazon, use this shortcode:

[asa2_keywords merchant="Amazon"]playstation[/asa2_keywords]

min_price

If you want to give the search results a minimum price, you can use the min_price option. The search results will have at least one offer price above the specified price.

Note

The minimum price must be given as an integer with decimal places, but without decimal point.

  • Value type: Positive Integer

  • Default Value: None

So if you want to define a minimum price of $25, the correct value is 2500.

$25 = 2500

19.99 € = 1999

… and so on.

min_price example

To display playstation 4 products cheaper than 20.00 but you want to exclude products below 10.00, sorted by ascending price, use this shortcode:

[asa2_keywords min_price="1000" max_price="2000" sort_by="Price:LowToHigh" search_index="VideoGames"]playstation 4[/asa2_keywords]
Keywords option min_price

min_reviews_rating

With the option “min_reviews_rating” search results can be filtered for products with user ratings above the specified value.

  • Value type: Positive Integer less than 5

  • Default Value: None

min_reviews_rating example

To show wireless headphones with a user review rating of at least 4 and cheaper than 30.00:

[asa2_keywords min_reviews_rating="4" max_price="3000"]headphones wireless[/asa2_keywords]

min_saving_percent

With option “min_saving_percent” you can filter search results to items with at least one offer having saving percentage above the specified value.

  • Value Type: Positive Integer less than 100

  • Default Value: None

min_saving_percent example

[asa2_keywords min_saving_percent="50"]headphones wireless[/asa2_keywords]

no_cache

The no_cache option will prevent the keyword search result from being loaded from cache. This is useful if you want to test template updates in the frontend. In production you should use it with care.

[asa2_keywords limit="6" no_cache="1"]nintendo switch lite[/asa2_keywords]

repo_categories

If option Store results is activated, you can use option repo_categories to define product categories that should be automatically saved for the new product when transferring it to the Products section. You can specify one or more categories separated by commas.

repo_categories example

[asa2_keywords min_saving_percent="50" repo_categories="headphones"]headphones wireless[/asa2_keywords]

repo_tags

If option Store results is activated, you can use option repo_tags to define product tags that should be automatically saved for the new product when transferring it to the Products section. You can specify one or more tags separated by commas.

repo_tags example

[asa2_keywords min_saving_percent="50" repo_tags="wireless, red"]headphones wireless red[/asa2_keywords]

repo_transfer

Use this option to dynamically disable the automatic saving of products in the Products section (see Products).

Note

The automatic saving of products resulting from the keyword search is not activated by default and must first be activated with the option Store results.

This option is recommended as long as you develop or optimize the appropriate options for a keyword search. If everything is right, you can remove this option and from then on the products will be saved in the Products section.

  • Supported values: “false”, “0”

repo_transfer example

To deactivate item transfer to the Products section, use the option like this:

[asa2_keywords repo_transfer="false"]headphones wireless red[/asa2_keywords]
// or
[asa2_keywords repo_transfer="0"]headphones wireless red[/asa2_keywords]

search_index

With the “search_index” option you can narrow down the results of the search to a specific product range from Amazon’s directory. The default is “All”, which means a search across all categories.

[asa2_keywords search_index="VideoGames" limit="6"]nintendo switch lite[/asa2_keywords]

For example, if you want to display only books instead of video games about Super Mario, you can use the “Books” search index.

[asa2_keywords search_index="Books"]super mario[/asa2_keywords]

The available categories vary according to the country. For a list of available search indexes, please check the pages linked below.

The following screenshot shows a section of available product ranges of the German store and the values to be used in the left column.

Note

Use the term in the left column “Search Index” as option value for “search_index”.

Keywords search index left column

List of available Search Indexes

Store

URL

Australia

https://webservices.amazon.com/paapi5/documentation/locale-reference/australia.html#search-index

Brazil

https://webservices.amazon.com/paapi5/documentation/locale-reference/brazil.html#search-index

Canada

https://webservices.amazon.com/paapi5/documentation/locale-reference/canada.html#search-index

France

https://webservices.amazon.com/paapi5/documentation/locale-reference/france.html#search-index

Germany

https://webservices.amazon.com/paapi5/documentation/locale-reference/germany.html#search-index

India

https://webservices.amazon.com/paapi5/documentation/locale-reference/india.html#search-index

Italy

https://webservices.amazon.com/paapi5/documentation/locale-reference/italy.html#search-index

Japan

https://webservices.amazon.com/paapi5/documentation/locale-reference/japan.html#search-index

Mexico

https://webservices.amazon.com/paapi5/documentation/locale-reference/mexico.html#search-index

Singapore

https://webservices.amazon.com/paapi5/documentation/locale-reference/singapore.html#search-index

Spain

https://webservices.amazon.com/paapi5/documentation/locale-reference/spain.html#search-index

Turkey

https://webservices.amazon.com/paapi5/documentation/locale-reference/turkey.html#search-index

United Arab Emirates

https://webservices.amazon.com/paapi5/documentation/locale-reference/united-arab-emirates.html#search-index

United Kingdom

https://webservices.amazon.com/paapi5/documentation/locale-reference/united-kingdom.html#search-index

United States

https://webservices.amazon.com/paapi5/documentation/locale-reference/united-states.html#search-index

sort_by

With the option “sort_by” you can adjust the sort order of the search result. Default value is: none.

  • Value Type: String

  • Default Value: None

Supported Values

Description

AvgCustomerReviews

Sorts results according to average customer reviews

Featured

Sorts results with featured items having higher rank

NewestArrivals

Sorts results with according to newest arrivals

Price:HighToLow

Sorts results according to most expensive to least expensive

Price:LowToHigh

Sorts results according to least expensive to most expensive

Relevance

Sorts results with relevant items having higher rank

sort_by example

To show the latest video games for PlayStation 4, use this shortcode:

[asa2_keywords sort_by="NewestArrivals" search_index="VideoGames"]playstation 4[/asa2_keywords]
Keywords option sort_by

tpl

If you do not want to use the default template to render the keyword search result, you can define a custom template by its name using the tpl option. It makes sense to use a grid compatible template, e.g. Flex_1.

[asa2_keywords tpl="Flex_1"]nintendo switch lite[/asa2_keywords]

tplid

If you want to define a template by its ID, use the tplid option. You can find the ID in the first column of the template table. Using the template ID allows you to change the template’s name afterwards.

[asa2_keywords tplid="16"]nintendo switch lite[/asa2_keywords]
Templates table column ID

tracking_id

You can also set a custom Associate ID in the asa2_keywords options.

[asa2_keywords tracking_id="other-id"]nintendo switch lite[/asa2_keywords]

Custom Values Placeholders

Additionally to the shortcode options, you can also define custom values to use as placeholders in templates.

It is very easy. Just define a unique shortcode option with a value and use the exact same option name as placeholder in a template.

[asa2_keywords my_custom_text="Banana!"]nintendo switch lite[/asa2_keywords]

# use placeholder {{ my_custom_text }} in your template