> Portal Navigation: > > - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version. > - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages). > - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`). > - Top-level index of all portals: https://dev.wix.com/docs/llms.txt > - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt # ListSuggestedKeywords # Package: seo # Namespace: SeoKeywordsSuggestionsSPI # Method link: https://dev.wix.com/docs/api-reference/business-management/marketing/seo/seo-keywords-suggestions-service-plugin/list-suggested-keywords.md ## Introduction This method requests keyword suggestions for a specified phrase. You provide statistical data about the requested keyword and a list of similar keywords so the user can compare the SEO strength of the suggested keywords. Wix calls this method when a Wix user requests data about a keyword via the SEO page of the Dashboard. --- ## REST API ### Schema ``` Method: listSuggestedKeywords Description: This method requests keyword suggestions for a specified phrase. You provide statistical data about the requested keyword and a list of similar keywords so the user can compare the SEO strength of the suggested keywords. Wix calls this method when a Wix user requests data about a keyword via the SEO page of the Dashboard. URL: null Method: POST Method parameters: param name: countryCode | type: countryCode | description: Specific country for analysis. 2-letter country code in [ISO-3166 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements) format. param name: keyword | type: keyword | description: Keyword to analyze for SEO strength. Return type: ListSuggestedKeywordsResponse - name: data | type: array | description: Analysis of the keyword. - name: keyword | type: string | description: *Required**. Keyword suggestions offered by the SEO tool. - name: volume | type: integer | description: *Required**. Average number of searches per month for the keyword. - name: difficulty | type: integer | description: *Required**. Indicates how competitive the keyword is and how difficult to rank in an organic search. A higher difficulty means the keyword has a lower search ranking.
Min: `1`
Max: `100` - name: latestTrends | type: array | description: *Required**. Trends in searches for the keyword per month over the last 12 months. Must include exactly 12 values. Typically, the trend values represent the number of searches relative to the peak search volume. A value of `1.0` represents the highest search volume for the term. A value of `0.50` means that there were half as many searches.
Min: `0.0`
Max: `1.0` - name: searcherIntent | type: array | description: User's reason for searching for the keyword. - enum: - COMMERCIAL: Users searched for specific brands or services, usually with an intent to purchase. - INFORMATIONAL: Users searched for information about a topic. - NAVIGATIONAL: Users searched for a specific page, site, or physical location. - TRANSACTIONAL: Users searched to perform a transaction, for example a purchase. - name: quota | type: Quota | description: Updated quota after request processed. - name: remaining | type: integer | description: *Required**. Number of searches left until the end of the current quota cycle. - name: limit | type: integer | description: *Required**. Total number of searches available in the current quota cycle. - name: startDate | type: string | description: *Required**. Start date and time of the current quota cycle as UTC datetime in `YYYY-MM-DDThh:mm[:ss][.sss]Z` format. - name: endDate | type: string | description: *Required**. End date and time of the current quota cycle as UTC datetime in `YYYY-MM-DDThh:mm[:ss][.sss]Z` format. After this time, the quota is reset - name: paidPlan | type: boolean | description: *Required**. Whether the user currently has a paid plan. If `false`, the user is offered an upgrade using the `upgradeUrl` from the configuration. Possible Errors: HTTP Code: 401 | Status Code: UNAUTHENTICATED | Application Code: MISSING_TOKEN | Description: none HTTP Code: 429 | Status Code: RESOURCE_EXHAUSTED | Application Code: QUOTA_LIMIT_REACHED | Description: none ``` ### Examples ### List suggested keywords ```curl curl POST https://www.provider.example.com/v1/list-suggested-keywords \ -H 'Content-Type: application/json;charset=UTF-8' \ -H 'Authorization: ' \ --data '{ "keyword": "ice cream", "countryCode": "US" }' ``` --- ## JavaScript SDK ### Schema ``` Method: wixClientAdmin.seo.SeoKeywordsSuggestionsSPI.listSuggestedKeywords(request, metadata) Description: This method requests keyword suggestions for a specified phrase. You provide statistical data about the requested keyword and a list of similar keywords so the user can compare the SEO strength of the suggested keywords. Wix calls this method when a Wix user requests data about a keyword via the SEO page of the Dashboard. Method parameters: param name: metadata | type: Context | description: this message is not directly used by any service, it exists to describe the expected parameters that SHOULD be provided to invoked Velo methods as part of open-platform. e.g. SPIs, event-handlers, etc.. NOTE: this context object MUST be provided as the last argument in each Velo method signature. Example: ```typescript export function wixStores_onOrderCanceled({ event, metadata }: OrderCanceledEvent) { ... } ``` - name: requestId | type: string | description: A unique identifier of the request. You may print this GUID to your logs to help with future debugging and easier correlation with Wix's logs. - name: currency | type: string | description: [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) 3-letter currency code. - name: identity | type: IdentificationData | description: An object that describes the identity that triggered this request. - ONE-OF: - name: anonymousVisitorId | type: string | description: GUID of a site visitor that has not logged in to the site. - name: memberId | type: string | description: GUID of a site visitor that has logged in to the site. - name: wixUserId | type: string | description: GUID of a Wix user (site owner, contributor, etc.). - name: appId | type: string | description: GUID of an app. - name: languages | type: array | description: A string representing a language and region in the format of `"xx-XX"`. First 2 letters represent the language code according to ISO 639-1. This is followed by a dash "-", and then a by 2 capital letters representing the region according to ISO 3166-2. For example, `"en-US"`. - name: instanceId | type: string | description: The service provider app's instance GUID. param name: request | type: ListSuggestedKeywordsRequest - name: keyword | type: string | description: Keyword to analyze for SEO strength. - name: countryCode | type: string | description: Specific country for analysis. 2-letter country code in [ISO-3166 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements) format. Return type: PROMISE - name: data | type: array | description: Analysis of the keyword. - name: keyword | type: string | description: *Required**. Keyword suggestions offered by the SEO tool. - name: volume | type: integer | description: *Required**. Average number of searches per month for the keyword. - name: difficulty | type: integer | description: *Required**. Indicates how competitive the keyword is and how difficult to rank in an organic search. A higher difficulty means the keyword has a lower search ranking.
Min: `1`
Max: `100` - name: latestTrends | type: array | description: *Required**. Trends in searches for the keyword per month over the last 12 months. Must include exactly 12 values. Typically, the trend values represent the number of searches relative to the peak search volume. A value of `1.0` represents the highest search volume for the term. A value of `0.50` means that there were half as many searches.
Min: `0.0`
Max: `1.0` - name: searcherIntent | type: array | description: User's reason for searching for the keyword. - enum: - COMMERCIAL: Users searched for specific brands or services, usually with an intent to purchase. - INFORMATIONAL: Users searched for information about a topic. - NAVIGATIONAL: Users searched for a specific page, site, or physical location. - TRANSACTIONAL: Users searched to perform a transaction, for example a purchase. - name: quota | type: Quota | description: Updated quota after request processed. - name: remaining | type: integer | description: *Required**. Number of searches left until the end of the current quota cycle. - name: limit | type: integer | description: *Required**. Total number of searches available in the current quota cycle. - name: startDate | type: Date | description: *Required**. Start date and time of the current quota cycle as UTC datetime in `YYYY-MM-DDThh:mm[:ss][.sss]Z` format. - name: endDate | type: Date | description: *Required**. End date and time of the current quota cycle as UTC datetime in `YYYY-MM-DDThh:mm[:ss][.sss]Z` format. After this time, the quota is reset - name: paidPlan | type: boolean | description: *Required**. Whether the user currently has a paid plan. If `false`, the user is offered an upgrade using the `upgradeUrl` from the configuration. Possible Errors: HTTP Code: 401 | Status Code: UNAUTHENTICATED | Application Code: MISSING_TOKEN | Description: none HTTP Code: 429 | Status Code: RESOURCE_EXHAUSTED | Application Code: QUOTA_LIMIT_REACHED | Description: none ``` ### Examples ### Example of a `data` and `quota` return value @description: ```javascript import { seoKeywordSuggestions } from "@wix/marketing/service-plugins"; seoKeywordSuggestions.provideHandlers({ listSuggestedKeywords: async (payload) => { const { request, metadata } = payload; // Use the `request` and `metadata` received from Wix and // apply custom logic. return { // Return your response exactly as documented to integrate with Wix. // Return value example: data: [ { keyword: "ice cream", volume: 550000, difficulty: 100, latestTrends: [ 0.3, 0.2, 0.24, 0.16, 0.2, 0.2, 0.44, 0.36, 0.36, 0.36, 0.24, 0.2, ], searcherIntent: ["TRANSACTIONAL"], }, { keyword: "ice cream near me", volume: 1500000, difficulty: 83, latestTrends: [ 0.66, 0.44, 0.3, 0.3, 0.3, 0.3, 0.54, 0.66, 0.81, 1.0, 1.0, 0.66, ], searcherIntent: ["TRANSACTIONAL"], }, { keyword: "little debbie ice cream", volume: 110000, difficulty: 50, latestTrends: [ 0.0, 0.06, 0.16, 0.07, 0.66, 1.0, 0.16, 0.11, 0.09, 0.07, 0.09, 0.04, ], searcherIntent: ["INFORMATIONAL"], }, { keyword: "ice cream cake strain", volume: 74000, difficulty: 43, latestTrends: [ 1.0, 1.0, 1.0, 0.81, 0.81, 0.66, 0.81, 0.81, 0.66, 0.66, 0.66, 0.66, ], searcherIntent: ["INFORMATIONAL"], }, { keyword: "ice cream places near me", volume: 74000, difficulty: 61, latestTrends: [ 0.44, 0.3, 0.13, 0.16, 0.2, 0.3, 0.36, 0.44, 1.0, 0.66, 0.66, 0.44, ], searcherIntent: ["TRANSACTIONAL"], }, { keyword: "jeni's ice cream", volume: 74000, difficulty: 70, latestTrends: [ 0.67, 0.54, 0.54, 0.54, 0.54, 0.54, 0.67, 0.67, 0.81, 1.0, 0.16, 0.16, ], searcherIntent: ["NAVIGATIONAL"], }, { keyword: "jenis ice cream", volume: 74000, difficulty: 70, latestTrends: [ 0.36, 0.55, 0.45, 0.67, 0.55, 0.45, 0.82, 0.45, 0.67, 0.67, 1.0, 0.82, ], searcherIntent: ["NAVIGATIONAL"], }, { keyword: "rolled ice cream", volume: 74000, difficulty: 49, latestTrends: [ 0.54, 0.54, 0.44, 0.44, 0.54, 0.44, 0.54, 0.54, 0.67, 0.67, 0.81, 0.81, ], searcherIntent: ["INFORMATIONAL"], }, { keyword: "ice cream cake", volume: 60500, difficulty: 71, latestTrends: [ 0.66, 0.54, 0.54, 0.54, 0.66, 0.54, 0.66, 0.66, 0.81, 0.81, 1.0, 0.81, ], searcherIntent: ["INFORMATIONAL"], }, { keyword: "ice cream shop", volume: 60500, difficulty: 48, latestTrends: [ 0.24, 0.24, 0.16, 0.16, 0.3, 0.3, 0.44, 0.24, 0.3, 1.0, 0.16, 0.66, ], searcherIntent: ["COMMERCIAL"], }, { keyword: "museum of ice cream", volume: 60500, difficulty: 80, latestTrends: [ 0.66, 0.54, 0.54, 0.54, 0.66, 0.66, 1.0, 0.66, 0.54, 1.0, 0.66, 0.66, ], searcherIntent: ["NAVIGATIONAL"], }, ], quota: { endDate: "2022-11-05T07:04:35Z", limit: 10, isPaidPlan: false, paidPlan: false, remaining: 9, startDate: "2022-11-04T07:04:35Z", }, }; }, }); ``` ### listSuggestedKeywords (self-hosted) Self-hosted SDK calls require you to [create a client](https://dev.wix.com/docs/sdk/articles/work-with-the-sdk/about-the-wix-client.md). ```javascript import { createClient } from '@wix/sdk'; import { seoKeywordSuggestions } from '@wix/marketing/service-plugins'; // Import the auth strategy for the relevant access type // Import the relevant host module if needed const myWixClient = createClient ({ modules: { seoKeywordSuggestions }, // Include the auth strategy and host as relevant }); async function listSuggestedKeywords(request,metadata) { const response = await myWixClient.seoKeywordSuggestions.listSuggestedKeywords(request,metadata); }; ``` ---