About the Page Optimization API

The Page Optimization API generates AI-powered, whole-page SEO suggestions for a page of a Wix site: a rewritten title tag, description tag, headings, and body text. Each suggestion is a before/after pair against the page's current content, aimed at the page's focus keyword.

With the Page Optimization API, you can:

• Start an optimization job for a site page or for the site's homepage.
• Poll for the job's status and retrieve the finished suggestion set.
• Show site owners what to change on the page, text by text, and apply the changes they accept.

How optimization works

Generation is asynchronous. Trigger Page Optimization or Trigger Home Page Optimization starts a generation job and returns a predictionId. Poll Get Page Optimization Results until status is COMPLETED. Generation typically takes under 2 minutes.

The job reads the page from the site's latest saved revision, so unpublished changes are included and the site doesn't need to be published. To analyze the page, a temporary preview deployment of that saved revision is created on the site and removed automatically after 30 minutes. The site's editor content and live version are never modified.

Optimization targets the page's focus keyword, which is read from the page's SEO settings. Set it before triggering, for example with the Item SEO Tags API. A page without a focus keyword can't be optimized.

Before you begin

It's important to note the following points before starting to code:

• The page must have a focus keyword set in its SEO settings. Otherwise the trigger fails with FOCUS_KEYWORD_NOT_SET.
• Only Wix-rendered sites are supported. Headless projects fail with SITE_NOT_SUPPORTED.
• The trigger methods must be called with a Wix user identity, for example an app acting on behalf of a signed-in site owner. The page analysis runs as the user, so calls made with an API key fail. Get Page Optimization Results accepts API keys.
• Suggestions are stored per page. A later trigger for the same page replaces the previous suggestion set, and a predictionId can be looked up for 2 hours after its trigger. Look up by pageId to get the page's latest suggestions at any time.
• Triggering is idempotent per page. While a job for the page is in progress, triggering again returns the same predictionId, unless the page's focus keyword changed since the job started, which fails with SUGGESTIONS_ALREADY_IN_PROGRESS.
• Each method is limited to 2 requests per second per calling user, and each call has a time budget of 60 seconds. Calls over the rate limit are rejected, so retry them after a short delay.
• Suggestions are generated by AI. Triggering the same page twice may produce different suggestions.

Use cases

• Optimize a page for its focus keyword
• Optimize the homepage

Terminology

• Focus keyword: The search term a page targets, set in the page's SEO settings. Suggestions are written to rank the page for it.
• Generation job: One run of the AI optimization for a page, identified by its predictionId. A job is IN_PROGRESS, COMPLETED, or FAILED.
• Text suggestion: A before/after pair. before is the page's current text and after the suggested replacement. before is empty when the page has no text in that slot, such as a missing meta description.
• Title tag and description tag: The page's <title> element and meta description, shown in search results.
• Body text: The page's paragraph and section texts. Up to 100 of them get a suggested rewrite.