> Portal Navigation: > > - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version. > - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages). > - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`). > - Top-level index of all portals: https://dev.wix.com/docs/llms.txt > - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt # QueryCategories # Package: blog # Namespace: CategoryService # Method link: https://dev.wix.com/docs/api-reference/business-solutions/blog/category/query-categories.md ## Permission Scopes: Read Blog : SCOPE.DC-BLOG.READ-BLOGS ## Introduction Retrieves a list of up to 100 categories, given the provided paging, filtering, and sorting. Query Categories runs with these defaults, which you can override. - `displayPosition` is sorted in `DESC` order. - `paging.limit` is `50`. - `paging.offset` is `0`. To learn about working with _Query_ endpoints, see [API Query Language](https://dev.wix.com/api/rest/getting-started/api-query-language), [Sorting and Paging](https://dev.wix.com/api/rest/getting-started/sorting-and-paging), and [Field Projection](https://dev.wix.com/api/rest/getting-started/field-projection). --- ## REST API ### Schema ``` Method: queryCategories Description: Retrieves a list of up to 100 categories, given the provided paging, filtering, and sorting. Query Categories runs with these defaults, which you can override. - `displayPosition` is sorted in `DESC` order. - `paging.limit` is `50`. - `paging.offset` is `0`. To learn about working with _Query_ endpoints, see [API Query Language](https://dev.wix.com/api/rest/getting-started/api-query-language), [Sorting and Paging](https://dev.wix.com/api/rest/getting-started/sorting-and-paging), and [Field Projection](https://dev.wix.com/api/rest/getting-started/field-projection). URL: https://www.wixapis.com/blog/v3/categories/query Method: POST Method parameters: param name: fieldsets | type: array | description: List of additional category fields to include in the response. By default only the category’s base fields are returned. Base fields are all category fields that don't appear in the fieldset enum. To retrieve a field, pass the relevant fieldset in the enum in the `fieldsets` array. For example, add the `URL` fieldset to `fieldsets` to retrieve the url field in the response in addition to the category’s base fields. - enum: - UNKNOWN: - URL: Includes category URL. - SEO: Includes SEO data. param name: query | type: PlatformQuery - name: paging | type: Paging | description: Paging options to limit and skip the number of items. - name: limit | type: integer | description: Number of items to load. - name: offset | type: integer | description: Number of items to skip in the current sort order. - name: filter | type: object | description: Filter object in the following format: `"filter" : { "fieldName1": "value1", "fieldName2":{"$operator":"value2"} }` Example of operators: `$eq`, `$ne`, `$lt`, `$lte`, `$gt`, `$gte`, `$in`, `$hasSome`, `$hasAll`, `$startsWith`, `$contains` - name: sort | type: array | description: Sort object in the following format: `[{"fieldName":"sortField1","order":"ASC"},{"fieldName":"sortField2","order":"DESC"}]` - name: fieldName | type: string | description: Name of the field to sort by. - name: order | type: SortOrder | description: Sort order. - enum: ASC, DESC Return type: QueryCategoriesResponse - name: categories | type: array | description: List of categories. - name: id | type: string | description: Category GUID. - name: label | type: string | description: Category label. Displayed in the Category Menu. - name: postCount | type: integer | description: Number of posts in the category. - name: url | type: PageUrl | description: The `url` of the page that lists every post with the specified category. - name: base | type: string | description: The base URL. For premium sites, this is the domain. For free sites, this is the site URL. For example, `mysite.wixsite.com/mysite`. - name: path | type: string | description: The relative path for the page within the site. For example, `/product-page/a-product`. - name: description | type: string | description: Category description. - name: displayPosition | type: integer | description: Position of the category in the [Category Menu](https://support.wix.com/en/article/wix-blog-adding-and-customizing-a-category-menu). Categories are displayed in ascending order. Categories with a position of `-1` appear at the end of the sequence. Default: `-1` - name: translationId | type: string | description: GUID of the category's translations. All translations of a single category share the same `translationId`. - name: language | type: string | description: Category language. 2-or-4-letter language code in [IETF BCP 47 language tag](https://en.wikipedia.org/wiki/IETF_language_tag) format. - name: slug | type: string | description: Part of a category's URL that refers to a specific category. For example, the slug of `https:/example.com/blog/category/famous-cats` is `famous-cats`. - name: seoData | type: SeoSchema | description: SEO data. - name: tags | type: array | description: SEO tag information. - name: type | type: string | description: SEO tag type. Supported values: `title`, `meta`, `script`, `link`. - name: props | type: object | description: A `{"key": "value"}` pair object where each SEO tag property (`"name"`, `"content"`, `"rel"`, `"href"`) contains a value. For example: `{"name": "description", "content": "the description itself"}`. - name: meta | type: object | description: SEO tag metadata. For example, `{"height": 300, "width": 240}`. - name: children | type: string | description: SEO tag inner content. For example, ` inner content `. - name: custom | type: boolean | description: Whether the tag is a [custom tag](https://support.wix.com/en/article/adding-additional-meta-tags-to-your-sites-pages). - name: disabled | type: boolean | description: Whether the tag is disabled. If the tag is disabled, people can't find your page when searching for this phrase in search engines. - name: settings | type: Settings | description: SEO general settings. - name: preventAutoRedirect | type: boolean | description: Whether the [automatical redirect visits](https://support.wix.com/en/article/customizing-your-pages-seo-settings-in-the-seo-panel) from the old URL to the new one is enabled. Default: `false` (automatical redirect is enabled). - name: keywords | type: array | description: User-selected keyword terms for a specific page. - name: term | type: string | description: Keyword value. - name: isMain | type: boolean | description: Whether the keyword is the main focus keyword. - name: origin | type: string | description: The source that added the keyword terms to the SEO settings. - name: coverImage | type: Image | description: Category cover image. - name: id | type: string | description: WixMedia image GUID. - name: url | type: string | description: Image URL. - name: height | type: integer | description: Original image height. - name: width | type: integer | description: Original image width. - name: altText | type: string | description: Image alt text. - name: filename | type: string | description: Image filename. - name: updatedDate | type: string | description: Date and time the Category was last updated. - name: pagingMetadata | type: PagingMetadataV2 | description: Details on the paged set of results returned. - name: count | type: integer | description: Number of items returned in the response. - name: offset | type: integer | description: Offset that was requested. - name: total | type: integer | description: Total number of items that match the query. Returned if offset paging is used and the `tooManyToCount` flag is not set. - name: tooManyToCount | type: boolean | description: Flag that indicates the server failed to calculate the `total` field. - name: cursors | type: Cursors | description: Cursors to navigate through the result pages using `next` and `prev`. Returned if cursor paging is used. - name: next | type: string | description: Cursor pointing to next page in the list of results. - name: prev | type: string | description: Cursor pointing to previous page in the list of results. ``` ### Examples ### QueryCategories ```curl ~~~cURL curl \ 'https://www.wixapis.com/blog/v3/categories/query' \ --data-binary '{ "fieldsets": ["URL"], "filter": { "title": { "$startsWith": "Summer" } } }' \ } -H 'Content-Type: application/json' \ -H 'Authorization: ' ~~~ ``` --- ## JavaScript SDK ### Schema ``` Method: wixClientAdmin.blog.CategoryService.queryCategories(query, options) Description: Retrieves a list of up to 100 categories, given the provided paging, filtering, and sorting. Query Categories runs with these defaults, which you can override. - `displayPosition` is sorted in `DESC` order. - `paging.limit` is `50`. - `paging.offset` is `0`. To learn about working with _Query_ endpoints, see [API Query Language](https://dev.wix.com/api/rest/getting-started/api-query-language), [Sorting and Paging](https://dev.wix.com/api/rest/getting-started/sorting-and-paging), and [Field Projection](https://dev.wix.com/api/rest/getting-started/field-projection). # Note: If the parameter `a.b` is listed under required parameters, `b` is only required if `a` is also present. Required parameters: query Method parameters: param name: options | type: QueryCategoriesOptions none - name: fieldsets | type: array | description: List of additional category fields to include in the response. By default only the category’s base fields are returned. Base fields are all category fields that don't appear in the fieldset enum. To retrieve a field, pass the relevant fieldset in the enum in the `fieldsets` array. For example, add the `URL` fieldset to `fieldsets` to retrieve the url field in the response in addition to the category’s base fields. - enum: - UNKNOWN: - URL: Includes category URL. - SEO: Includes SEO data. param name: query | type: CategoryQuery | required: true - name: paging | type: Paging | description: Paging options to limit and skip the number of items. - name: limit | type: integer | description: Number of items to load. - name: offset | type: integer | description: Number of items to skip in the current sort order. - name: filter | type: object | description: Filter object in the following format: `"filter" : { "fieldName1": "value1", "fieldName2":{"$operator":"value2"} }` Example of operators: `$eq`, `$ne`, `$lt`, `$lte`, `$gt`, `$gte`, `$in`, `$hasSome`, `$hasAll`, `$startsWith`, `$contains` - name: sort | type: array | description: Sort object in the following format: `[{"fieldName":"sortField1","order":"ASC"},{"fieldName":"sortField2","order":"DESC"}]` - name: fieldName | type: string | description: Name of the field to sort by. - name: order | type: SortOrder | description: Sort order. - enum: ASC, DESC Return type: PROMISE - name: categories | type: array | description: List of categories. - name: _id | type: string | description: Category GUID. - name: label | type: string | description: Category label. Displayed in the Category Menu. - name: postCount | type: integer | description: Number of posts in the category. - name: url | type: string | description: The `url` of the page that lists every post with the specified category. - name: description | type: string | description: Category description. - name: displayPosition | type: integer | description: Position of the category in the [Category Menu](https://support.wix.com/en/article/wix-blog-adding-and-customizing-a-category-menu). Categories are displayed in ascending order. Categories with a position of `-1` appear at the end of the sequence. Default: `-1` - name: translationId | type: string | description: GUID of the category's translations. All translations of a single category share the same `translationId`. - name: language | type: string | description: Category language. 2-or-4-letter language code in [IETF BCP 47 language tag](https://en.wikipedia.org/wiki/IETF_language_tag) format. - name: slug | type: string | description: Part of a category's URL that refers to a specific category. For example, the slug of `https:/example.com/blog/category/famous-cats` is `famous-cats`. - name: seoData | type: SeoSchema | description: SEO data. - name: tags | type: array | description: SEO tag information. - name: type | type: string | description: SEO tag type. Supported values: `title`, `meta`, `script`, `link`. - name: props | type: object | description: A `{"key": "value"}` pair object where each SEO tag property (`"name"`, `"content"`, `"rel"`, `"href"`) contains a value. For example: `{"name": "description", "content": "the description itself"}`. - name: meta | type: object | description: SEO tag metadata. For example, `{"height": 300, "width": 240}`. - name: children | type: string | description: SEO tag inner content. For example, ` inner content `. - name: custom | type: boolean | description: Whether the tag is a [custom tag](https://support.wix.com/en/article/adding-additional-meta-tags-to-your-sites-pages). - name: disabled | type: boolean | description: Whether the tag is disabled. If the tag is disabled, people can't find your page when searching for this phrase in search engines. - name: settings | type: Settings | description: SEO general settings. - name: preventAutoRedirect | type: boolean | description: Whether the [automatical redirect visits](https://support.wix.com/en/article/customizing-your-pages-seo-settings-in-the-seo-panel) from the old URL to the new one is enabled. Default: `false` (automatical redirect is enabled). - name: keywords | type: array | description: User-selected keyword terms for a specific page. - name: term | type: string | description: Keyword value. - name: isMain | type: boolean | description: Whether the keyword is the main focus keyword. - name: origin | type: string | description: The source that added the keyword terms to the SEO settings. - name: coverImage | type: string | description: Category cover image. - name: _updatedDate | type: Date | description: Date and time the Category was last updated. - name: pagingMetadata | type: PagingMetadataV2 | description: Details on the paged set of results returned. - name: count | type: integer | description: Number of items returned in the response. - name: offset | type: integer | description: Offset that was requested. - name: total | type: integer | description: Total number of items that match the query. Returned if offset paging is used and the `tooManyToCount` flag is not set. - name: tooManyToCount | type: boolean | description: Flag that indicates the server failed to calculate the `total` field. - name: cursors | type: Cursors | description: Cursors to navigate through the result pages using `next` and `prev`. Returned if cursor paging is used. - name: next | type: string | description: Cursor pointing to next page in the list of results. - name: prev | type: string | description: Cursor pointing to previous page in the list of results. ``` ### Examples ### Query for a category with filters This example uses the `queryCategories()` function to search for categories in descending order that have a `displayPosition` less than or equal to 2. ```javascript import { categories } from '@wix/blog'; export async function queryCategoriesFunction() { try { const result = await categories.queryCategories({ query: { filter: { displayPosition: { $lt: 3 } }, sort: [ { fieldName: 'label', order: 'DESC' } ] }, options: { fieldsets: ['URL'] } }); console.log('Retrieved result:', result.categories); return result.categories; } catch (error) { console.log(error); } } /* Returns: * [ * { * "_id": "1ea22fce-bc3c-4b78-9422-f0f367f8628e", * "coverImage": "wix:image://v1/162e66_f6bffd1cd6144ddf87325b82fe8f42ed~mv2.jpg#originWidth=385&originHeight=245", * "description": "Posts about my summer", * "displayPosition": 2, * "label": "Summer", * "language": "en", * "postCount": 6, * "slug": "summer-slug" * "title": "Summer", * "translationId": "973369ad-0d4b-41f5-a820-1eed7986e0de", * "url": "http://https://tadasz7.wixsite.com/blog-velo-events/my-blog/categories/summer-slug" * }, * { * "_id": "f489bf39-3297-4854-8429-e19dbefdca0e", * "coverImage": "wix:image://v1/162e66_f6bffd1cd6144ddf87325b82fe8f42ed~mv2.jpg#originWidth=385&originHeight=245" * "description": "my category description", * "displayPosition": 0, * "label": "My Category", * "language": "en", * "postCount": 1, * "slug": "my-category", * "title": "My Category", * "translationId": "dfc5b1a7-df04-4596-b311-9724f0477c3e", * "url": "http://https://tadasz7.wixsite.com/blog-velo-events/my-blog/categories/my-category" * }, * { * "_id": "686d5dd8-317a-4e3a-96b5-fe25f107aafd", * "coverImage": "wix:image://v1/162e66_f6bffd1cd6144ddf87325b82fe8f42ed~mv2.jpg#originWidth=385&originHeight=245" * "description": "my category description", * "displayPosition": 1, * "label": "My Category 2", * "language": "lt", * "postCount": 0, * "slug": "my-category-2", * "title": "My Category 2", * "translationId": "dfc5b1a7-df04-4596-b311-9724f0477c3e", * "url": "http://https://tadasz7.wixsite.com/blog-velo-events/my-blog/categories/my-category-2" * } * ] */ ``` ### Retrieve a list of all categories This example uses the `queryCategories()` function to retrieve a list of all categories. ```javascript import { categories } from '@wix/blog'; export async function queryCategoriesFunction() { try { const results = await categories.queryCategories({ query: {} }); const items = results.categories; return items; } catch (error) { console.error(error); } } /* Returns: * [ * { * "_id": "f489bf39-3297-4854-8429-e19dbefdca0e", * "coverImage": "wix:image://v1/162e66_f6bffd1cd6144ddf87325b82fe8f42ed~mv2.jpg#originWidth=385&originHeight=245", * "description": "my category description", * "displayPosition": 0, * "label": "My Category", * "language": "en", * "postCount": 1, * "slug": "my-category", * "title": "My Category", * "translationId": "dfc5b1a7-df04-4596-b311-9724f0477c3e" * }, * { * "_id": "686d5dd8-317a-4e3a-96b5-fe25f107aafd", * "coverImage": "wix:image://v1/162e66_f6bffd1cd6144ddf87325b82fe8f42ed~mv2.jpg#originWidth=385&originHeight=245", * "description": "my category description", * "displayPosition": 1, * "label": "My Category 2", * "language": "lt", * "postCount": 0, * "slug": "my-category-2", * "title": "My Category 2", * "translationId": "dfc5b1a7-df04-4596-b311-9724f0477c3e" * }, * { * "_id": "1ea22fce-bc3c-4b78-9422-f0f367f8628e", * "coverImage": "wix:image://v1/162e66_f6bffd1cd6144ddf87325b82fe8f42ed~mv2.jpg#originWidth=385&originHeight=245", * "description": "Posts about my summer", * "displayPosition": 2, * "label": "Summer", * "language": "en", * "postCount": 6, * "slug": "summer-slug", * "title": "Summer", * "translationId": "973369ad-0d4b-41f5-a820-1eed7986e0de" * }, * { * "_id": "8bb208d0-bc3d-4caa-bbbf-775e52851d8f", * "coverImage": "wix:image://v1/162e66_f6bffd1cd6144ddf87325b82fe8f42ed~mv2.jpg#originWidth=385&originHeight=245", * "description": "Posts about my holidays", * "displayPosition": 3, * "label": "holidays", * "language": "en", * "postCount": 0, * "slug": "holidays", * "title": "Holidays", * "translationId": "" * } * ] */ ``` ### queryCategories (self-hosted) Self-hosted SDK calls require you to [create a client](https://dev.wix.com/docs/sdk/articles/work-with-the-sdk/about-the-wix-client.md). ```javascript import { createClient } from '@wix/sdk'; import { categories } from '@wix/blog'; // Import the auth strategy for the relevant access type // Import the relevant host module if needed const myWixClient = createClient ({ modules: { categories }, // Include the auth strategy and host as relevant }); async function queryCategories(query,options) { const response = await myWixClient.categories.queryCategories(query,options); }; ``` ---