Go Headless

Build Apps

Client

API Preview

Develop Websites

REST

Velo

GraphQL (Alpha)

# About the SEO Keyword Suggestions SPI

<blockquote class="important">

**Important**: To test an app with the SEO Keyword Suggestions SPI, please [contact us](fallback::https://devforum.wix.com/kb/en/contact). Our team can add the app to the SEO Setup Checklist flow for testing.

</blockquote>

As a provider of SEO keyword research tools, you can integrate with Wix to enable Wix users to optimize their SEO strategy.

Using the SEO Keyword Suggestions SPI, 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.

## How to become an SEO keyword suggestion provider

To become an SEO keyword suggestion provider,
[add the **Seo Keywords Suggestions** extension](fallback::https://dev.wix.com/docs/rest/articles/getting-started/service-provider-interface#configure-an-extension-in-the-development-center)
in your app's configuration in Wix Developers Center.

Provide the necessary configuration for your app:

| Name                    | Type          | Description                                                                                                                                                                                           |
| ----------------------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `baseUri`               | string        | **Required.** Base URL of your SEO implementation. Wix sends API requests to endpoints implemented using this URL.                                                                                                  |
| `upgradeUrl`            | string        | 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.                                         |
| `supportedCountryCodes` | array<string> | **Required.** List of countries you support for SEO analysis. 2-letter country code in [ISO-3166 alpha-2](fallback::https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements) format. |
| `quotaEnabled`          | boolean       | Whether there is a quota limit in the service. When set to true, include the quota object in responses.                                                                                               |
| `landingPageUrl`        | string        | **Required.** Your website's landing page.                                                                                                                                                            |

## 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.



# Sample Flows
This article shares some use cases your app could support, as well as a sample flow that could support each use case. You're certainly not limited to these use cases, but they can be a helpful jumping off point as you plan your app's implementation.



## SEO List Suggested Keywords Flow

A Wix user wishes to determine the strongest SEO keywords for their site. When the `quotaEnabled` parameter is set to `true` in the configuration, you return a quota object in addition to the data object.

1. The Wix user provides a keyword to Wix to check its SEO strength.

2. Wix sends a [List Suggested Keywords](fallback::https://dev.wix.com/api/rest/marketing/seo-keyword-suggestions-spi/list-suggested-keywords) request to your app using the configured `baseUri`. 

    ```json
    {
        "keyword": "pizza",
        "countryCode": "US"
    }
    ```

3. Your app sends a response. 

   Wix expects an object containing either a 4xx HTTP status code (and some errors) or a 200 HTTP status code and the List Suggested Keywords response.

You can see an example of the response in the [List Suggested Keywords](fallback::https://dev.wix.com/api/rest/marketing/seo-keyword-suggestions-spi/list-suggested-keywords) code example. 

## Get Quota Flow

When a Wix user initially opens the SEO page in the Dashboard, Wix requests information about the current quota plan.

1. The Wix user opens the SEO page in the Dashboard.

2. Wix sends a [Get Quota](fallback::https://dev.wix.com/api/rest/marketing/seo-keyword-suggestions-spi/get-quota) request to your app using the configured `baseUri`. No parameters are sent.

3. Your app sends a response. 

   Wix expects an object containing either a 4xx HTTP status code (and some errors) or a 200 HTTP status code and the Get Quota response.

You can see an example of the response in the [Get Quota](fallback::https://dev.wix.com/api/rest/marketing/seo-keyword-suggestions-spi/get-quota) code example. 


value

BoolValue

StringValue

nanos

seconds

Timestamp

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: OrderCanceledEvent, context: Context) {
...
}
```

3 capital letters string representing a currency according to ISO-4217

currency

The identification type and identity data

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

languages

A unique identifier for each request. Can be used for logging / troubleshooting

requestId

Context

identityType

IdentificationData

IdentityType

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

GetQuotaRequest

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

GetQuotaResponse

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

ListSuggestedKeywordsRequest

data

ListSuggestedKeywordsResponse

*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

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

paidPlan

*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

Quota

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

SeoKeywordsSuggestionsSPIConfig

*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`

latestTrends

User's reason for searching for the keyword (optional):
- `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.

searcherIntent

*Required**. Average number of searches per month for the keyword.

volume

SuggestedKeywords

This endpoint 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 endpoint when a Wix user requests data about a keyword via the SEO page of the Dashboard.


> You cannot try out this endpoint because it has to be implemented by an app and can
> have an arbitrary URL. So please ignore the **Authorization** and **POST** sections below
> as well as the **Try It Out** button.

OutOfQuotaError

MissingTokenError

List suggested keywords

ListSuggestedKeywords

This endpoint 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 endpoint when a Wix user opens the SEO page of the Dashboard.

> You cannot try out this endpoint because it has to be implemented by an app and can
> have an arbitrary URL. So please ignore the **Authorization** and **POST** sections below
> as well as the **Try It Out** button.