# Keyword.com Google SERP Tracker API v2 - **OpenAPI Version:** `3.2.0` - **API Version:** `2.0.0` # Introduction The **Keyword.com API** empowers developers to programmatically access and manage keyword ranking data, giving you the same core functionality available in the Keyword.com interface. Whether you’re building an SEO tool, a content marketing platform, or a performance dashboard, our API delivers the data and insights needed to grow search visibility and drive traffic. This documentation covers everything you need to get started: - Authentication using secure headers - RESTful endpoints for managing projects and keywords - Practical examples of requests and responses - Tips for efficient, scalable integration ## **Getting Started** To use the API, you’ll need an API token. If you don’t have one yet, create an account on [Keyword.com](https://keyword.com) and retrieve your token under **Settings >** [Account tab](https://app.keyword.com/settings/account). Once authenticated, you can: - Retrieve project and keyword ranking data - Add and delete keywords - Trigger on-demand keyword refreshes - Access custom shareable view links for reporting - And more... With this API, you can integrate Keyword.com into your internal tools, automate SEO workflows, and scale your keyword tracking operations. ## Authentication The Keyword.com API uses **token-based authentication via HTTP headers** for secure access. ### **Required Header** Include the following header in all your API requests: ```properties Authorization: Bearer [API_TOKEN] ``` Example: ```bash curl --location 'https://app.keyword.com/api/v2/groups/Apple/keywords/272678916' \ --header 'Authorization: Bearer [API_TOKEN]' ``` ### **API Token Types** There are two types of tokens: - **Master API Token** Grants full access to your account, including all projects and administrative actions (e.g., add/remove keywords, manage users). - **Project Auth Token + ViewKey** Provides access to a specific project. Useful when sharing data with third-party tools or restricting access. Keep your API key and tokens secure, and do not share them with unauthorized users. Anyone with your token can read and modify your Keyword.com data. ### Making API Requests The Keyword.com API follows a RESTful design, using standard HTTP methods: - GET to retrieve data - POST to create resources - PATCH to update data - DELETE to remove resources All responses are returned in JSON format for easy integration. ## Base URL All API requests should be made to: ```properties https://app.keyword.com/api/v2 ``` ## Rate Limits API requests are rate-limited per token to protect service stability: | Endpoint group | Limit | | ------------------------------------ | ------------------ | | Keywords (list, get, create, delete) | 60 requests/minute | | Competitor history | 30 requests/minute | | All other endpoints | 60 requests/minute | When you exceed a rate limit, the API returns HTTP `429 Too Many Requests`. Use exponential backoff (e.g. retry after 1s, then 2s, then 4s) rather than retrying immediately. ## Pagination List endpoints return paginated results. Control pagination with query parameters: | Parameter | Type | Description | | ---------- | ------- | ------------------------------------------------------ | | `page` | integer | Page number (default: 1) | | `per_page` | integer | Results per page (default: 20, max varies by endpoint) | Paginated responses include metadata: ```json { "data": [...], "meta": { "pagination": { "total": 150, "count": 20, "per_page": 20, "current_page": 1, "total_pages": 8 } }, "links": { "self": "https://app.keyword.com/api/v2/...&page=1", "first": "https://app.keyword.com/api/v2/...&page=1", "next": "https://app.keyword.com/api/v2/...&page=2", "last": "https://app.keyword.com/api/v2/...&page=8" } } ``` ## Error Handling Error responses follow a consistent format with an `errors` array: ```json { "errors": [ { "code": "401", "title": "Your request is unauthorized", "message": "Unauthenticated." } ] } ``` | HTTP Status | Meaning | | ----------- | -------------------------------------------------------- | | `401` | Invalid or missing API token | | `403` | Insufficient permissions (e.g. view-only token) | | `404` | Resource not found | | `422` | Validation error — check the `message` field for details | | `429` | Rate limit exceeded | *** ## **Keyword Update Schedule** One of the core benefits of using **Keyword.com** is that **you don’t need to manually run API requests to keep your keyword data fresh**—we handle that for you. When you add keywords to a project, they’re automatically queued for updates according to your plan. Our system continuously tracks and refreshes keyword rankings in the background, so you can focus on analysis and insights rather than data collection. #### Automatic Update Frequency | **Plan Type** | **Update Frequency** | | ------------- | -------------------- | | Daily | Every 24 hours | | Weekly | Every 7 days | > **Example**: If you’re on a weekly plan and added keywords on a Wednesday, your keywords will automatically refresh every Wednesday between 00:00 and 12:00 UTC On-demand refreshes are limited based on your plan and count separately from the automatic updates above. This hybrid approach gives you both the **convenience of automation** and the **control of real-time updates** when you need them. ## Servers - **URL:** `https://app.keyword.com` ## Operations ### List projects - **Method:** `GET` - **Path:** `/api/v2/groups/active` - **Tags:** Projects This call will get you a summary of all your projects with their respective groups, tags and number of keywords. It will also provide you with the PROJECT AUTH KEY which is required to collect detailed project and keyword data. **Important Notes:** 1. The group name must follow the required naming convention and include \[sub] when submitting the request. 2. Ensure the parent project is created **before** adding groups to it. #### Responses ##### Status: 200 Returns all projects and groups (subprojects) with their tags and keyword counts. Groups are identified by the \`\[sub]\` naming convention in the \`id\` field (e.g. \`Disney\[sub]Disney Classics\`). ###### Content-Type: application/json - **`data`** `array` **Items:** - **`attributes`** `object` - **`auth`** `string` — Project auth key for API access and ViewKey links - **`company_desc`** `string | null` - **`company_link`** `string | null` - **`company_logo`** `string | null` - **`company_name`** `string | null` - **`crawled_at`** `string | null`, format: `date-time` — Date and time of last keyword ranking refresh - **`currency_code`** `string` — Currency code for cost-related data (e.g. USD, GBP) - **`keywords_count`** `object` - **`ACTIVE`** `integer` — Number of active keywords - **`keywords_last_updated_at`** `string`, format: `date-time` — Last time keyword rankings were updated - **`name`** `string` — Project or group name - **`notes_count`** `integer` - **`password`** `string | null` — Password for shared ViewKey links - **`project_id`** `integer` — Unique identifier of the project or group - **`project_overview_settings`** `object` — Display configuration for project overview widgets - **`shortkey`** `string` — Short identifier used in shareable ViewKey URLs - **`sov_view_key`** `boolean` — Whether Share of Voice is visible in shared ViewKeys - **`tags`** `array` **Items:** - **`created_at`** `string`, format: `date-time` - **`id`** `integer` — Unique tag identifier - **`keywords_count`** `integer` — Number of keywords with this tag - **`name`** `string` — Tag name - **`project_id`** `integer` — Parent project or group ID - **`updated_at`** `string`, format: `date-time` - **`tags_count`** `integer` — Number of tags in the project or group - **`updated_at`** `string`, format: `date-time` - **`url`** `string | null` — Custom website URL for the project - **`id`** `string` — Project or group name. Groups include \`\[sub]\` in the name. - **`type`** `string`, possible values: `"group"` **Example:** ```json { "data": [ { "type": "group", "id": "", "attributes": { "project_id": 1, "auth": "", "name": "", "keywords_count": { "ACTIVE": 1 }, "tags_count": 1, "tags": [ { "id": 1, "project_id": 1, "name": "", "created_at": "", "updated_at": "", "keywords_count": 1 } ], "keywords_last_updated_at": "", "notes_count": 1, "updated_at": "", "password": null, "company_name": null, "company_desc": null, "company_link": null, "company_logo": null, "sov_view_key": true, "crawled_at": null, "currency_code": "", "url": null, "shortkey": "", "project_overview_settings": { "additionalProperty": { "visible": true, "order": 1 } } } } ] } ``` ##### Status: 401 Authentication failed — invalid or missing API token ###### Content-Type: application/json - **`errors`** `array` **Items:** - **`code`** `string` — Application-specific error code - **`message`** `string` — Detailed error message - **`title`** `string` — Human-readable error summary **Example:** ```json { "errors": [ { "code": "", "title": "", "message": "" } ] } ``` ##### Status: 404 The requested resource was not found ###### Content-Type: application/json - **`errors`** `array` **Items:** - **`code`** `string` — Application-specific error code - **`message`** `string` — Detailed error message - **`title`** `string` — Human-readable error summary **Example:** ```json { "errors": [ { "code": "", "title": "", "message": "" } ] } ``` ### Create project - **Method:** `POST` - **Path:** `/api/v2/groups` - **Tags:** Projects Use this endpoint to create a single project in your Keyword.com account #### Request Body ##### Content-Type: application/json - **`data` (required)** `object` - **`attributes` (required)** `object` - **`category` (required)** `string` — Project name - **`currency_code`** `string` — Currency for reporting (e.g. USD, EUR, GBP) - **`type` (required)** `string`, possible values: `"group"` **Example:** ```json { "data": { "type": "group", "attributes": { "category": "", "currency_code": "" } } } ``` #### Responses ##### Status: 201 Create project ###### Content-Type: application/json - **`data`** `object` - **`attributes`** `object` - **`auth`** `string` — Project auth key for API access and ViewKey links - **`company_desc`** `string | null` - **`company_link`** `string | null` - **`company_logo`** `string | null` - **`company_name`** `string | null` - **`crawled_at`** `string | null`, format: `date-time` — Date and time of last keyword ranking refresh - **`currency_code`** `string` — Currency code for cost-related data (e.g. USD, GBP) - **`keywords_count`** `object` - **`ACTIVE`** `integer` — Number of active keywords - **`keywords_last_updated_at`** `string`, format: `date-time` — Last time keyword rankings were updated - **`name`** `string` — Project or group name - **`notes_count`** `integer` - **`password`** `string | null` — Password for shared ViewKey links - **`project_id`** `integer` — Unique identifier of the project or group - **`project_overview_settings`** `object` — Display configuration for project overview widgets - **`shortkey`** `string` — Short identifier used in shareable ViewKey URLs - **`sov_view_key`** `boolean` — Whether Share of Voice is visible in shared ViewKeys - **`tags`** `array` **Items:** - **`created_at`** `string`, format: `date-time` - **`id`** `integer` — Unique tag identifier - **`keywords_count`** `integer` — Number of keywords with this tag - **`name`** `string` — Tag name - **`project_id`** `integer` — Parent project or group ID - **`updated_at`** `string`, format: `date-time` - **`tags_count`** `integer` — Number of tags in the project or group - **`updated_at`** `string`, format: `date-time` - **`url`** `string | null` — Custom website URL for the project - **`id`** `string` — Project or group name. Groups include \`\[sub]\` in the name. - **`type`** `string`, possible values: `"group"` **Example:** ```json { "data": { "type": "group", "id": "", "attributes": { "project_id": 1, "auth": "", "name": "", "keywords_count": { "ACTIVE": 1 }, "tags_count": 1, "tags": [ { "id": 1, "project_id": 1, "name": "", "created_at": "", "updated_at": "", "keywords_count": 1 } ], "keywords_last_updated_at": "", "notes_count": 1, "updated_at": "", "password": null, "company_name": null, "company_desc": null, "company_link": null, "company_logo": null, "sov_view_key": true, "crawled_at": null, "currency_code": "", "url": null, "shortkey": "", "project_overview_settings": { "additionalProperty": { "visible": true, "order": 1 } } } } } ``` ##### Status: 401 Authentication failed — invalid or missing API token ###### Content-Type: application/json - **`errors`** `array` **Items:** - **`code`** `string` — Application-specific error code - **`message`** `string` — Detailed error message - **`title`** `string` — Human-readable error summary **Example:** ```json { "errors": [ { "code": "", "title": "", "message": "" } ] } ``` ##### Status: 404 The requested resource was not found ###### Content-Type: application/json - **`errors`** `array` **Items:** - **`code`** `string` — Application-specific error code - **`message`** `string` — Detailed error message - **`title`** `string` — Human-readable error summary **Example:** ```json { "errors": [ { "code": "", "title": "", "message": "" } ] } ``` ### Get project - **Method:** `GET` - **Path:** `/api/v2/groups/{project_name}` - **Tags:** Projects This call is used to retrieve a single project’s summary of groups, tags and number of keywords. It will also provide you with the PROJECT AUTH KEY which is required to collect detailed project and keyword data. **Important Notes:** 1. The group name must follow the required naming convention and include \[sub] when submitting the request. 2. Ensure the parent project is created **before** adding groups to it. #### Responses ##### Status: 200 Retrieve details for a single project or group (subproject). To fetch a group, use the full name including \`\[sub]\` (e.g. \`Disney\[sub]Disney Classics\`). ###### Content-Type: application/json - **`data`** `object` - **`attributes`** `object` - **`auth`** `string` — Project auth key for API access and ViewKey links - **`company_desc`** `string | null` - **`company_link`** `string | null` - **`company_logo`** `string | null` - **`company_name`** `string | null` - **`crawled_at`** `string | null`, format: `date-time` — Date and time of last keyword ranking refresh - **`currency_code`** `string` — Currency code for cost-related data (e.g. USD, GBP) - **`keywords_count`** `object` - **`ACTIVE`** `integer` — Number of active keywords - **`keywords_last_updated_at`** `string`, format: `date-time` — Last time keyword rankings were updated - **`name`** `string` — Project or group name - **`notes_count`** `integer` - **`password`** `string | null` — Password for shared ViewKey links - **`project_id`** `integer` — Unique identifier of the project or group - **`project_overview_settings`** `object` — Display configuration for project overview widgets - **`shortkey`** `string` — Short identifier used in shareable ViewKey URLs - **`sov_view_key`** `boolean` — Whether Share of Voice is visible in shared ViewKeys - **`tags`** `array` **Items:** - **`created_at`** `string`, format: `date-time` - **`id`** `integer` — Unique tag identifier - **`keywords_count`** `integer` — Number of keywords with this tag - **`name`** `string` — Tag name - **`project_id`** `integer` — Parent project or group ID - **`updated_at`** `string`, format: `date-time` - **`tags_count`** `integer` — Number of tags in the project or group - **`updated_at`** `string`, format: `date-time` - **`url`** `string | null` — Custom website URL for the project - **`id`** `string` — Project or group name. Groups include \`\[sub]\` in the name. - **`type`** `string`, possible values: `"group"` **Example:** ```json { "data": { "type": "group", "id": "", "attributes": { "project_id": 1, "auth": "", "name": "", "keywords_count": { "ACTIVE": 1 }, "tags_count": 1, "tags": [ { "id": 1, "project_id": 1, "name": "", "created_at": "", "updated_at": "", "keywords_count": 1 } ], "keywords_last_updated_at": "", "notes_count": 1, "updated_at": "", "password": null, "company_name": null, "company_desc": null, "company_link": null, "company_logo": null, "sov_view_key": true, "crawled_at": null, "currency_code": "", "url": null, "shortkey": "", "project_overview_settings": { "additionalProperty": { "visible": true, "order": 1 } } } } } ``` ##### Status: 401 Authentication failed — invalid or missing API token ###### Content-Type: application/json - **`errors`** `array` **Items:** - **`code`** `string` — Application-specific error code - **`message`** `string` — Detailed error message - **`title`** `string` — Human-readable error summary **Example:** ```json { "errors": [ { "code": "", "title": "", "message": "" } ] } ``` ##### Status: 404 The requested resource was not found ###### Content-Type: application/json - **`errors`** `array` **Items:** - **`code`** `string` — Application-specific error code - **`message`** `string` — Detailed error message - **`title`** `string` — Human-readable error summary **Example:** ```json { "errors": [ { "code": "", "title": "", "message": "" } ] } ``` ### Delete project - **Method:** `DELETE` - **Path:** `/api/v2/groups/{project_name}` - **Tags:** Projects This call will delete a single project or group. **Important Notes:** 1. The group name must follow the required naming convention and include \[sub] when submitting the request. 2. Ensure the parent project is created **before** adding groups to it. #### Responses ##### Status: 200 Permanently delete a project or group (subproject). This cannot be undone — all keywords and historical data will be lost. To delete a group, use the full name including \`\[sub]\`. ###### Content-Type: application/json - **`meta`** `object` - **`code`** `string`, format: `utc-millisec` - **`extra_data`** `array` **Items:** - **`title`** `string` **Example:** ```json { "meta": { "title": "", "code": "", "extra_data": [] } } ``` ##### Status: 401 Authentication failed — invalid or missing API token ###### Content-Type: application/json - **`errors`** `array` **Items:** - **`code`** `string` — Application-specific error code - **`message`** `string` — Detailed error message - **`title`** `string` — Human-readable error summary **Example:** ```json { "errors": [ { "code": "", "title": "", "message": "" } ] } ``` ##### Status: 404 The requested resource was not found ###### Content-Type: application/json - **`errors`** `array` **Items:** - **`code`** `string` — Application-specific error code - **`message`** `string` — Detailed error message - **`title`** `string` — Human-readable error summary **Example:** ```json { "errors": [ { "code": "", "title": "", "message": "" } ] } ``` ### Archive project - **Method:** `PUT` - **Path:** `/api/v2/groups/{project_name}` - **Tags:** Projects Sets the project status to “Archived.” The project will remain in the “Archived” state until it is either restored or permanently deleted. **Important Notes:** 1. The group name must follow the required naming convention and include \[sub] when submitting the request. 2. Ensure the parent project is created **before** adding groups to it. #### Request Body ##### Content-Type: application/json - **`data` (required)** `object` - **`attributes` (required)** `object` - **`status` (required)** `integer`, possible values: `2` — Set to 2 to archive the project or group - **`type` (required)** `string`, possible values: `"group"` **Example:** ```json { "data": { "type": "group", "attributes": { "status": 2 } } } ``` #### Responses ##### Status: 200 Project or group has been archived successfully ###### Content-Type: application/json - **`meta`** `object` - **`code`** `string` - **`title`** `string` **Example:** ```json { "meta": { "title": "", "code": "" } } ``` ##### Status: 401 Authentication failed — invalid or missing API token ###### Content-Type: application/json - **`errors`** `array` **Items:** - **`code`** `string` — Application-specific error code - **`message`** `string` — Detailed error message - **`title`** `string` — Human-readable error summary **Example:** ```json { "errors": [ { "code": "", "title": "", "message": "" } ] } ``` ##### Status: 404 The requested resource was not found ###### Content-Type: application/json - **`errors`** `array` **Items:** - **`code`** `string` — Application-specific error code - **`message`** `string` — Detailed error message - **`title`** `string` — Human-readable error summary **Example:** ```json { "errors": [ { "code": "", "title": "", "message": "" } ] } ``` ### Restore project - **Method:** `GET` - **Path:** `/api/v2/groups/{project_name}/undo/archive` - **Tags:** Projects This endpoint allows users to restore archived projects or groups. Once restored, the associated keywords will automatically update during the next scheduled automatic cycle. If an immediate update is needed, users can trigger an on-demand request for the restored project. Important Notes: - The group name must follow the required naming convention and include \[sub] when submitting the request. - Ensure the parent project is created before adding groups to it. #### Responses ##### Status: 200 Project or group has been restored successfully ###### Content-Type: application/json - **`meta`** `object` - **`code`** `string` - **`title`** `string` **Example:** ```json { "meta": { "title": "", "code": "" } } ``` ##### Status: 401 Authentication failed — invalid or missing API token ###### Content-Type: application/json - **`errors`** `array` **Items:** - **`code`** `string` — Application-specific error code - **`message`** `string` — Detailed error message - **`title`** `string` — Human-readable error summary **Example:** ```json { "errors": [ { "code": "", "title": "", "message": "" } ] } ``` ##### Status: 404 The requested resource was not found ###### Content-Type: application/json - **`errors`** `array` **Items:** - **`code`** `string` — Application-specific error code - **`message`** `string` — Detailed error message - **`title`** `string` — Human-readable error summary **Example:** ```json { "errors": [ { "code": "", "title": "", "message": "" } ] } ``` ### List keywords - **Method:** `GET` - **Path:** `/api/v2/groups/{project_name}/keywords` - **Tags:** Keywords Use this endpoint to fetch all keyword settings and ranking metrics for a specific **group** or **project**. This includes each keyword’s configuration, rank history, and associated metrics. By default, the API returns **20 results per page**. However, for best performance—especially when dealing with large datasets—we recommend setting the per\_page parameter to **250** and paginating through results using the page parameter. #### **Example for a group or project with 500 keywords:** - **Request 1:** `https://app.keyword.com/api/v2/groups/[project_name]/keywords/?per_page=250&page=1` - **Request 2:** `https://app.keyword.com/api/v2/groups/[project_name]/keywords/?per_page=250&page=2` This method ensures faster responses and minimizes server load while retrieving bulk keyword data. > ⚠️ Note: If per\_page is not specified, the default is 20 results per page. You can obtain each keyword\_id after you’ve added a keyword to a group or project. This ID is used for other actions like updating or refreshing a specific keyword. **You can also collect the data for a single date by using the 'date' parameter.** #### Responses ##### Status: 200 Retrieve all keywords and their data in project or group ###### Content-Type: application/json - **`data`** `array` **Items:** - **`attributes`** `object` - **`auth`** `string` — Project auth key - **`best`** `integer | null` — Best ranking position since tracking started - **`category`** `string` — Project name - **`clicks`** `integer` — Average clicks from Google Search Console (-1 if not linked) - **`competition`** `number` — Competition metric from Google Ads - **`cpc`** `number` — Average cost per click in USD from Google Ads - **`crawled_at`** `integer | null` — Unix timestamp of last rank check - **`ctr`** `number` — Click-through rate from Google Search Console (-1 if not linked) - **`currency_symbol`** `string` — Currency symbol for CPC values (e.g. $, €) - **`gmb`** `string | null` — Google Business Profile name - **`gpage`** `integer | null` — Google results page number - **`grank`** `integer | string | null` — Current Google rank position. Returns \`"OTR"\` (Out of Range) when ranking beyond tracked SERP depth, or null while scraping is in progress. See \[Ranking Positions & Historical Data Explained]\(https\://support.keyword.com/en/articles/13701470-ranking-positions-historical-data-explained). - **`grank_int`** `integer` — Numeric rank value (0 if out of top results) - **`grankhistory`** `array` — Historical ranking positions **Items:** `integer` - **`has_featured`** `boolean` — Whether keyword has any featured snippets - **`has_featured_url`** `string` — URL ranking in the featured snippet, or empty string if none - **`ignore_featured`** `boolean` — Whether featured snippets are excluded from tracking - **`ignore_local`** `boolean` — Whether local listings are excluded from tracking - **`impressions`** `integer` — Impressions from Google Search Console (-1 if not linked) - **`in_featured`** `boolean` — Whether domain ranks in featured snippets - **`in_local_pack`** `boolean` — Whether ranking in local pack - **`included_in_sov`** `boolean` — Whether keyword is included in Share of Voice calculations - **`is_paginated`** `integer` — SERP pagination depth at which the ranking URL was found - **`isfav`** `boolean` — Whether keyword is marked as favorite - **`kw`** `string` — Keyword text - **`language`** `string` — Tracked language code - **`ms`** `integer` — Monthly search volume - **`near`** `string | null` — Location for local tracking - **`notes`** `string | null` - **`project_id`** `integer` - **`rankingurl`** `string` — URL currently ranking for this keyword - **`region`** `string` — Google region (e.g. google.com, google.co.uk) - **`search_intents`** `object` — Search intent probability scores (0-1) - **`commercial`** `number | null` - **`informational`** `number | null` - **`navigational`** `number | null` - **`transactional`** `number | null` - **`seocomp`** `integer | null` — Number of search results for this keyword - **`serp_features`** `object` — SERP features detected for this keyword (e.g. \`{"knowledge\_panel": 1, "video": 0}\`) - **`source`** `integer` — How keyword was added (1=API, 2=Suggestions, 3=Manual, 4=Bulk import) - **`start`** `integer | null` — Starting rank when keyword was first added - **`status`** `string`, possible values: `"EMPTY", "INACTIVE", "ACTIVE", "ARCHIVED"` - **`tag`** `string | null` — Legacy single-tag field; prefer the \`tags\` array - **`tags`** `array` **Items:** `string` - **`tags_count`** `integer` - **`trends`** `object` — Rank position changes. Values are integers, or \`"N/A"\` when data is unavailable. - **`day`** `integer | string` — Daily position change - **`life`** `integer | string` — Lifetime position change - **`month`** `integer | string` — Monthly position change - **`week`** `integer | string` — Weekly position change - **`type`** `string` — Device type (se=desktop, sem=mobile) - **`updated_at`** `string`, format: `date-time` — Last time keyword settings were changed - **`url`** `string` — Tracked domain or URL - **`url_tracking_method`** `string`, possible values: `"broad", "exact"` - **`id`** `string` — Unique keyword ID - **`type`** `string`, possible values: `"keyword"` - **`links`** `object` - **`first`** `string` - **`last`** `string` - **`next`** `string | null` - **`self`** `string` - **`meta`** `object` - **`domains`** `array` **Items:** `string` - **`pagination`** `object` - **`count`** `integer` - **`current_page`** `integer` - **`per_page`** `integer` - **`total`** `integer` - **`total_pages`** `integer` - **`types`** `array` **Items:** `string` **Example:** ```json { "data": [ { "type": "keyword", "id": "", "attributes": { "project_id": 1, "category": "", "url": "", "auth": "", "kw": "", "source": 1, "start": null, "notes": null, "tags_count": 1, "tags": [ "" ], "region": "", "language": "", "in_featured": true, "has_featured": true, "ignore_local": true, "ignore_featured": true, "url_tracking_method": "broad", "type": "", "gmb": null, "near": null, "isfav": true, "status": "EMPTY", "clicks": 1, "impressions": 1, "ctr": 1, "ms": 1, "competition": 1, "cpc": 1, "gpage": null, "serp_features": { "additionalProperty": 0 }, "grank": null, "grank_int": 1, "best": null, "seocomp": null, "in_local_pack": true, "rankingurl": "", "trends": { "day": 1, "week": 1, "month": 1, "life": 1 }, "updated_at": "", "crawled_at": null, "has_featured_url": "", "currency_symbol": "", "included_in_sov": true, "is_paginated": 1, "search_intents": { "commercial": null, "informational": null, "navigational": null, "transactional": null } } } ], "meta": { "pagination": { "total": 1, "count": 1, "per_page": 1, "current_page": 1, "total_pages": 1 }, "domains": [ "" ], "types": [ "" ] }, "links": { "self": "", "first": "", "next": null, "last": "" } } ``` ##### Status: 401 Authentication failed — invalid or missing API token ###### Content-Type: application/json - **`errors`** `array` **Items:** - **`code`** `string` — Application-specific error code - **`message`** `string` — Detailed error message - **`title`** `string` — Human-readable error summary **Example:** ```json { "errors": [ { "code": "", "title": "", "message": "" } ] } ``` ##### Status: 404 The requested resource was not found ###### Content-Type: application/json - **`errors`** `array` **Items:** - **`code`** `string` — Application-specific error code - **`message`** `string` — Detailed error message - **`title`** `string` — Human-readable error summary **Example:** ```json { "errors": [ { "code": "", "title": "", "message": "" } ] } ``` ### Add keywords - **Method:** `POST` - **Path:** `/api/v2/groups/{project_name}/keywords` - **Tags:** Keywords Add keywords to project or group. The response will include details of the keywords, but will not include tracking data and keyword metrics. Those are being updated in the background. #### Request Body ##### Content-Type: application/json - **`data` (required)** `array` **Items:** - **`attributes` (required)** `object` - **`category` (required)** `string` — Project name - **`kw` (required)** `string` — Keyword to track (max 150 characters) - **`language` (required)** `string` — Language code (e.g. en, fr, de) - **`region` (required)** `string` — Google region (e.g. google.com, google.co.uk) - **`url` (required)** `string` — Domain to track. Without trailing \`/\` tracks broad domain; with \`/\` tracks exact URL. - **`gmb`** `string` — Google Business Profile name (must be exact match) - **`ignore_local`** `boolean` — Whether to exclude local listings - **`ignore_sub_domains`** `boolean` — Whether to ignore sub-domains while tracking - **`near`** `string` — Location for local rank tracking - **`source`** `integer`, possible values: `1` — Source identifier (1=API) - **`tags`** `array` **Items:** `string` - **`type`** `string`, possible values: `"se", "sem"` — Device type (se=desktop, sem=mobile) - **`url_tracking_method`** `string`, possible values: `"broad", "exact"` - **`type` (required)** `string`, possible values: `"keyword"` **Example:** ```json { "data": [ { "type": "keyword", "attributes": { "category": "", "url": "", "region": "", "language": "", "kw": "", "type": "se", "ignore_local": true, "near": "", "source": 1, "gmb": "", "tags": [ "" ], "url_tracking_method": "broad", "ignore_sub_domains": true } } ] } ``` #### Responses ##### Status: 201 Add keywords to project or group ###### Content-Type: application/json - **`data`** `array` **Items:** - **`attributes`** `object` - **`auth`** `string` — Project auth key - **`best`** `integer | null` — Best ranking position since tracking started - **`category`** `string` — Project name - **`clicks`** `integer` — Average clicks from Google Search Console (-1 if not linked) - **`competition`** `number` — Competition metric from Google Ads - **`cpc`** `number` — Average cost per click in USD from Google Ads - **`crawled_at`** `integer | null` — Unix timestamp of last rank check - **`ctr`** `number` — Click-through rate from Google Search Console (-1 if not linked) - **`currency_symbol`** `string` — Currency symbol for CPC values (e.g. $, €) - **`gmb`** `string | null` — Google Business Profile name - **`gpage`** `integer | null` — Google results page number - **`grank`** `integer | string | null` — Current Google rank position. Returns \`"OTR"\` (Out of Range) when ranking beyond tracked SERP depth, or null while scraping is in progress. See \[Ranking Positions & Historical Data Explained]\(https\://support.keyword.com/en/articles/13701470-ranking-positions-historical-data-explained). - **`grank_int`** `integer` — Numeric rank value (0 if out of top results) - **`grankhistory`** `array` — Historical ranking positions **Items:** `integer` - **`has_featured`** `boolean` — Whether keyword has any featured snippets - **`has_featured_url`** `string` — URL ranking in the featured snippet, or empty string if none - **`ignore_featured`** `boolean` — Whether featured snippets are excluded from tracking - **`ignore_local`** `boolean` — Whether local listings are excluded from tracking - **`impressions`** `integer` — Impressions from Google Search Console (-1 if not linked) - **`in_featured`** `boolean` — Whether domain ranks in featured snippets - **`in_local_pack`** `boolean` — Whether ranking in local pack - **`included_in_sov`** `boolean` — Whether keyword is included in Share of Voice calculations - **`is_paginated`** `integer` — SERP pagination depth at which the ranking URL was found - **`isfav`** `boolean` — Whether keyword is marked as favorite - **`kw`** `string` — Keyword text - **`language`** `string` — Tracked language code - **`ms`** `integer` — Monthly search volume - **`near`** `string | null` — Location for local tracking - **`notes`** `string | null` - **`project_id`** `integer` - **`rankingurl`** `string` — URL currently ranking for this keyword - **`region`** `string` — Google region (e.g. google.com, google.co.uk) - **`search_intents`** `object` — Search intent probability scores (0-1) - **`commercial`** `number | null` - **`informational`** `number | null` - **`navigational`** `number | null` - **`transactional`** `number | null` - **`seocomp`** `integer | null` — Number of search results for this keyword - **`serp_features`** `object` — SERP features detected for this keyword (e.g. \`{"knowledge\_panel": 1, "video": 0}\`) - **`source`** `integer` — How keyword was added (1=API, 2=Suggestions, 3=Manual, 4=Bulk import) - **`start`** `integer | null` — Starting rank when keyword was first added - **`status`** `string`, possible values: `"EMPTY", "INACTIVE", "ACTIVE", "ARCHIVED"` - **`tag`** `string | null` — Legacy single-tag field; prefer the \`tags\` array - **`tags`** `array` **Items:** `string` - **`tags_count`** `integer` - **`trends`** `object` — Rank position changes. Values are integers, or \`"N/A"\` when data is unavailable. - **`day`** `integer | string` — Daily position change - **`life`** `integer | string` — Lifetime position change - **`month`** `integer | string` — Monthly position change - **`week`** `integer | string` — Weekly position change - **`type`** `string` — Device type (se=desktop, sem=mobile) - **`updated_at`** `string`, format: `date-time` — Last time keyword settings were changed - **`url`** `string` — Tracked domain or URL - **`url_tracking_method`** `string`, possible values: `"broad", "exact"` - **`id`** `string` — Unique keyword ID - **`type`** `string`, possible values: `"keyword"` **Example:** ```json { "data": [ { "type": "keyword", "id": "", "attributes": { "project_id": 1, "category": "", "url": "", "auth": "", "kw": "", "source": 1, "start": null, "notes": null, "tags_count": 1, "tags": [ "" ], "region": "", "language": "", "in_featured": true, "has_featured": true, "ignore_local": true, "ignore_featured": true, "url_tracking_method": "broad", "type": "", "gmb": null, "near": null, "isfav": true, "status": "EMPTY", "clicks": 1, "impressions": 1, "ctr": 1, "ms": 1, "competition": 1, "cpc": 1, "gpage": null, "serp_features": { "additionalProperty": 0 }, "grank": null, "grank_int": 1, "best": null, "seocomp": null, "in_local_pack": true, "rankingurl": "", "trends": { "day": 1, "week": 1, "month": 1, "life": 1 }, "updated_at": "", "crawled_at": null, "has_featured_url": "", "currency_symbol": "", "included_in_sov": true, "is_paginated": 1, "search_intents": { "commercial": null, "informational": null, "navigational": null, "transactional": null } } } ] } ``` ##### Status: 401 Authentication failed — invalid or missing API token ###### Content-Type: application/json - **`errors`** `array` **Items:** - **`code`** `string` — Application-specific error code - **`message`** `string` — Detailed error message - **`title`** `string` — Human-readable error summary **Example:** ```json { "errors": [ { "code": "", "title": "", "message": "" } ] } ``` ##### Status: 404 The requested resource was not found ###### Content-Type: application/json - **`errors`** `array` **Items:** - **`code`** `string` — Application-specific error code - **`message`** `string` — Detailed error message - **`title`** `string` — Human-readable error summary **Example:** ```json { "errors": [ { "code": "", "title": "", "message": "" } ] } ``` ### Get keyword - **Method:** `GET` - **Path:** `/api/v2/groups/{project_name}/keywords/{keyword_id}` - **Tags:** Keywords Use this call to retrieve all the keyword settings and ranking metrics for a single keyword. The keyword\_id is the unique identifier of the keyword, which is obtained after you add the keyword. **You can add the 'date' parameter to retrieve the ranking data for a specific date.** #### Responses ##### Status: 200 Retrieve single keyword data ###### Content-Type: application/json - **`data`** `object` - **`attributes`** `object` - **`auth`** `string` — Project auth key - **`best`** `integer | null` — Best ranking position since tracking started - **`category`** `string` — Project name - **`clicks`** `integer` — Average clicks from Google Search Console (-1 if not linked) - **`competition`** `number` — Competition metric from Google Ads - **`cpc`** `number` — Average cost per click in USD from Google Ads - **`crawled_at`** `integer | null` — Unix timestamp of last rank check - **`ctr`** `number` — Click-through rate from Google Search Console (-1 if not linked) - **`currency_symbol`** `string` — Currency symbol for CPC values (e.g. $, €) - **`gmb`** `string | null` — Google Business Profile name - **`gpage`** `integer | null` — Google results page number - **`grank`** `integer | string | null` — Current Google rank position. Returns \`"OTR"\` (Out of Range) when ranking beyond tracked SERP depth, or null while scraping is in progress. See \[Ranking Positions & Historical Data Explained]\(https\://support.keyword.com/en/articles/13701470-ranking-positions-historical-data-explained). - **`grank_int`** `integer` — Numeric rank value (0 if out of top results) - **`grankhistory`** `array` — Historical ranking positions **Items:** `integer` - **`has_featured`** `boolean` — Whether keyword has any featured snippets - **`has_featured_url`** `string` — URL ranking in the featured snippet, or empty string if none - **`ignore_featured`** `boolean` — Whether featured snippets are excluded from tracking - **`ignore_local`** `boolean` — Whether local listings are excluded from tracking - **`impressions`** `integer` — Impressions from Google Search Console (-1 if not linked) - **`in_featured`** `boolean` — Whether domain ranks in featured snippets - **`in_local_pack`** `boolean` — Whether ranking in local pack - **`included_in_sov`** `boolean` — Whether keyword is included in Share of Voice calculations - **`is_paginated`** `integer` — SERP pagination depth at which the ranking URL was found - **`isfav`** `boolean` — Whether keyword is marked as favorite - **`kw`** `string` — Keyword text - **`language`** `string` — Tracked language code - **`ms`** `integer` — Monthly search volume - **`near`** `string | null` — Location for local tracking - **`notes`** `string | null` - **`project_id`** `integer` - **`rankingurl`** `string` — URL currently ranking for this keyword - **`region`** `string` — Google region (e.g. google.com, google.co.uk) - **`search_intents`** `object` — Search intent probability scores (0-1) - **`commercial`** `number | null` - **`informational`** `number | null` - **`navigational`** `number | null` - **`transactional`** `number | null` - **`seocomp`** `integer | null` — Number of search results for this keyword - **`serp_features`** `object` — SERP features detected for this keyword (e.g. \`{"knowledge\_panel": 1, "video": 0}\`) - **`source`** `integer` — How keyword was added (1=API, 2=Suggestions, 3=Manual, 4=Bulk import) - **`start`** `integer | null` — Starting rank when keyword was first added - **`status`** `string`, possible values: `"EMPTY", "INACTIVE", "ACTIVE", "ARCHIVED"` - **`tag`** `string | null` — Legacy single-tag field; prefer the \`tags\` array - **`tags`** `array` **Items:** `string` - **`tags_count`** `integer` - **`trends`** `object` — Rank position changes. Values are integers, or \`"N/A"\` when data is unavailable. - **`day`** `integer | string` — Daily position change - **`life`** `integer | string` — Lifetime position change - **`month`** `integer | string` — Monthly position change - **`week`** `integer | string` — Weekly position change - **`type`** `string` — Device type (se=desktop, sem=mobile) - **`updated_at`** `string`, format: `date-time` — Last time keyword settings were changed - **`url`** `string` — Tracked domain or URL - **`url_tracking_method`** `string`, possible values: `"broad", "exact"` - **`id`** `string` — Unique keyword ID - **`type`** `string`, possible values: `"keyword"` **Example:** ```json { "data": { "type": "keyword", "id": "", "attributes": { "project_id": 1, "category": "", "url": "", "auth": "", "kw": "", "source": 1, "start": null, "notes": null, "tags_count": 1, "tags": [ "" ], "region": "", "language": "", "in_featured": true, "has_featured": true, "ignore_local": true, "ignore_featured": true, "url_tracking_method": "broad", "type": "", "gmb": null, "near": null, "isfav": true, "status": "EMPTY", "clicks": 1, "impressions": 1, "ctr": 1, "ms": 1, "competition": 1, "cpc": 1, "gpage": null, "serp_features": { "additionalProperty": 0 }, "grank": null, "grank_int": 1, "best": null, "seocomp": null, "in_local_pack": true, "rankingurl": "", "trends": { "day": 1, "week": 1, "month": 1, "life": 1 }, "updated_at": "", "crawled_at": null, "has_featured_url": "", "currency_symbol": "", "included_in_sov": true, "is_paginated": 1, "search_intents": { "commercial": null, "informational": null, "navigational": null, "transactional": null } } } } ``` ##### Status: 401 Authentication failed — invalid or missing API token ###### Content-Type: application/json - **`errors`** `array` **Items:** - **`code`** `string` — Application-specific error code - **`message`** `string` — Detailed error message - **`title`** `string` — Human-readable error summary **Example:** ```json { "errors": [ { "code": "", "title": "", "message": "" } ] } ``` ##### Status: 404 The requested resource was not found ###### Content-Type: application/json - **`errors`** `array` **Items:** - **`code`** `string` — Application-specific error code - **`message`** `string` — Detailed error message - **`title`** `string` — Human-readable error summary **Example:** ```json { "errors": [ { "code": "", "title": "", "message": "" } ] } ``` ### Delete keyword - **Method:** `DELETE` - **Path:** `/api/v2/groups/{project_name}/keywords/{keyword_id}` - **Tags:** Keywords * Use this call to delete keywords from a project or group. Note that this cannot be undone and when deleted you lose all historic ranking data. #### Responses ##### Status: 200 Delete single keyword ###### Content-Type: application/json - **`meta`** `object` - **`code`** `string`, format: `utc-millisec` - **`extra_data`** `array` **Items:** - **`title`** `string` **Example:** ```json { "meta": { "title": "", "code": "", "extra_data": [] } } ``` ##### Status: 401 Authentication failed — invalid or missing API token ###### Content-Type: application/json - **`errors`** `array` **Items:** - **`code`** `string` — Application-specific error code - **`message`** `string` — Detailed error message - **`title`** `string` — Human-readable error summary **Example:** ```json { "errors": [ { "code": "", "title": "", "message": "" } ] } ``` ##### Status: 404 The requested resource was not found ###### Content-Type: application/json - **`errors`** `array` **Items:** - **`code`** `string` — Application-specific error code - **`message`** `string` — Detailed error message - **`title`** `string` — Human-readable error summary **Example:** ```json { "errors": [ { "code": "", "title": "", "message": "" } ] } ``` ### Bulk delete keywords - **Method:** `DELETE` - **Path:** `/api/v2/projects/{project_id}/keywords` - **Tags:** Keywords #### Request Body ##### Content-Type: application/json - **`data` (required)** `object` - **`ids` (required)** `array` **Items:** `string` - **`type` (required)** `string`, possible values: `"keyword"` **Example:** ```json { "data": { "type": "keyword", "ids": [ "" ] } } ``` #### Responses ##### Status: 200 Keywords have been deleted successfully ###### Content-Type: application/json - **`meta`** `object` - **`title`** `string` **Example:** ```json { "meta": { "title": "" } } ``` ##### Status: 401 Authentication failed — invalid or missing API token ###### Content-Type: application/json - **`errors`** `array` **Items:** - **`code`** `string` — Application-specific error code - **`message`** `string` — Detailed error message - **`title`** `string` — Human-readable error summary **Example:** ```json { "errors": [ { "code": "", "title": "", "message": "" } ] } ``` ##### Status: 404 The requested resource was not found ###### Content-Type: application/json - **`errors`** `array` **Items:** - **`code`** `string` — Application-specific error code - **`message`** `string` — Detailed error message - **`title`** `string` — Human-readable error summary **Example:** ```json { "errors": [ { "code": "", "title": "", "message": "" } ] } ``` ### Update keywords - **Method:** `PATCH` - **Path:** `/api/v2/projects/{project_id}/keywords` - **Tags:** Keywords #### Request Body ##### Content-Type: application/json - **`data` (required)** `object` - **`attributes` (required)** `object` — Fields to update on the keywords - **`ignore_featured`** `boolean` - **`ignore_local`** `boolean` - **`language`** `string` - **`region`** `string` - **`tags`** `array` **Items:** `string` - **`type`** `string`, possible values: `"se", "sem"` - **`url`** `string` - **`url_tracking_method`** `string`, possible values: `"broad", "exact"` - **`ids` (required)** `array` — Keyword IDs to update **Items:** `string` - **`type` (required)** `string`, possible values: `"keyword"` **Example:** ```json { "data": { "ids": [ "" ], "type": "keyword", "attributes": { "url": "", "region": "", "language": "", "type": "se", "ignore_local": true, "ignore_featured": true, "url_tracking_method": "broad", "tags": [ "" ] } } } ``` #### Responses ##### Status: 200 Keywords updated successfully ###### Content-Type: application/json - **`data`** `object` - **`existingKeywordsCount`** `array` **Items:** - **`count`** `integer` - **`id`** `integer` - **`project_name`** `string` - **`meta`** `object` - **`code`** `string` - **`extra_data`** `object` - **`affected`** `integer` - **`duplicates`** `integer` - **`title`** `string` **Example:** ```json { "data": { "existingKeywordsCount": [ { "id": 1, "project_name": "", "count": 1 } ] }, "meta": { "title": "", "code": "", "extra_data": { "duplicates": 1, "affected": 1 } } } ``` ##### Status: 401 Authentication failed — invalid or missing API token ###### Content-Type: application/json - **`errors`** `array` **Items:** - **`code`** `string` — Application-specific error code - **`message`** `string` — Detailed error message - **`title`** `string` — Human-readable error summary **Example:** ```json { "errors": [ { "code": "", "title": "", "message": "" } ] } ``` ##### Status: 404 The requested resource was not found ###### Content-Type: application/json - **`errors`** `array` **Items:** - **`code`** `string` — Application-specific error code - **`message`** `string` — Detailed error message - **`title`** `string` — Human-readable error summary **Example:** ```json { "errors": [ { "code": "", "title": "", "message": "" } ] } ``` ### Refresh keywords - **Method:** `POST` - **Path:** `/api/v2/keywords/refresh` - **Tags:** Keywords Use this call to run an on demand update for all the keywords in a project or group. **Important Notes:** 1. The group name must follow the required naming convention and include \[sub] when submitting the request. 2. Ensure the parent project is created **before** adding groups to it. #### Request Body ##### Content-Type: application/json - **`data` (required)** `object` - **`project_ids` (required)** `array` — List of project IDs to refresh **Items:** `string` - **`include_sub_groups`** `boolean` — Whether to include keywords from sub-groups **Example:** ```json { "data": { "include_sub_groups": true, "project_ids": [ "" ] } } ``` #### Responses ##### Status: 200 On demand refresh of keywords in a single project ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "" } ``` ##### Status: 401 Authentication failed — invalid or missing API token ###### Content-Type: application/json - **`errors`** `array` **Items:** - **`code`** `string` — Application-specific error code - **`message`** `string` — Detailed error message - **`title`** `string` — Human-readable error summary **Example:** ```json { "errors": [ { "code": "", "title": "", "message": "" } ] } ``` ##### Status: 404 The requested resource was not found ###### Content-Type: application/json - **`errors`** `array` **Items:** - **`code`** `string` — Application-specific error code - **`message`** `string` — Detailed error message - **`title`** `string` — Human-readable error summary **Example:** ```json { "errors": [ { "code": "", "title": "", "message": "" } ] } ``` ### Get keyword metrics - **Method:** `GET` - **Path:** `/api/v2/groups/{project_name}/metrics` - **Tags:** Ranking Data ### GET /api/v2/groups/Disney/metrics This endpoint retrieves metrics for a specific group within a project. #### Request - Path Parameters - `project_name` (string, required): The name of the project. - Query Parameters - `tagId` (string, required): The ID of the tag. - `timeframe` (string, required): The time frame for the metrics. #### Response The response for this request follows the JSON schema below: ```json { "data": { "type": "", "id": "", "attributes": { "ranges": [ { "daily": { "count": 0, "change": 0, "status": "" }, "weekly": { "count": 0, "change": 0, "status": "" }, "monthly": { "count": 0, "change": 0, "status": "" }, "semester": { "count": 0, "change": 0, "status": "" }, "yearly": { "count": 0, "change": 0, "status": "" }, "life": { "count": 0, "change": 0, "status": "" }, "count": 0, "title": "" } ], "movements": { "daily": { "up": 0, "down": 0, "tie": 0 }, "weekly": { "up": 0, "down": 0, "tie": 0 }, "monthly": { "up": 0, "down": 0, "tie": 0 }, "semester": { "up": 0, "down": 0, "tie": 0 }, "yearly": { "up": 0, "down": 0, "tie": 0 }, "life": { "up": 0, "down": 0, "tie": 0 } }, "chart": null, "total": 0 } } } ``` #### Responses ##### Status: 200 Get keyword movement metrics for project, group or tag ###### Content-Type: application/json - **`data`** `object` - **`attributes`** `object` - **`chart`** `object | null` - **`movements`** `object` - **`daily`** `object` - **`down`** `integer` - **`tie`** `integer` - **`up`** `integer` - **`life`** `object` - **`down`** `integer` - **`tie`** `integer` - **`up`** `integer` - **`monthly`** `object` - **`down`** `integer` - **`tie`** `integer` - **`up`** `integer` - **`semester`** `object` - **`down`** `integer` - **`tie`** `integer` - **`up`** `integer` - **`weekly`** `object` - **`down`** `integer` - **`tie`** `integer` - **`up`** `integer` - **`yearly`** `object` - **`down`** `integer` - **`tie`** `integer` - **`up`** `integer` - **`ranges`** `array` **Items:** - **`count`** `integer` - **`daily`** `object` - **`change`** `integer` - **`count`** `integer` - **`status`** `string` - **`life`** `object` - **`change`** `integer` - **`count`** `integer` - **`status`** `string` - **`monthly`** `object` - **`change`** `integer` - **`count`** `integer` - **`status`** `string` - **`semester`** `object` - **`change`** `integer` - **`count`** `integer` - **`status`** `string` - **`title`** `string` - **`weekly`** `object` - **`change`** `integer` - **`count`** `integer` - **`status`** `string` - **`yearly`** `object` - **`change`** `integer` - **`count`** `integer` - **`status`** `string` - **`total`** `integer` - **`id`** `string` - **`type`** `string` **Example:** ```json { "data": { "type": "", "id": "", "attributes": { "ranges": [ { "daily": { "count": 1, "change": 1, "status": "" }, "weekly": { "count": 1, "change": 1, "status": "" }, "monthly": { "count": 1, "change": 1, "status": "" }, "semester": { "count": 1, "change": 1, "status": "" }, "yearly": { "count": 1, "change": 1, "status": "" }, "life": { "count": 1, "change": 1, "status": "" }, "count": 1, "title": "" } ], "movements": { "daily": { "up": 1, "down": 1, "tie": 1 }, "weekly": { "up": 1, "down": 1, "tie": 1 }, "monthly": { "up": 1, "down": 1, "tie": 1 }, "semester": { "up": 1, "down": 1, "tie": 1 }, "yearly": { "up": 1, "down": 1, "tie": 1 }, "life": { "up": 1, "down": 1, "tie": 1 } }, "chart": null, "total": 1 } } } ``` ##### Status: 401 Authentication failed — invalid or missing API token ###### Content-Type: application/json - **`errors`** `array` **Items:** - **`code`** `string` — Application-specific error code - **`message`** `string` — Detailed error message - **`title`** `string` — Human-readable error summary **Example:** ```json { "errors": [ { "code": "", "title": "", "message": "" } ] } ``` ##### Status: 404 The requested resource was not found ###### Content-Type: application/json - **`errors`** `array` **Items:** - **`code`** `string` — Application-specific error code - **`message`** `string` — Detailed error message - **`title`** `string` — Human-readable error summary **Example:** ```json { "errors": [ { "code": "", "title": "", "message": "" } ] } ``` ### Get rank history - **Method:** `POST` - **Path:** `/api/v2/keywords/chart` - **Tags:** Ranking Data Returns the daily ranking position for each specified keyword for the number of days prior to today. You can specify up to **180 days** of history using the limit query parameter. Rankings are grouped by keyword ID and domain and include both chart-compatible date formats (Date.UTC) and raw rank history with URLs. #### Request Body ##### Content-Type: application/json - **`kwid`** `array` **Items:** `string` **Example:** ```json { "kwid": [ "" ] } ``` #### Responses ##### Status: 200 Retrieve Ranking history for set number of days ###### Content-Type: application/json - **`data`** `array` **Items:** - **`data`** `array` **Items:** **Array of:** - **`data`** `array` **Items:** **Array of:** `string` - **`name`** `string` - **`domains`** `array` **Items:** `string` - **`kwid`** `integer` **Example:** ```json { "data": [ { "kwid": 1, "data": [ [ { "name": "", "data": [ [ "" ] ] } ] ], "domains": [ "" ] } ] } ``` ##### Status: 401 Authentication failed — invalid or missing API token ###### Content-Type: application/json - **`errors`** `array` **Items:** - **`code`** `string` — Application-specific error code - **`message`** `string` — Detailed error message - **`title`** `string` — Human-readable error summary **Example:** ```json { "errors": [ { "code": "", "title": "", "message": "" } ] } ``` ##### Status: 404 The requested resource was not found ###### Content-Type: application/json - **`errors`** `array` **Items:** - **`code`** `string` — Application-specific error code - **`message`** `string` — Detailed error message - **`title`** `string` — Human-readable error summary **Example:** ```json { "errors": [ { "code": "", "title": "", "message": "" } ] } ``` ### Get competitors - **Method:** `GET` - **Path:** `/api/v2/metrics/{project_name}/competitors/{keyword_id}/history` - **Tags:** Ranking Data #### Responses ##### Status: 200 Returns the top 100 competing URLs for a single keyword, including their rank position and result type (organic, featured snippet, etc.). ###### Content-Type: application/json - **`data`** `array` **Items:** - **`date`** `string` - **`rank`** `integer` - **`results`** `array` **Items:** - **`resultType`** `string` - **`title`** `string` - **`url`** `string` **Example:** ```json { "data": [ { "rank": 1, "results": [ { "resultType": "", "url": "", "title": "" } ], "date": "" } ] } ``` ##### Status: 401 Authentication failed — invalid or missing API token ###### Content-Type: application/json - **`errors`** `array` **Items:** - **`code`** `string` — Application-specific error code - **`message`** `string` — Detailed error message - **`title`** `string` — Human-readable error summary **Example:** ```json { "errors": [ { "code": "", "title": "", "message": "" } ] } ``` ##### Status: 404 The requested resource was not found ###### Content-Type: application/json - **`errors`** `array` **Items:** - **`code`** `string` — Application-specific error code - **`message`** `string` — Detailed error message - **`title`** `string` — Human-readable error summary **Example:** ```json { "errors": [ { "code": "", "title": "", "message": "" } ] } ``` ### List regions - **Method:** `GET` - **Path:** `/api/v2/groups/{project_name}/regions` - **Tags:** Ranking Data Use this call to get a list of all the regions your are tracking in this project with the count of number of keywords per region. **Important Notes:** 1. The group name must follow the required naming convention and include \[sub] when submitting the request. 2. Ensure the parent project is created **before** adding groups to it. #### Responses ##### Status: 200 Returns all Google regions being tracked in a project or group (subproject). ###### Content-Type: application/json - **`data`** `array` **Items:** - **`lang`** `string` - **`region`** `string` - **`total`** `integer` - **`type`** `string` **Example:** ```json { "data": [ { "region": "", "lang": "", "type": "", "total": 1 } ] } ``` ##### Status: 401 Authentication failed — invalid or missing API token ###### Content-Type: application/json - **`errors`** `array` **Items:** - **`code`** `string` — Application-specific error code - **`message`** `string` — Detailed error message - **`title`** `string` — Human-readable error summary **Example:** ```json { "errors": [ { "code": "", "title": "", "message": "" } ] } ``` ##### Status: 404 The requested resource was not found ###### Content-Type: application/json - **`errors`** `array` **Items:** - **`code`** `string` — Application-specific error code - **`message`** `string` — Detailed error message - **`title`** `string` — Human-readable error summary **Example:** ```json { "errors": [ { "code": "", "title": "", "message": "" } ] } ``` ### Get top pages - **Method:** `GET` - **Path:** `/api/v2/groups/{project_name}/keywords/ranking-urls` - **Tags:** Ranking Data #### Responses ##### Status: 200 Returns the top-performing pages for a project or group (subproject) based on keyword rankings. ###### Content-Type: application/json - **`data`** `array` **Items:** - **`average_cost_per_click`** `integer` - **`average_current_rank`** `integer` - **`average_previous_rank`** `integer` - **`current_ranking_url`** `string` - **`total_keyword_count`** `integer` - **`total_search_volume`** `integer` - **`links`** `object` - **`first`** `string` - **`last`** `string` - **`next`** `string` - **`prev`** `string` - **`meta`** `object` - **`current_page`** `integer` - **`from`** `integer` - **`last_page`** `integer` - **`path`** `string` - **`per_page`** `integer` - **`to`** `integer` - **`total`** `integer` **Example:** ```json { "data": [ { "current_ranking_url": "", "total_keyword_count": 1, "average_current_rank": 1, "average_previous_rank": 1, "total_search_volume": 1, "average_cost_per_click": 1 } ], "links": { "first": "", "last": "", "prev": "", "next": "" }, "meta": { "current_page": 1, "from": 1, "last_page": 1, "path": "", "per_page": 1, "to": 1, "total": 1 } } ``` ##### Status: 401 Authentication failed — invalid or missing API token ###### Content-Type: application/json - **`errors`** `array` **Items:** - **`code`** `string` — Application-specific error code - **`message`** `string` — Detailed error message - **`title`** `string` — Human-readable error summary **Example:** ```json { "errors": [ { "code": "", "title": "", "message": "" } ] } ``` ##### Status: 404 The requested resource was not found ###### Content-Type: application/json - **`errors`** `array` **Items:** - **`code`** `string` — Application-specific error code - **`message`** `string` — Detailed error message - **`title`** `string` — Human-readable error summary **Example:** ```json { "errors": [ { "code": "", "title": "", "message": "" } ] } ``` ### Get latest - **Method:** `GET` - **Path:** `/api/v2/metrics/{project_name}/mindshare/latest` - **Tags:** Share of Voice Get the top 10 domains for Share of Voice. #### Responses ##### Status: 200 Retrieve latest Top 10 results for Share of Voice ###### Content-Type: application/json - **`data`** `array` **Items:** - **`changes`** `object` - **`month`** `number` - **`clicks`** `number` - **`percentage`** `number` - **`title`** `string` - **`url`** `string` **Example:** ```json { "data": [ { "title": "", "url": "", "clicks": 1, "percentage": 1, "changes": { "month": 1 } } ] } ``` ##### Status: 401 Authentication failed — invalid or missing API token ###### Content-Type: application/json - **`errors`** `array` **Items:** - **`code`** `string` — Application-specific error code - **`message`** `string` — Detailed error message - **`title`** `string` — Human-readable error summary **Example:** ```json { "errors": [ { "code": "", "title": "", "message": "" } ] } ``` ##### Status: 404 The requested resource was not found ###### Content-Type: application/json - **`errors`** `array` **Items:** - **`code`** `string` — Application-specific error code - **`message`** `string` — Detailed error message - **`title`** `string` — Human-readable error summary **Example:** ```json { "errors": [ { "code": "", "title": "", "message": "" } ] } ``` ### Get history - **Method:** `GET` - **Path:** `/api/v2/projects/{project_id}/mindshare/from-cache` - **Tags:** Share of Voice Get share of Voice data for a range of time. The options you can use are 7 days, 30 days, 90 days, 180 days and 365 days. Depending on what day range you select, you will be presented with data like this: 7 days = Data points every 1 day for last 7 days;\ 30 days = Data point every 7 days for last 30 days;\ 90 days = Data point every 14 days for last 90 days;\ 180 days = Data point every 30 days for last 180 days;\ 365 days = Data point every 60 days for last 365 days; #### Responses ##### Status: 200 Returns Share of Voice data over the requested time range ###### Content-Type: application/json - **`data`** `object` - **`latest`** `array` — Most recent SoV snapshot **Items:** - **`clicks`** `number` - **`domain_exist_in_project`** `boolean` - **`percentage`** `number` - **`url`** `string` **Example:** ```json { "data": { "latest": [ { "url": "", "clicks": 1, "percentage": 1, "domain_exist_in_project": true } ], "additionalProperty": [ { "url": "", "clicks": 1, "percentage": 1 } ] } } ``` ##### Status: 401 Authentication failed — invalid or missing API token ###### Content-Type: application/json - **`errors`** `array` **Items:** - **`code`** `string` — Application-specific error code - **`message`** `string` — Detailed error message - **`title`** `string` — Human-readable error summary **Example:** ```json { "errors": [ { "code": "", "title": "", "message": "" } ] } ``` ##### Status: 404 The requested resource was not found ###### Content-Type: application/json - **`errors`** `array` **Items:** - **`code`** `string` — Application-specific error code - **`message`** `string` — Detailed error message - **`title`** `string` — Human-readable error summary **Example:** ```json { "errors": [ { "code": "", "title": "", "message": "" } ] } ``` ### List alerts - **Method:** `GET` - **Path:** `/api/v2/alerts` - **Tags:** Alerts Retrieves all the alerts present for your Keyword.com account #### Responses ##### Status: 200 Get all alerts for account ###### Content-Type: application/json - **`data`** `array` **Items:** - **`attributes`** `object` - **`category`** `string` - **`created_at`** `integer` - **`keyword_id`** `integer` - **`kw`** `string` - **`language`** `string` - **`ms`** `integer` - **`prevrank`** `integer` - **`read`** `boolean` - **`region`** `string` - **`result`** `integer` - **`time`** `string` - **`url`** `string` - **`id`** `string` - **`type`** `string` - **`links`** `object` - **`first`** `string` - **`last`** `string` - **`next`** `string` - **`self`** `string` - **`meta`** `object` - **`pagination`** `object` - **`count`** `integer` - **`current_page`** `integer` - **`per_page`** `integer` - **`total`** `integer` - **`total_pages`** `integer` **Example:** ```json { "data": [ { "type": "", "id": "", "attributes": { "category": "", "keyword_id": 1, "url": "", "kw": "", "ms": 1, "region": "", "language": "", "prevrank": 1, "result": 1, "time": "", "created_at": 1, "read": true } } ], "meta": { "pagination": { "total": 1, "count": 1, "per_page": 1, "current_page": 1, "total_pages": 1 } }, "links": { "self": "", "first": "", "next": "", "last": "" } } ``` ##### Status: 401 Authentication failed — invalid or missing API token ###### Content-Type: application/json - **`errors`** `array` **Items:** - **`code`** `string` — Application-specific error code - **`message`** `string` — Detailed error message - **`title`** `string` — Human-readable error summary **Example:** ```json { "errors": [ { "code": "", "title": "", "message": "" } ] } ``` ##### Status: 404 The requested resource was not found ###### Content-Type: application/json - **`errors`** `array` **Items:** - **`code`** `string` — Application-specific error code - **`message`** `string` — Detailed error message - **`title`** `string` — Human-readable error summary **Example:** ```json { "errors": [ { "code": "", "title": "", "message": "" } ] } ``` ### Get current user - **Method:** `GET` - **Path:** `/api/v2/users/self` - **Tags:** Account #### Responses ##### Status: 200 Returns user profile information including subscription details ###### Content-Type: application/json - **`data`** `object` - **`attributes`** `object` - **`access_level`** `string` - **`addon_master_disabled`** `boolean` - **`addon_master_email`** `string` - **`addon_restricted`** `boolean` - **`api_token`** `string` - **`contactnum`** `string` - **`contactnum_code`** `string` - **`country`** `string` - **`countrystate`** `string` - **`created_at`** `string` - **`created_at_ts`** `integer` - **`currency_code`** `string` - **`daily_added`** `object` - **`limit`** `integer` - **`remaining`** `integer` - **`used`** `integer` - **`disabled`** `boolean` - **`gsc_connected`** `boolean` - **`intercom_hash`** `string` - **`intercom_user_id`** `string` - **`is_free_plan`** `boolean` - **`is_not_stripe_user`** `boolean` - **`last_login_at`** `string` - **`name`** `string` - **`onboarding`** `boolean` - **`package`** `integer` - **`package_info`** `object` - **`title`** `string` - **`refreshes`** `object` - **`limit`** `integer` - **`remaining`** `integer` - **`used`** `integer` - **`serp_and_ranking_history_limit_date`** `string` - **`sharedcountapi`** `string` - **`showall`** `string` - **`trial_is_used`** `boolean` - **`used`** `integer` - **`user_id`** `integer` - **`user_is_restricted`** `boolean` - **`verified`** `integer` - **`id`** `string` - **`type`** `string` **Example:** ```json { "data": { "type": "", "id": "", "attributes": { "user_is_restricted": true, "onboarding": true, "verified": 1, "user_id": 1, "intercom_hash": "", "intercom_user_id": "", "name": "", "addon_master_email": "", "addon_master_disabled": true, "addon_restricted": true, "api_token": "", "showall": "", "sharedcountapi": "", "access_level": "", "gsc_connected": true, "used": 1, "package": 1, "refreshes": { "used": 1, "remaining": 1, "limit": 1 }, "daily_added": { "used": 1, "remaining": 1, "limit": 1 }, "contactnum": "", "contactnum_code": "", "country": "", "countrystate": "", "last_login_at": "", "created_at": "", "created_at_ts": 1, "disabled": true, "is_not_stripe_user": true, "is_free_plan": true, "currency_code": "", "serp_and_ranking_history_limit_date": "", "trial_is_used": true, "package_info": { "title": "" } } } } ``` ##### Status: 401 Authentication failed — invalid or missing API token ###### Content-Type: application/json - **`errors`** `array` **Items:** - **`code`** `string` — Application-specific error code - **`message`** `string` — Detailed error message - **`title`** `string` — Human-readable error summary **Example:** ```json { "errors": [ { "code": "", "title": "", "message": "" } ] } ``` ##### Status: 404 The requested resource was not found ###### Content-Type: application/json - **`errors`** `array` **Items:** - **`code`** `string` — Application-specific error code - **`message`** `string` — Detailed error message - **`title`** `string` — Human-readable error summary **Example:** ```json { "errors": [ { "code": "", "title": "", "message": "" } ] } ``` ## Schemas ### Error - **Type:**`object` * **`errors`** `array` **Items:** - **`code`** `string` — Application-specific error code - **`message`** `string` — Detailed error message - **`title`** `string` — Human-readable error summary **Example:** ```json { "errors": [ { "code": "", "title": "", "message": "" } ] } ``` ### Project - **Type:**`object` * **`attributes`** `object` - **`auth`** `string` — Project auth key for API access and ViewKey links - **`company_desc`** `string | null` - **`company_link`** `string | null` - **`company_logo`** `string | null` - **`company_name`** `string | null` - **`crawled_at`** `string | null`, format: `date-time` — Date and time of last keyword ranking refresh - **`currency_code`** `string` — Currency code for cost-related data (e.g. USD, GBP) - **`keywords_count`** `object` - **`ACTIVE`** `integer` — Number of active keywords - **`keywords_last_updated_at`** `string`, format: `date-time` — Last time keyword rankings were updated - **`name`** `string` — Project or group name - **`notes_count`** `integer` - **`password`** `string | null` — Password for shared ViewKey links - **`project_id`** `integer` — Unique identifier of the project or group - **`project_overview_settings`** `object` — Display configuration for project overview widgets - **`shortkey`** `string` — Short identifier used in shareable ViewKey URLs - **`sov_view_key`** `boolean` — Whether Share of Voice is visible in shared ViewKeys - **`tags`** `array` **Items:** - **`created_at`** `string`, format: `date-time` - **`id`** `integer` — Unique tag identifier - **`keywords_count`** `integer` — Number of keywords with this tag - **`name`** `string` — Tag name - **`project_id`** `integer` — Parent project or group ID - **`updated_at`** `string`, format: `date-time` - **`tags_count`** `integer` — Number of tags in the project or group - **`updated_at`** `string`, format: `date-time` - **`url`** `string | null` — Custom website URL for the project * **`id`** `string` — Project or group name. Groups include \`\[sub]\` in the name. * **`type`** `string`, possible values: `"group"` **Example:** ```json { "type": "group", "id": "", "attributes": { "project_id": 1, "auth": "", "name": "", "keywords_count": { "ACTIVE": 1 }, "tags_count": 1, "tags": [ { "id": 1, "project_id": 1, "name": "", "created_at": "", "updated_at": "", "keywords_count": 1 } ], "keywords_last_updated_at": "", "notes_count": 1, "updated_at": "", "password": null, "company_name": null, "company_desc": null, "company_link": null, "company_logo": null, "sov_view_key": true, "crawled_at": null, "currency_code": "", "url": null, "shortkey": "", "project_overview_settings": { "additionalProperty": { "visible": true, "order": 1 } } } } ``` ### Tag - **Type:**`object` * **`created_at`** `string`, format: `date-time` * **`id`** `integer` — Unique tag identifier * **`keywords_count`** `integer` — Number of keywords with this tag * **`name`** `string` — Tag name * **`project_id`** `integer` — Parent project or group ID * **`updated_at`** `string`, format: `date-time` **Example:** ```json { "id": 1, "project_id": 1, "name": "", "created_at": "", "updated_at": "", "keywords_count": 1 } ``` ### Keyword - **Type:**`object` * **`attributes`** `object` - **`auth`** `string` — Project auth key - **`best`** `integer | null` — Best ranking position since tracking started - **`category`** `string` — Project name - **`clicks`** `integer` — Average clicks from Google Search Console (-1 if not linked) - **`competition`** `number` — Competition metric from Google Ads - **`cpc`** `number` — Average cost per click in USD from Google Ads - **`crawled_at`** `integer | null` — Unix timestamp of last rank check - **`ctr`** `number` — Click-through rate from Google Search Console (-1 if not linked) - **`currency_symbol`** `string` — Currency symbol for CPC values (e.g. $, €) - **`gmb`** `string | null` — Google Business Profile name - **`gpage`** `integer | null` — Google results page number - **`grank`** `integer | string | null` — Current Google rank position. Returns \`"OTR"\` (Out of Range) when ranking beyond tracked SERP depth, or null while scraping is in progress. See \[Ranking Positions & Historical Data Explained]\(https\://support.keyword.com/en/articles/13701470-ranking-positions-historical-data-explained). - **`grank_int`** `integer` — Numeric rank value (0 if out of top results) - **`grankhistory`** `array` — Historical ranking positions **Items:** `integer` - **`has_featured`** `boolean` — Whether keyword has any featured snippets - **`has_featured_url`** `string` — URL ranking in the featured snippet, or empty string if none - **`ignore_featured`** `boolean` — Whether featured snippets are excluded from tracking - **`ignore_local`** `boolean` — Whether local listings are excluded from tracking - **`impressions`** `integer` — Impressions from Google Search Console (-1 if not linked) - **`in_featured`** `boolean` — Whether domain ranks in featured snippets - **`in_local_pack`** `boolean` — Whether ranking in local pack - **`included_in_sov`** `boolean` — Whether keyword is included in Share of Voice calculations - **`is_paginated`** `integer` — SERP pagination depth at which the ranking URL was found - **`isfav`** `boolean` — Whether keyword is marked as favorite - **`kw`** `string` — Keyword text - **`language`** `string` — Tracked language code - **`ms`** `integer` — Monthly search volume - **`near`** `string | null` — Location for local tracking - **`notes`** `string | null` - **`project_id`** `integer` - **`rankingurl`** `string` — URL currently ranking for this keyword - **`region`** `string` — Google region (e.g. google.com, google.co.uk) - **`search_intents`** `object` — Search intent probability scores (0-1) - **`commercial`** `number | null` - **`informational`** `number | null` - **`navigational`** `number | null` - **`transactional`** `number | null` - **`seocomp`** `integer | null` — Number of search results for this keyword - **`serp_features`** `object` — SERP features detected for this keyword (e.g. \`{"knowledge\_panel": 1, "video": 0}\`) - **`source`** `integer` — How keyword was added (1=API, 2=Suggestions, 3=Manual, 4=Bulk import) - **`start`** `integer | null` — Starting rank when keyword was first added - **`status`** `string`, possible values: `"EMPTY", "INACTIVE", "ACTIVE", "ARCHIVED"` - **`tag`** `string | null` — Legacy single-tag field; prefer the \`tags\` array - **`tags`** `array` **Items:** `string` - **`tags_count`** `integer` - **`trends`** `object` — Rank position changes. Values are integers, or \`"N/A"\` when data is unavailable. - **`day`** `integer | string` — Daily position change - **`life`** `integer | string` — Lifetime position change - **`month`** `integer | string` — Monthly position change - **`week`** `integer | string` — Weekly position change - **`type`** `string` — Device type (se=desktop, sem=mobile) - **`updated_at`** `string`, format: `date-time` — Last time keyword settings were changed - **`url`** `string` — Tracked domain or URL - **`url_tracking_method`** `string`, possible values: `"broad", "exact"` * **`id`** `string` — Unique keyword ID * **`type`** `string`, possible values: `"keyword"` **Example:** ```json { "type": "keyword", "id": "", "attributes": { "project_id": 1, "category": "", "url": "", "auth": "", "kw": "", "source": 1, "start": null, "notes": null, "tags_count": 1, "tags": [ "" ], "region": "", "language": "", "in_featured": true, "has_featured": true, "ignore_local": true, "ignore_featured": true, "url_tracking_method": "broad", "type": "", "gmb": null, "near": null, "isfav": true, "status": "EMPTY", "clicks": 1, "impressions": 1, "ctr": 1, "ms": 1, "competition": 1, "cpc": 1, "gpage": null, "serp_features": { "additionalProperty": 0 }, "grank": null, "grank_int": 1, "best": null, "seocomp": null, "in_local_pack": true, "rankingurl": "", "trends": { "day": 1, "week": 1, "month": 1, "life": 1 }, "updated_at": "", "crawled_at": null, "has_featured_url": "", "currency_symbol": "", "included_in_sov": true, "is_paginated": 1, "search_intents": { "commercial": null, "informational": null, "navigational": null, "transactional": null } } } ``` ### Pagination - **Type:**`object` * **`count`** `integer` * **`current_page`** `integer` * **`per_page`** `integer` * **`total`** `integer` * **`total_pages`** `integer` **Example:** ```json { "total": 1, "count": 1, "per_page": 1, "current_page": 1, "total_pages": 1 } ```