Go Headless

Build Apps

Client

API Preview

Ricos

Develop Websites

REST

Velo

GraphQL (Alpha)

SeoKeywordSuggestions

Seo Keyword Suggestions 1 0 0

MissingTokenWixError

OutOfQuotaWixError

payload

GetQuotaEnvelope

This method requests information about remaining quota in the plan.
A Wix user can purchase a paid plan from your site or utilize a free plan
if you offer one.
You provide information about the current plan including how many searches remain
out of the total in the plan, the dates of the plan, and whether the user currently has a paid plan.

Wix calls this method when a Wix user opens the SEO page of the Dashboard.

import { seoKeywordSuggestions } from '@wix/marketing/service-plugins';

seoKeywordSuggestions.provideHandlers({

  getQuota: 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:
        quota: {
          endDate: "2024-07-05T07:04:35Z",
          limit: 10,
          paidPlan: false,
          remaining: 9,
          startDate: "2024-07-04T07:04:35Z"
        }
      }
    }
});


Example of a `quota` return value @description:

getQuota

GetQuotaResponse

OutOfQuotaError

MissingTokenError

ListSuggestedKeywordsEnvelope

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.

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"
        }
      }
    }
});


Example of a `data` and `quota` return value @description:

listSuggestedKeywords

ListSuggestedKeywordsResponse

# About the SEO Keyword Suggestions Service Plugin

As an SEO Keyword Suggestions provider, you can integrate with Wix to enable Wix users to optimize their SEO strategy.

The integration is done via an app in the Wix App Market and by implementing the SEO Keyword Suggestions [service plugin](https://dev.wix.com/docs/build-apps/develop-your-app/extensions/backend-extensions/service-plugins/about-service-plugin-extensions). After the app is installed on a site, Wix triggers a call to your service when specific actions are taken on the site. Refer to each function's description for details about those actions.

Using the service plugin, you can design your app to:

+ Enable Wix users to check the SEO strength of a potential keyword.
+ Suggest similar keywords to compare SEO strength.
+ Provide analysis about the suggested keywords based on search volume and ranking difficulty.
+ Update Wix users about remaining credit in their plan.

## Terminology
+ **Suggested keywords:** Keywords suggested by your app to compare SEO strength of potential keywords and enable optimization of SEO strategy.
+ **Quota:** Details of the plan such as credit remaining in terms of number of searches left, total available searches, and start and end dates of the quota cycle.  

## Get started

Follow these steps to begin implementing your service plugin.

### Choose a framework

You can implement this service plugin with the following [frameworks](https://dev.wix.com/docs/build-apps/get-started/overview/wix-s-development-frameworks):

+ **Wix CLI:** Learn how to [implement a service plugin with the CLI and the SDK](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/wix-cli/supported-extensions/backend-extensions/service-plugins/add-service-plugin-extensions-with-the-cli).
+ **Self-hosted:** Learn how to [implement a self-hosted service plugin with the SDK and the Wix Dev Center](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/self-hosting/supported-extensions/backend-extensions/add-self-hosted-service-plugin-extensions-with-the-sdk).

### Configure your service plugin

To configure and customize your plugin, you need to provide important information in the service plugin configuration file. You can [configure your plugin in the Wix Dev Center](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/self-hosting/supported-extensions/backend-extensions/add-self-hosted-service-plugin-extensions-with-the-sdk#step-1--add-a-service-plugin-extension-to-your-app). For details, see [SEO Keyword Suggestions Extension Configuration](https://dev.wix.com/docs/sdk/backend-modules/marketing/service-plugins/seo-keyword-suggestions/extension-config).

### Define handler functions

Use [`seoKeywordSuggestions.provideHandlers()`](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/self-hosting/supported-extensions/backend-extensions/add-self-hosted-service-plugin-extensions-with-the-sdk#step-4--define-handler-functions) to define the following handler functions that implement your custom business logic. Make sure you define all required functions.

| Function                    | Required       |
|-----------------------------|----------------|
| [`getQuota()`](https://dev.wix.com/docs/sdk/backend-modules/marketing/service-plugins/seo-keyword-suggestions/get-quota)    | Yes            |
| [`listSuggestedKeywords()`](https://dev.wix.com/docs/sdk/backend-modules/marketing/service-plugins/seo-keyword-suggestions/list-suggested-keywords)    | Yes            |

## Code examples

Below is an example for implementing the SEO Keyword Suggestions service plugin in your code.

### CLI: Basic code structure

This is the basic code structure for implementing the SEO Keyword Suggestions service plugin with the Wix CLI:

```js
import { seoKeywordSuggestions } from '@wix/marketing/service-plugins'

seoKeywordSuggestions.provideHandlers({
  getQuota: async (payload) => {

    const { request, metadata } = payload;

    // Add your logic here

  },
  listSuggestedKeywords: async (payload) => {

    const { request, metadata } = payload;

    // Add your logic here

  }  
});
  
```

### Self-hosted: Basic code structure

This is the basic code structure for implementing a self-hosted SEO Keyword Suggestions service plugin:

```js
import { createClient } from '@wix/sdk';
import { seoKeywordSuggestions } from '@wix/marketing/service-plugins'

const wixClient = createClient({
  auth: {
    appId: <YOUR_APP_ID>,
    publicKey: <YOUR_APP_PUBLIC_KEY>
  },
  modules: { seoKeywordSuggestions }
});

wixClient.seoKeywordSuggestions.provideHandlers({
  getQuota: async (payload) => {

    const { request, metadata } = payload;

    // Add your logic here

  },
  listSuggestedKeywords: async (payload) => {

    const { request, metadata } = payload;

    // Add your logic here

  }  
});

// Implement a router to process all requests
express.post('/plugins-and-webhooks/*', (req, res) => {
  wixClient.process(req);
});
  
```

## See also

+ [About Service Plugin Extensions](https://dev.wix.com/docs/build-apps/develop-your-app/extensions/backend-extensions/service-plugins/about-service-plugin-extensions)
+ [Add a Service Plugin Extension With the CLI](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/wix-cli/supported-extensions/backend-extensions/service-plugins/add-service-plugin-extensions-with-the-cli)
+ [Add a Self-hosted Service Plugin With the SDK](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/self-hosting/supported-extensions/backend-extensions/add-self-hosted-service-plugin-extensions-with-the-sdk)


marketing_seo-keyword-suggestions

To configure and customize your service plugin, you need to provide important details in the `plugin.json` configuration file.

SEO Keyword Suggestions Extension Config

Extension Config

SeoKeywordsSuggestionsSPIConfig

Context

[ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) 3-letter currency code.

currency

string

An object that describes the identity that triggered this request.

identity

IdentificationData

instanceId

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"`.

languages

A unique identifier of the request. You may print this ID to your logs to help with future debugging and easier correlation with Wix's logs.

requestId

metadata

request

GetQuotaRequest

*Required if `quotaEnabled` is `true` in the configuration**. Information about remaining credit in the plan.

quota

Quota

ID of a site visitor that has not logged in to the site.

anonymousVisitorId

appId

ID of a site visitor that has logged in to the site.

memberId

ID of a Wix user (site owner, contributor, etc.).

wixUserId

identityType

IdentityType

ListSuggestedKeywordsRequest

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.

countryCode

keyword

data

*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

endDate

*Required**. Total number of searches available in the current quota cycle.

limit

number

*Required**. Whether the user currently has a paid plan.
If `false`, the user is offered an upgrade using the `upgradeUrl` from the configuration.

paidPlan

boolean

*Required**. Number of searches left until the end of the current quota cycle.

remaining

*Required**. Start date and time of the current quota cycle as UTC datetime in `YYYY-MM-DDThh:mm[:ss][.sss]Z` format.

startDate

Users searched for specific brands or services, usually with an intent to purchase.

Users searched for information about a topic.

Users searched for a specific page, site, or physical location.

Users searched to perform a transaction, for example a purchase.

SearcherIntent

Base URL of your SEO implementation. Wix sends API requests to endpoints implemented using this URL.

baseUri

landingPageUrl

Whether there is a quota limit in the service. When set to true, include the quota object in responses.

quotaEnabled

List of countries you support for SEO 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.

supportedCountryCodes

URL of the page where users can purchase a paid plan. Wix offers a link to this page when you respond with a value of `false` in quota's `paidPlan` property.

upgradeUrl

SuggestedKeywords

*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. <br>
Min: `1` <br>
Max: `100`

difficulty

*Required**. Keyword suggestions offered by the SEO tool.

*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. <br>
Min: `0.0` <br>
Max: `1.0`

listSuggestedKeywords( )