About the Wix Site Search API

Developer Preview
APIs in Developer Preview are subject to change and are not intended for use in production.
Send us your suggestions for improving this API. Your feedback is valuable to us.

 

The Wix Site Search API allows you to search and retrieve specific types of documents from a site. The API returns results in the form of site document objects that match your search criteria.

For example, you can use the API to find upcoming events by searching the EVENTS document type.

Supported document types

The Search API supports a variety of document types, each with its own schema that defines how data the documents can be filtered, sorted, and searched:

You can also perform aggregations on the search results. For example, you can aggregate search results of the STORES_PRODUCTS document type to find the lowest price for each brand in your store.

Learn more about the Wix Site Search feature.

Before you begin

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

  • The site owner must install the Wix Site Search app.
  • Document types are not the same as Wix app collections. Though they overlap in content, documents are specifically for use by Wix Search.

Use cases

Terminology

  • Document: A document is a structured set of field and value pairs. Each document type corresponds to a specific Wix app on a site and follows a specific Wix Search schema. The following documents are supported:
    • Site pages: All regular and dynamic site pages with SEO indexing enabled. All Wix site pages are indexed by default. Note that custom router pages and some Wix app pages are not currently searchable.
    • Wix app content: Pages whose content is derived from the following schemas for Wix Search: BLOG_POSTS, BOOKINGS_SERVICES, FORUM_CONTENT, EVENTS, STORES_PRODUCT, and PROGALLERY_ITEM.
  • Document type: The specific type of document to search in, as listed in the Supported Document Types section.
  • Aggregation: A search method for grouping data into various categories (facets) and providing summaries for each category. For example, use aggregations to categorize search results by specific price ranges, brand names, or ratings.
Did this help?

Sample Use Cases & Flows

This article presents possible use cases and corresponding sample flows that your app can support. It provides a useful starting point as you plan your app's implementation.

Search for jazz events in San Francisco

If you're developing a tickets app, and you want to search for jazz events in San Francisco, do the following:

  1. Search the EVENTS document type for 'jazz' in the expression field, and filter by location for San Francisco.

    Copy
    { "search": { "filter": { "location": "san francisco" } "aggregations": [], "sort": [], "search": { "fields": [], "expression": "jazz" }, "paging": {} }, "documentType": "EVENTS" }
  2. Retrieve all the jazz events in San Francisco.

Find the lowest price for products in stock and out of stock

If you're developing a wholesale app, you can perform an aggregation on a site with store products to count how many products are in stock vs out of stock, and what is the lowest price for the in-stock products vs. the out of stock products.

To do this, you need to perform a nested aggregation:

  1. First perform a value aggregation with "fieldPath": "inStock" to get the products that are in stock and out of stock (since this field is a boolean).

  2. Then add a scalar aggregation with "fieldPath": "discountedPriceNumeric", "type": "MIN" to get the minimum price for the in-stock and out-of-stock products returned in the first aggregation.

    Sample request:

    Copy
    { "search": { "aggregations": [ { "name": "Lowest price for products in stock and out of stock.", "type": "NESTED", "nested": { "nestedAggregations": [ { "name": "in-stock", "type": "VALUE", "fieldPath": "inStock", "value": {} }, { "name": "min-price", "type": "SCALAR", "fieldPath": "discountedPriceNumeric", "scalar": { "type": "MIN" } } ] } } ] }, "documentType": "STORES_PRODUCTS" }

    Sample response:

    Copy
    "aggregationData": { "results": [ { "name": "Lowest price for products in stock and out of stock.", "type": "NESTED", "nested": { "results": [ { "results": { "in-stock": { "value": { "value": "true", "count": 3 } }, "min-price": { "scalar": { "value": 899 } } } }, { "results": { "in-stock": { "value": { "value": "false", "count": 2 } }, "min-price": { "scalar": { "value": 500 } } } } ] } } ] },

In our example, the lowest price among the 3 in-stock products is $899, and the lowest price among the 2 out-of-stock products is $500.

Did this help?

POST

Search


Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Retrieves a list of site documents that match the provided search query and optionally performs aggregations on the data queried.

The Search API supports the document types listed in the Introduction, each with its own schema. These schemas define the fields available for filtering, sorting, and free-text searching.

To learn more about working with the search query, see API Query Language and Sorting and Paging.

Permissions
Read Site Documents
Learn more about app permissions.
Endpoint
POST
https://www.wixapis.com/_api/site-search/v1/search

Body Params
searchSearchRequired

Search query and aggregation information.


documentTypestringRequired

Document type to search in.


languagestringformat LANGUAGE

Language to search in.

Response Object
siteDocumentItemsArray <SiteDocument>

Documents matching the search query.


aggregationDataAggregationData

Aggregated data.


pagingOffsetMetadataPagingOffsetMetadata

Paging metadata.

Request
cURL
curl -X POST \ 'https://www.wixapis.com/_api/site-search/v1/search' \ -H 'Content-type: application/json' \ -H 'Authorization: <AUTH>' \ -d '{ "documentType": "STORES_PRODUCTS", "search": { "aggregations": [], "sort": [], "search": { "fields": [], "expression": "game" }, "paging": { "limit": 3 } } }'
Response
JSON
{ "siteDocumentItems": [ { "id": "5818aa78-849d-237c-6639-d2af6ba0d8f1", "data": { "_score": 149.54732, "_updated": "2024-04-14T13:22:47.783Z", "collections": ["Games"], "currency": "EUR", "description": "I&#39;m a product description. This is a great place to &#34;sell&#34; your product and grab buyers&#39; attention. Describe your product clearly and concisely. Use unique keywords. Write your own description instead of using manufacturers&#39; copy.", "discountedPrice": "€39.99", "discountedPriceNumeric": 39.99, "documentImage": { "height": 9080, "name": "c837a6_0fc432ddbaa847358c7d2598829b08e8~mv2.jpg", "width": 9156 }, "documentType": "public/stores/products", "id": "5818aa78-849d-237c-6639-d2af6ba0d8f1", "inStock": true, "infoSections": [ "Product Info", "<p>I'm a product detail. I'm a great place to add more information about your product such as sizing, material, care and cleaning instructions. This is also a great space to write what makes this product special and how your customers can benefit from this item. Buyers like to know what they’re getting before they purchase, so give them as much information as possible so they can buy with confidence and certainty.</p>\n", "Return and Refund Policy", "<p>I’m a Return and Refund policy. I’m a great place to let your customers know what to do in case they are dissatisfied with their purchase. Having a straightforward refund or exchange policy is a great way to build trust and reassure your customers that they can buy with confidence.</p>\n", "Shipping Info", "<p>I'm a shipping policy. I'm a great place to add more information about your shipping methods, packaging and cost. Providing straightforward information about your shipping policy is a great way to build trust and reassure your customers that they can buy from you with confidence.</p>\n" ], "onSale": false, "sku": "0026", "title": "Cyber Kid Infinite", "url": "/product-page/cyber-kid-infinite" } }, { "id": "b35a1597-da0f-9382-3162-e4ea5d4048fd", "data": { "_score": 149.54732, "_updated": "2024-04-14T13:22:47.783Z", "collections": ["Games"], "currency": "EUR", "description": "I&#39;m a product description. This is a great place to &#34;sell&#34; your product and grab buyers&#39; attention. Describe your product clearly and concisely. Use unique keywords. Write your own description instead of using manufacturers&#39; copy.", "discountedPrice": "€35.99", "discountedPriceNumeric": 35.99, "documentImage": { "height": 9080, "name": "c837a6_1fced547ddff4698a820b04cbf4e7622~mv2.jpg", "width": 9156 }, "documentType": "public/stores/products", "id": "b35a1597-da0f-9382-3162-e4ea5d4048fd", "inStock": true, "infoSections": [ "Product Info", "<p>I'm a product detail. I'm a great place to add more information about your product such as sizing, material, care and cleaning instructions. This is also a great space to write what makes this product special and how your customers can benefit from this item. Buyers like to know what they’re getting before they purchase, so give them as much information as possible so they can buy with confidence and certainty.</p>\n", "Return and Refund Policy", "<p>I’m a Return and Refund policy. I’m a great place to let your customers know what to do in case they are dissatisfied with their purchase. Having a straightforward refund or exchange policy is a great way to build trust and reassure your customers that they can buy with confidence.</p>\n", "Shipping Info", "<p>I'm a shipping policy. I'm a great place to add more information about your shipping methods, packaging and cost. Providing straightforward information about your shipping policy is a great way to build trust and reassure your customers that they can buy from you with confidence.</p>\n" ], "onSale": true, "sku": "0024", "title": "Ice Dome: Exile", "url": "/product-page/ice-dome-exile" } }, { "id": "f2ad9533-30cd-f145-dee4-3f50f4fe84f3", "data": { "_highlights": { "title": ["Mach <mark>Gaming</mark> Chair"] }, "_score": 149.27646, "_updated": "2024-04-14T13:22:47.815Z", "collections": ["Accessories", "On Sale", "Best Sellers"], "currency": "EUR", "description": "I&#39;m a product description. This is a great place to &#34;sell&#34; your product and grab buyers&#39; attention. Describe your product clearly and concisely. Use unique keywords. Write your own description instead of using manufacturers&#39; copy.", "discountedPrice": "€116.99", "discountedPriceNumeric": 116.99, "documentImage": { "height": 4083, "name": "c837a6_85410586580e46ce94659e34046a48c8~mv2.jpg", "width": 4842 }, "documentType": "public/stores/products", "id": "f2ad9533-30cd-f145-dee4-3f50f4fe84f3", "inStock": true, "infoSections": [ "Product Info", "<p>I'm a product detail. I'm a great place to add more information about your product such as sizing, material, care and cleaning instructions. This is also a great space to write what makes this product special and how your customers can benefit from this item. Buyers like to know what they’re getting before they purchase, so give them as much information as possible so they can buy with confidence and certainty.</p>\n", "Return and Refund Policy", "<p>I’m a Return and Refund policy. I’m a great place to let your customers know what to do in case they are dissatisfied with their purchase. Having a straightforward refund or exchange policy is a great way to build trust and reassure your customers that they can buy with confidence.</p>\n", "Shipping Info", "<p>I'm a shipping policy. I'm a great place to add more information about your shipping methods, packaging and cost. Providing straightforward information about your shipping policy is a great way to build trust and reassure your customers that they can buy from you with confidence.</p>\n" ], "onSale": true, "sku": "0006", "title": "Mach Gaming Chair", "url": "/product-page/mach-gaming-chair" } } ], "aggregationData": null, "pagingOffsetMetadata": { "count": 3, "offset": 0, "total": 10, "tooManyToCount": false, "hasNext": true } }
Did this help?