[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]
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]
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]
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]
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]
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]
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]
item_page¶
Defines the search result page. By default, only the ten results of the first search result page are displayed. With the option item_page
, the results of the further result pages can be requested specifically. Valid options are 1 - 10. Default is 1.
[asa2_keywords item_page="2"]nintendo switch games[/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]
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]
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_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”.
List of available Search Indexes¶
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]
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]
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