> 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 # QueryTags # Package: blog # Namespace: TagService # Method link: https://dev.wix.com/docs/api-reference/business-solutions/blog/tags/query-tags.md ## Permission Scopes: Read Blog : SCOPE.DC-BLOG.READ-BLOGS ## Introduction Retrieves a list of up to 500 tags, given the provided paging, filtering, and sorting. Query Posts runs with these defaults, which you can override: - `postCount` 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: queryTags Description: Retrieves a list of up to 500 tags, given the provided paging, filtering, and sorting. Query Posts runs with these defaults, which you can override: - `postCount` 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/v3/tags/query Method: POST Method parameters: param name: fieldsets | type: array | description: List of additional tag fields to include in the response. For example, use the `URL` fieldset to retrieve the url field in the response in addition to the tag's base fields. Base fields don’t include any of the supported fieldset values. By default only the tag's base fields are returned. - enum: UNKNOWN, URL 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: QueryTagsResponse - name: tags | type: array | description: List of tags. - name: id | type: string | description: Tag GUID. - name: label | type: string | description: Tag label. A blog can't have two tags with the same label. - name: slug | type: string | description: Part of a tag's URL that refers to a specific tag. For example, `'https:/example.com/tags/{my-tag-slug}'` - name: createdDate | type: string | description: Date the tag was created. - name: updatedDate | type: string | description: Date the tag was last updated. - name: url | type: PageUrl | description: Tag URL. The `url` directs you to a page that lists every post with the specified tag. - 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: publishedPostCount | type: integer | description: Number of published posts with this tag. - name: translationId | type: string | description: GUID of the tag's translations when [Wix Multilingual](https://support.wix.com/en/article/wix-multilingual-translating-your-blog) is installed on a site. All translations of a single tag share the same `translationId`. - name: language | type: string | description: Tag language. 2-or-4-letter language code in [IETF BCP 47 language tag](https://en.wikipedia.org/wiki/IETF_language_tag) format. - 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 ### QueryTags ```curl ~~~cURL curl \ 'https://www.wixapis.com/blog/v2/tags/query' \ --data-binary '{ "filter": { "postCount": { "$gt": 5 } } }' \ } -H 'Content-Type: application/json' \ -H 'Authorization: ' ~~~ ``` --- ## JavaScript SDK ### Schema ``` Method: wixClientAdmin.blog.TagService.queryTags(query, options) Description: Retrieves a list of up to 500 tags, given the provided paging, filtering, and sorting. Query Posts runs with these defaults, which you can override: - `postCount` 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: QueryTagsOptions none - name: fieldsets | type: array | description: List of additional tag fields to include in the response. For example, use the `URL` fieldset to retrieve the url field in the response in addition to the tag's base fields. Base fields don’t include any of the supported fieldset values. By default only the tag's base fields are returned. - enum: UNKNOWN, URL param name: query | type: TagQuery | 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: tags | type: array | description: List of tags. - name: _id | type: string | description: Tag GUID. - name: label | type: string | description: Tag label. A blog can't have two tags with the same label. - name: slug | type: string | description: Part of a tag's URL that refers to a specific tag. For example, `'https:/example.com/tags/{my-tag-slug}'` - name: _createdDate | type: Date | description: Date the tag was created. - name: _updatedDate | type: Date | description: Date the tag was last updated. - name: url | type: string | description: Tag URL. The `url` directs you to a page that lists every post with the specified tag. - name: publishedPostCount | type: integer | description: Number of published posts with this tag. - name: translationId | type: string | description: GUID of the tag's translations when [Wix Multilingual](https://support.wix.com/en/article/wix-multilingual-translating-your-blog) is installed on a site. All translations of a single tag share the same `translationId`. - name: language | type: string | description: Tag language. 2-or-4-letter language code in [IETF BCP 47 language tag](https://en.wikipedia.org/wiki/IETF_language_tag) format. - 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 tags with filters This example uses the `queryTags()` function to retrieve all tags with a `postCount` less than 3. ```javascript import { tags } from '@wix/blog'; export async function queryTagsFunction() { try { const queryTagsResults = await tags.queryTags({ query: { filter: { postCount: { $lt: 3 } } } }); const items = queryTagsResults.tags; return items; } catch (error) { console.error(error); } } /* Returns: * [ * { * "_createdDate": "2022-07-19T10:30:03.607Z", * "_id": "32970480-e53b-46e7-b52f-fba810a0b45d", * "_updatedDate": "2022-07-19T10:30:03.607Z", * "label": "my tag", * "language": "en", * "postCount": 1, * "publishedPostCount": 1, * "slug": "my-tag", * "translationId": "", * "url": "http://https://tadasz7.wixsite.com/blog-velo-events/my-blog/tags/my-tag" * }, * { * "_createdDate": "2022-07-21T14:52:58.099Z", * "_id": "6a67d2ea-b758-49f1-a2bd-cce214246809", * "_updatedDate": "2022-07-21T14:52:58.099Z", * "label": "your tag", * "language": "en", * "postCount": 2, * "publishedPostCount": 2, * "slug": "your-tag", * "translationId": "", * "url": "http://https://tadasz7.wixsite.com/blog-velo-events/my-blog/tags/your-tag" * } * ] */ ``` ### Retrieves a list of all tags This example uses the `queryTags()` function to retrieve all tags. ```javascript import { tags } from '@wix/blog'; export async function queryTagsFunction() { try { const queryTagsResults = await tags.queryTags({ query: {} }); const items = queryTagsResults.tags; return items; } catch (error) { console.error(error); } } /* Returns: * [ * { * "_createdDate": "2022-07-19T10:30:03.607Z", * "_id": "32970480-e53b-46e7-b52f-fba810a0b45d", * "_updatedDate": "2022-07-19T10:30:03.607Z", * "label": "my tag", * "language": "en", * "postCount": 1, * "publishedPostCount": 1, * "slug": "my-tag", * "translationId": "" * }, * { * "_createdDate": "2022-07-21T14:52:58.099Z", * "_id": "6a67d2ea-b758-49f1-a2bd-cce214246809", * "_updatedDate": "2022-07-21T14:52:58.099Z", * "label": "your tag", * "language": "en", * "postCount": 2, * "publishedPostCount": 2, * "slug": "your-tag", * "translationId": "" * } * { * "_createdDate": "2022-07-22T09:27:45.883Z", * "_id": "28230621-702d-4dab-af68-7a2a9b152fae", * "_updatedDate": "2022-07-22T09:27:45.883Z", * "label": "their tag", * "language": "en", * "postCount": 3, * "publishedPostCount": 3, * "slug": "their-tag", * "translationId": "" * }, * ] */ ``` ### queryTags (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 { tags } from '@wix/blog'; // Import the auth strategy for the relevant access type // Import the relevant host module if needed const myWixClient = createClient ({ modules: { tags }, // Include the auth strategy and host as relevant }); async function queryTags(query,options) { const response = await myWixClient.tags.queryTags(query,options); }; ``` ---