> 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 # UpdateKeywordResearchItem # Package: seo # Namespace: KeywordResearchServiceV1 # Method link: https://dev.wix.com/docs/api-reference/business-management/seo/content-plan-keyword-research-v1/update-keyword-research-item.md ## Permission Scopes: Manage SEO Settings: SCOPE.PROMOTE.MANAGE-SEO ## Introduction Updates a keyword research item. `fieldMask` is required and must name at least one of `keyword` or `mainKeyword`. Those are the only writable fields, and an omitted or empty mask is rejected rather than treated as a request to write everything. `mainKeyword` only promotes. Set it to `true` to make the item its page's main keyword. Setting it to `false`, or leaving it out, changes nothing, so a main keyword can't be demoted with this method. This method updates an item that already exists. It can't add or delete a keyword. The first write to AI-generated research copies that research instead of changing it, so the response can carry a different `keywordResearchId`. Always send the ID from the most recent response on your next write. Sending the original ID again copies the research again. Changing `keyword` also refreshes that item's `searchVolume` and `competition`, even though the mask doesn't name them. Edits don't survive a later generation. A generation that completes after your edit produces fresh research that replaces the edited copy in every read. To update multiple keyword research items in a single API call, call [Bulk Update Keyword Research Items](https://dev.wix.com/docs/api-reference/business-management/seo/content-plan-keyword-research-v1/bulk-update-keyword-research-items.md). --- ## REST API ### Schema ``` Method: updateKeywordResearchItem Description: Updates a keyword research item. `fieldMask` is required and must name at least one of `keyword` or `mainKeyword`. Those are the only writable fields, and an omitted or empty mask is rejected rather than treated as a request to write everything. `mainKeyword` only promotes. Set it to `true` to make the item its page's main keyword. Setting it to `false`, or leaving it out, changes nothing, so a main keyword can't be demoted with this method. This method updates an item that already exists. It can't add or delete a keyword. The first write to AI-generated research copies that research instead of changing it, so the response can carry a different `keywordResearchId`. Always send the GUID from the most recent response on your next write. Sending the original GUID again copies the research again. Changing `keyword` also refreshes that item's `searchVolume` and `competition`, even though the mask doesn't name them. Edits don't survive a later generation. A generation that completes after your edit produces fresh research that replaces the edited copy in every read. To update multiple keyword research items in a single API call, call [Bulk Update Keyword Research Items](https://dev.wix.com/docs/api-reference/business-management/seo/content-plan-keyword-research-v1/bulk-update-keyword-research-items.md). URL: https://www.wixapis.com/promote/seo/v1/keyword-research-items/{item.id} Method: PATCH # Note: If the parameter `a.b` is listed under required parameters, `b` is only required if `a` is also present. Required parameters: keywordResearchId, item, item.id, fieldMask Method parameters: param name: fieldMask | type: fieldMask | description: Fields to update. Must name at least one of `keyword` or `mainKeyword`, the only writable fields. An omitted or empty mask is rejected. | required: true param name: item | type: UpdatedKeywordResearch | required: true - name: id | type: string | description: GUID of the keyword research item to update. | required: true | validation: format GUID - name: keyword | type: string | description: New keyword. Rejected if it's longer than 80 characters, or if it duplicates another keyword in the same research. Changing it also refreshes the item's `searchVolume` and `competition`. | validation: maxLength 1000 - name: mainKeyword | type: boolean | description: Whether to make this item its page's main keyword. Set to `true` to promote it. `false` and omitting the field both leave the current main keyword unchanged, so this field can't demote one. param name: keywordResearchId | type: keywordResearchId | description: GUID of the keyword research the item belongs to. Use the `keywordResearchId` from your most recent read or write. | required: true | validation: format GUID Return type: UpdateKeywordResearchItemResponse - name: keywordResearchItem | type: KeywordResearch | description: Updated keyword research item. - name: id | type: string | description: Keyword research item GUID. | read-only: true | validation: format GUID - name: keyword | type: string | description: The keyword itself. An update is rejected if the new keyword is longer than 80 characters, or if it duplicates another keyword in the same research. | validation: maxLength 1000 - name: pageId | type: string | description: GUID of the site page the keyword is assigned to. | validation: maxLength 1000 - name: itemType | type: string | description: Type of the site page the keyword is assigned to, such as a static page or a blog post. | validation: maxLength 1000 - name: pageUrl | type: string | description: URL of the site page the keyword is assigned to. | validation: maxLength 1000 - name: competition | type: integer | description: How hard it is to rank for the keyword, on a scale where a higher number means more competition. Recalculated when `keyword` changes, even if you don't name this field in the field mask. | validation: format int32 - name: searchVolume | type: integer | description: Estimated number of searches for the keyword per month. Recalculated when `keyword` changes, even if you don't name this field in the field mask. | validation: format int32 - name: pageDeleted | type: boolean | description: Whether the site page this keyword is assigned to has been deleted. A keyword assigned to a deleted page stays in the research. - name: primary | type: boolean | description: Whether this keyword is the main keyword for its page. A page has a single main keyword, and the other keywords in its cluster support it. - name: clusterName | type: string | description: Name of the cluster that groups this keyword with the others covering the same topic. | validation: maxLength 1000 - name: keywordResearchId | type: string | description: GUID of the keyword research holding the updated item. This can differ from the GUID you sent, because the first edit to generated research copies it. Use this value for your next write. | validation: format GUID ``` ### Examples ### Change a keyword The first edit to generated research copies it, so the returned keywordResearchId differs from the one sent. Use the returned ID for the next write. ```curl curl -X PATCH \ 'https://www.wixapis.com/seo-content-plan-service/v1/keyword-research-items/b70d5a92-31ef-4c08-8a6d-45f19be7c203' \ -H 'Authorization: ' \ -H 'Content-Type: application/json' \ -d '{ "keywordResearchId": "3f9c2b71-4d8e-4a15-9c63-b0e7d21a5f84", "item": { "id": "b70d5a92-31ef-4c08-8a6d-45f19be7c203", "keyword": "how to store coffee beans at home" }, "fieldMask": "keyword" }' ``` --- ## JavaScript SDK ### Schema ``` Method: wixClientAdmin.seo.keywordResearch.updateKeywordResearchItem(_id, keywordResearchId, options) Description: Updates a keyword research item. `fieldMask` is required and must name at least one of `keyword` or `mainKeyword`. Those are the only writable fields, and an omitted or empty mask is rejected rather than treated as a request to write everything. `mainKeyword` only promotes. Set it to `true` to make the item its page's main keyword. Setting it to `false`, or leaving it out, changes nothing, so a main keyword can't be demoted with this method. This method updates an item that already exists. It can't add or delete a keyword. The first write to AI-generated research copies that research instead of changing it, so the response can carry a different `keywordResearchId`. Always send the GUID from the most recent response on your next write. Sending the original GUID again copies the research again. Changing `keyword` also refreshes that item's `searchVolume` and `competition`, even though the mask doesn't name them. Edits don't survive a later generation. A generation that completes after your edit produces fresh research that replaces the edited copy in every read. To update multiple keyword research items in a single API call, call [Bulk Update Keyword Research Items](https://dev.wix.com/docs/api-reference/business-management/seo/content-plan-keyword-research-v1/bulk-update-keyword-research-items.md). # Note: If the parameter `a.b` is listed under required parameters, `b` is only required if `a` is also present. Required parameters: keywordResearchId, options.item, _id, options.fieldMask, options Method parameters: param name: _id | type: string | description: GUID of the keyword research item to update. | required: true | validation: format GUID param name: keywordResearchId | type: UpdateKeywordResearchItem | required: true - name: value | type: string | description: param name: options | type: UpdateKeywordResearchItemOptions none | required: true - name: item | type: UpdatedKeywordResearch | description: Keyword research item to update. | required: true - name: _id | type: string | description: GUID of the keyword research item to update. | validation: format GUID - name: keyword | type: string | description: New keyword. Rejected if it's longer than 80 characters, or if it duplicates another keyword in the same research. Changing it also refreshes the item's `searchVolume` and `competition`. | validation: maxLength 1000 - name: mainKeyword | type: boolean | description: Whether to make this item its page's main keyword. Set to `true` to promote it. `false` and omitting the field both leave the current main keyword unchanged, so this field can't demote one. - name: fieldMask | type: array | description: Fields to update. Must name at least one of `keyword` or `mainKeyword`, the only writable fields. An omitted or empty mask is rejected. | required: true Return type: PROMISE - name: keywordResearchItem | type: KeywordResearch | description: Updated keyword research item. - name: _id | type: string | description: Keyword research item GUID. | read-only: true | validation: format GUID - name: keyword | type: string | description: The keyword itself. An update is rejected if the new keyword is longer than 80 characters, or if it duplicates another keyword in the same research. | validation: maxLength 1000 - name: pageId | type: string | description: GUID of the site page the keyword is assigned to. | validation: maxLength 1000 - name: itemType | type: string | description: Type of the site page the keyword is assigned to, such as a static page or a blog post. | validation: maxLength 1000 - name: pageUrl | type: string | description: URL of the site page the keyword is assigned to. | validation: maxLength 1000 - name: competition | type: integer | description: How hard it is to rank for the keyword, on a scale where a higher number means more competition. Recalculated when `keyword` changes, even if you don't name this field in the field mask. | validation: format int32 - name: searchVolume | type: integer | description: Estimated number of searches for the keyword per month. Recalculated when `keyword` changes, even if you don't name this field in the field mask. | validation: format int32 - name: pageDeleted | type: boolean | description: Whether the site page this keyword is assigned to has been deleted. A keyword assigned to a deleted page stays in the research. - name: primary | type: boolean | description: Whether this keyword is the main keyword for its page. A page has a single main keyword, and the other keywords in its cluster support it. - name: clusterName | type: string | description: Name of the cluster that groups this keyword with the others covering the same topic. | validation: maxLength 1000 - name: keywordResearchId | type: string | description: GUID of the keyword research holding the updated item. This can differ from the GUID you sent, because the first edit to generated research copies it. Use this value for your next write. | validation: format GUID ``` ### Examples ### Change a keyword and make it its page's main keyword `fieldMask` is required and accepts only the paths `keyword` and `main_keyword`. Field mask paths use the API's field names, so `main_keyword` is correct here even though the property you set is `mainKeyword`. The response can carry a different `keywordResearchId`, because the first write to generated research copies it. Send the ID from the response on your next write. ```javascript import { keywordResearch } from "@wix/seo"; async function updateKeywordResearchItem() { const response = await keywordResearch.updateKeywordResearchItem( "c5f9e1a4-7b62-4d18-9a35-1e8f4c2d6b70", "8f3b6d2e-4c17-4a90-b5e3-9d70c1af2b48", { item: { keyword: "hand thrown ceramic mugs", mainKeyword: true, }, fieldMask: ["keyword", "main_keyword"], }, ); } /* Promise resolves to: * { * "keywordResearchItem": { * "_id": "c5f9e1a4-7b62-4d18-9a35-1e8f4c2d6b70", * "keyword": "hand thrown ceramic mugs", * "pageId": "a1b2c3d4-e5f6-4890-abcd-ef1234567890", * "itemType": "STATIC_PAGE", * "pageUrl": "https://example.com/shop", * "competition": 28, * "searchVolume": 1300, * "pageDeleted": false, * "primary": true, * "clusterName": "ceramic drinkware" * }, * "keywordResearchId": "b2c4e8a0-5f31-4276-9c8d-3a1e7b90fd52" * } */ ``` ### updateKeywordResearchItem (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 { keywordResearch } from '@wix/seo'; // Import the auth strategy for the relevant access type // Import the relevant host module if needed const myWixClient = createClient ({ modules: { keywordResearch }, // Include the auth strategy and host as relevant }); async function updateKeywordResearchItem(_id,keywordResearchId,options) { const response = await myWixClient.keywordResearch.updateKeywordResearchItem(_id,keywordResearchId,options); }; ``` ---