About the SEO Patterns API

The SEO Patterns API allows you to read and write a Wix site's SEO patterns: the templates that generate SEO tags for every item of a page type. A pattern is written once for a page type, such as every store product or every blog post, and its tags contain variables, such as {{product.name}}, that are filled in with each item's own values when its page renders. Changing one pattern therefore changes the tags of every page of that type that doesn't have SEO tags set for the item itself.

With the SEO Patterns API, you can:

• Retrieve the pattern in effect for a page type, along with the Wix default it started from.
• Retrieve the variables a page type offers, so you know what a pattern for it may reference.
• Create a pattern for a page type that's still on its Wix default.
• Change a pattern, or reset a page type back to its Wix default.
• Retrieve the patterns a site has stored.

How patterns fit with a site's other SEO tags

Wix builds the tags a page renders with by combining several sources, where a later source takes precedence:

1. The site's tags, which apply to every page. See the Site SEO Tags API.
2. The pattern Wix provides for the page type.
3. The pattern the Wix user customized for that page type, which this API manages.
4. The tags of the page that displays the item.
5. The tags set for the item itself. See the Item SEO Tags API.

So a pattern decides an item's tags only where the item has none of its own. To see the tags a specific item is expected to render with, and which source each one came from, read resolvedTags on that item with the Item SEO Tags API.

A pattern is stored where the live site reads it, so a change takes effect without a site publish.

Concurrent changes

A pattern has no revision, and a Wix user editing SEO patterns in the dashboard writes to the same patterns as this API. If both change a pattern at once, whichever lands second overwrites the other, with no conflict error. When a Wix user may be editing at the same time, retrieve the pattern immediately before writing it.

Patterns for a single dynamic page

Pages built from a Wix Data collection are the one case where a page type holds more than one pattern: each such page can have a pattern of its own. To address one of them, specify its ID in pageId, with a page type of WIX_DATA_PAGE_ITEM.

Every other page type has a single pattern for the whole type, and specifying a page ID for one of those fails rather than being ignored. collectionName isn't supported yet, so address a dynamic page by its ID instead.

Page types

Send one of the known page type names. An unknown name fails with UNSUPPORTED_PAGE_TYPE. That error message lists every name the method accepts.

Send STATIC_PAGE for Editor pages, never STATIC_PAGE_V2.

App pages added with a site page extension don't have their own page type. They use the STATIC_PAGE pattern, the same as Home or About.

A page type provided by a Wix business solution is only available when that business solution is installed on the site. Get, List SEO Pattern Variables, and Create fail with PAGE_TYPE_NOT_ON_SITE when it isn't.

These are the page types sites commonly customize:

pageType	What it is
STATIC_PAGE	Pages created in the Editor, such as Home or About
WIX_DATA_PAGE_ITEM	A page built from a Wix Data collection. Specify pageId to address one page
BLOG_POST	Blog posts
BLOG_CATEGORY	Blog categories
BLOG_TAGS	Blog tags
BLOG_ARCHIVE	Blog archive pages
STORES_PRODUCT	Store products
STORES_CATEGORY	Store categories
STORES_SUB_CATEGORY	Store subcategories
BOOKINGS_SERVICE	Bookings services
EVENTS_PAGE	Event pages
FORUM_POST	Forum posts
FORUM_CATEGORY	Forum categories
GROUPS_PAGE	Group pages
GROUPS_POST	Group posts
MEMBERS_AREA_PROFILE	Member profiles
MEMBERS_AREA_AUTHOR_PROFILE	Author profiles in the members area
PORTFOLIO_COLLECTIONS	Portfolio collections
PORTFOLIO_PROJECTS	Portfolio projects
PRICING_PLANS	Pricing plans
PRO_GALLERY_ITEM	Pro Gallery items
CHALLENGES_PAGE	Online programs
RESTAURANTS_MENU_PAGE	Restaurant menus
RESTAURANTS_MENU_ITEM	Restaurant menu items
TABLE_RESERVATIONS_EXPERIENCE	Table reservation experiences

The API also accepts names for some page components and platform pages, such as SEARCH_PAGE or BREADCRUMBS_COMPONENT. Those names appear in that error message. They aren't the page types a site customizes in SEO settings.

Page types aren't the same set as the item types of the Item SEO Tags API. A page type can support a pattern without supporting tags set per item, and the other way round.

Before you begin

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

• A page type always has a pattern in effect, and the Wix default is returned alongside it every time. Get SEO Pattern returns pattern, the pattern in effect, together with defaultPattern, the Wix default for that page type. Both are present on every call, including for a page type the site has customized. source says which of the two is in effect: PATTERN_SOURCE_USER when the page type has a pattern of its own, PATTERN_SOURCE_DEFAULT when it doesn't. So to see what Reset SEO Pattern To Default would restore, read defaultPattern. There's no need to reset the pattern to find out.
• Create and Set aren't interchangeable. Create SEO Pattern works only on a page type that has no pattern of its own. Set SEO Pattern changes a pattern that already exists.
• A pattern may reference only the variables its page type offers, and variable names differ by page type. A store product offers {{product.name}}, for example, while a page built from a Wix Data collection offers {{wix-data-page-item.main-collection-primary-field}}. Call List SEO Pattern Variables for each page type rather than reusing a name.
• Setting pattern replaces the page type's tag templates in full. Retrieve the pattern first and send back the complete set you want it to have.
• For a page type provided by a Wix business solution, such as BLOG_POST or STORES_PRODUCT, that business solution must be installed on the site. Get SEO Pattern, List SEO Pattern Variables, and Create SEO Pattern fail when it isn't. Set SEO Pattern and Reset SEO Pattern To Default don't apply that check, so a pattern stored before a business solution was uninstalled stays readable and editable.

Use cases

• Apply a title convention to a whole page type
• Audit which page types a site has customized
• Return a page type to the Wix default

Terminology

• Pattern: A template of SEO tags defined for one page type, whose variables are filled in per item.
• Page type: A known name for a category of page that shares a pattern, such as STORES_PRODUCT or BLOG_POST. See Page types.
• Variable: A placeholder such as {{product.name}}, written in double braces, that's replaced with an item's own value when its page renders. Each page type offers its own set.
• Wix default: The pattern Wix supplies for a page type, which applies until a site defines one of its own.