.. include:: _include.rst .. highlight:: bbcode .. _shortcodes_asa2_keywords: ################################# [asa2_keywords] ################################# Since version: 1.13.0 With the shortcode [asa2_keywords] you can dynamically display the results of an Amazon product search on your site. The supported :ref:`shortcodes_asa2_keywords_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**. .. code:: [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 :ref:`templates_managed_flex_1`. The most useful filters are: * **Price filters** :ref:`shortcodes_asa2_keywords_option_min_price` and :ref:`shortcodes_asa2_keywords_option_max_price`, with which you can determine the price range of the results. * **Sorting filter** :ref:`shortcodes_asa2_keywords_option_sort_by` It allows you to sort not only **by price**, but also by **type of products**, such as new releases. * **Rating filter** :ref:`shortcodes_asa2_keywords_option_min_reviews_rating` which considers the customer ratings. * **Search Index filter** :ref:`shortcodes_asa2_keywords_option_search_index` to narrow down the search range. * **Savings filter** :ref:`shortcodes_asa2_keywords_option_min_saving_percent` to include products with special offer price. * **Delivery program** filters :ref:`shortcodes_asa2_keywords_option_delivery_flags` to filter by a delivery type, like "Prime". Repo transfer ~~~~~~~~~~~~~ Expert hint: The products delivered by the keywords search can be stored in the |repo|. The option :ref:`options_keywords_store_in_repo` must be activated for this. Useful options in dealing with repo transfer: * :ref:`shortcodes_asa2_keywords_option_repo_categories` * :ref:`shortcodes_asa2_keywords_option_repo_tags` * :ref:`shortcodes_asa2_keywords_option_repo_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% .. code:: [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] .. image:: _static/asa2_keywords_advanced_usage.jpg :height: 402px :width: 594px :scale: 100% :alt: Keywords advanced usage In the following you will find a detailed description of all options that the shortcode ``[asa2_keywords]`` supports: .. _shortcodes_asa2_keywords_options: ******* 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 ------------------------ .. code:: [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: .. code-block:: ruby [asa2_keywords actor="Sandra Bullock" search_index="MoviesAndTV"]bluray[/asa2_keywords] .. image:: _static/asa2_keywords_option_actor.jpg :height: 322px :width: 620px :scale: 100% :alt: 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: .. code-block:: ruby [asa2_keywords artist="Coldplay" search_index="Music"]live album[/asa2_keywords] .. image:: _static/asa2_keywords_option_artist.jpg :height: 331px :width: 603px :scale: 100% :alt: 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. .. code-block:: ruby [asa2_keywords search_index="Books" author="Hermann Hesse"]siddhartha[/asa2_keywords] .. image:: _static/asa2_keywords_option_author.jpg :height: 328px :width: 605px :scale: 100% :alt: 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: .. code:: [asa2_keywords brand="Sony" search_index="Electronics"]smartphone[/asa2_keywords] .. image:: _static/asa2_keywords_option_brand.jpg :height: 348px :width: 603px :scale: 100% :alt: 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 ---------------------- .. code:: [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: .. code-block:: ruby [asa2_keywords condition="Collectible" search_index="Books"]goethe faust[/asa2_keywords] .. image:: _static/asa2_keywords_option_collectible.jpg :height: 340px :width: 601px :scale: 100% :alt: 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. .. code:: [asa2_keywords country_code="US"]nintendo switch lite[/asa2_keywords] .. _shortcodes_asa2_keywords_option_delivery_flags: 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. .. code:: [asa2_keywords search_index="Apparel" delivery_flags="Prime"]business coat woman[/asa2_keywords] .. image:: _static/asa2_keywords_option_delivery_flags.jpg :height: 393px :width: 665px :scale: 100% :alt: Keywords option delivery flags You can combine values: .. code:: [asa2_keywords search_index="Apparel" delivery_flags="FreeShipping,FulfilledByAmazon"]business coat woman[/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. .. code:: [asa2_keywords limit="6"]nintendo switch lite[/asa2_keywords] .. _shortcodes_asa2_keywords_option_max_price: 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: .. code-block:: ruby [asa2_keywords search_index="VideoGames" max_price="2000" sort_by="AvgCustomerReviews"]playstation 4[/asa2_keywords] .. image:: _static/asa2_keywords_option_max_price.jpg :height: 335px :width: 601px :scale: 100% :alt: 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: .. code:: [asa2_keywords merchant="Amazon"]playstation[/asa2_keywords] .. _shortcodes_asa2_keywords_option_min_price: 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: .. code:: [asa2_keywords min_price="1000" max_price="2000" sort_by="Price:LowToHigh" search_index="VideoGames"]playstation 4[/asa2_keywords] .. image:: _static/asa2_keywords_option_min_price.jpg :height: 341px :width: 602px :scale: 100% :alt: Keywords option min_price .. _shortcodes_asa2_keywords_option_min_reviews_rating: 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**: .. code:: [asa2_keywords min_reviews_rating="4" max_price="3000"]headphones wireless[/asa2_keywords] .. _shortcodes_asa2_keywords_option_min_saving_percent: 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 -------------------------- .. code:: [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. .. code:: [asa2_keywords limit="6" no_cache="1"]nintendo switch lite[/asa2_keywords] .. _shortcodes_asa2_keywords_option_repo_categories: repo_categories ~~~~~~~~~~~~~~~ If option :ref:`options_keywords_store_in_repo` is activated, you can use option ``repo_categories`` to define Repo categories that should be automatically saved for the new product when transferring it to the Repo. You can specify one or more categories separated by commas. repo_categories example ----------------------- .. code:: [asa2_keywords min_saving_percent="50" repo_categories="headphones"]headphones wireless[/asa2_keywords] .. _shortcodes_asa2_keywords_option_repo_tags: repo_tags ~~~~~~~~~~~~~~~ If option :ref:`options_keywords_store_in_repo` is activated, you can use option ``repo_tags`` to define Repo tags that should be automatically saved for the new product when transferring it to the Repo. You can specify one or more tags separated by commas. repo_tags example ----------------------- .. code:: [asa2_keywords min_saving_percent="50" repo_tags="wireless, red"]headphones wireless red[/asa2_keywords] .. _shortcodes_asa2_keywords_option_repo_transfer: repo_transfer ~~~~~~~~~~~~~ Use this option to dynamically **disable the automatic saving** of products in the |repo| (see :ref:`repo`). .. note:: The **automatic saving** of products resulting from the keyword search is **not activated by default** and must first be activated with the option :ref:`options_keywords_store_in_repo`. 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 repo. * Supported values: "false", "0" repo_transfer example ----------------------- To deactivate item transfer to the |repo|, use the option like this: .. code:: [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. .. code:: [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. .. code:: [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". .. image:: _static/asa2_keywords_search_index_left_column.jpg :height: 321px :width: 582px :scale: 100% :alt: 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 ======================= ================================================ .. _shortcodes_asa2_keywords_option_sort_by: 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: .. code:: [asa2_keywords sort_by="NewestArrivals" search_index="VideoGames"]playstation 4[/asa2_keywords] .. image:: _static/asa2_keywords_option_sort_by.jpg :height: 338px :width: 600px :scale: 100% :alt: 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. :ref:`templates_managed_flex_1`. .. code:: [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. .. code:: [asa2_keywords tplid="16"]nintendo switch lite[/asa2_keywords] .. image:: _static/templates_col_id.jpg :height: 267px :width: 527px :scale: 100% :alt: Templates table column ID tracking_id ~~~~~~~~~~~ You can also set a custom Associate ID in the asa2_keywords options. .. code:: [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. .. code:: [asa2_keywords my_custom_text="Banana!"]nintendo switch lite[/asa2_keywords] # use placeholder {{ my_custom_text }} in your template