{ "openapi": "3.0.0", "info": { "title": "SEOmonitor API", "description": "`\nWe have now released the new `API 3.0`!\nIt comes with enhanced data coverage and organization, and easy-to-use documentation.\nThis version will continue to be functional, and you can use it alongside the new version, if needed.`", "version": "1.2" }, "components": { "securitySchemes": { "Authorization": { "type": "apiKey", "name": "Authorization", "in": "header" } } }, "servers": [ { "url" : "https://api.internal.seomonitor.com/api/v1.2", "description" : "SEOmonitor API" } ], "paths": { "/keyword_canibalization/{site_id}/{group_id}": { "get": { "security": [ { "Authorization": [] } ], "google_sheets": { "show": false }, "summary": "Keyword Canibalization", "description": "List of keywords with canibalization issues\n", "parameters": [ { "name": "site_id", "in": "path", "description": "The unique site identifier", "required": true, "type": "integer" }, { "name": "group_id", "in": "path", "description": "The unique group identifier. 0 for 'All keywords'", "required": true, "type": "integer" }, { "name": "start_date", "in": "path", "description": "Start Date", "required": false, "type": "integer" }, { "name": "end_date", "in": "path", "description": "End Date", "required": false, "type": "integer" } ], "tags": [ "Keyword Data" ], "responses": { "200": { "description": "An array of keywords", "schema": { "type": "array", "items": { } } }, "default": { "description": "Unexpected error", "schema": { "$ref": "#/definitions/Error" } } } } }, "/sites": { "get": { "security": [ { "Authorization": [] } ], "google_sheets": { "show": false }, "summary": "Sites", "description": "List of sites available in your account.\n", "tags": [ "Sites" ], "responses": { "200": { "description": "An array of sites", "schema": { "type": "array", "items": { "$ref": "#/definitions/Site" } } }, "default": { "description": "Unexpected error", "schema": { "$ref": "#/definitions/Error" } } } } }, "/on_target/{site_id}": { "get": { "security": [ { "Authorization": [] } ], "google_sheets": { "show": false }, "summary": "Forecast", "description": "Traffic forecast status.\n", "parameters": [ { "name": "site_id", "in": "path", "description": "The unique site identifier", "required": true, "type": "integer" } ], "tags": [ "Forecast" ], "responses": { "200": { "description": "", "schema": { "type": "array", "items": { "$ref": "#/definitions/ForecastExample" } } }, "default": { "description": "Unexpected error", "schema": { "$ref": "#/definitions/Error" } } } } }, "/on_target/by_dates/{site_id}": { "get": { "security": [ { "Authorization": [] } ], "google_sheets": { "show": true, "header": { "date": { "name": "Month", "format_rule": "format_date_month", "note": null, "colWidth": 65, "style_rule": "alignment_center" }, "real_traffic": { "name": "Actual \n Traffic", "format_rule": "format_number", "note": "This is the actual non-brand organic traffic for the forecasted months that already passed.", "colWidth": 90, "style_rule": "alignment_right" }, "inertial_traffic": { "name": "Est. Inertial \n Traffic", "format_rule": "format_number", "note": "The estimated monthly non-brand organic traffic if there's no SEO progress or decrease in the selected timeframe. The estimations are based on the current values and then extrapolated using the seasonality and trends of the keywords that generate the Forecast. \n \n This estimations are used to calculate the impact in non-brand organic traffic when the objective will be achieved.", "colWidth": 90, "style_rule": "alignment_right" }, "estimated_traffic": { "name": "Est. Improved \n Traffic", "format_rule": "format_number", "note": "This is the initial forecasted non-brand organic traffic (monthly), based on achieving the selected SEO goals in the chosen timeframe.", "colWidth": 100, "style_rule": "alignment_right" }, "estimated_additional_traffic": { "name": "Additional \n Traffic", "format_rule": "format_number", "note": "This is the monthly estimated impact of the targeted SEO progress. It is the difference between the estimated Improved Traffic and the estimated Inertial Traffic.", "colWidth": 90, "style_rule": "alignment_right" }, "search_volume": { "name": "Search \n Seasonality", "format_rule": "format_number", "note": "This is the total monthly Search Volume of the tracked keywords, which informs our forecasting algorithm on the search seasonality.", "colWidth": 90, "style_rule": "alignment_right" } }, "error": "There is no forecast set as objective. \n You can configure one here: https://app.seomonitor.com/param_0/forecast" }, "summary": "Objective/Forecast", "description": "It returns the forecast data for the set objective", "parameters": [ { "name": "site_id", "in": "path", "description": "The unique site identifier", "required": true, "type": "integer", "google_sheets": { "label": "Site" } } ], "tags": [ "Forecast" ], "responses": { "200": { "description": "It returns the traffic forecast data for the last 12 months for the selected website, such as: month, search volume, real traffic, estimated traffic and visibility score.", "schema": { "type": "array", "items": { "$ref": "#/definitions/ForecastExampleByDates" } } }, "default": { "description": "Unexpected error", "schema": { "$ref": "#/definitions/Error" } } } } }, "/keyword_groups/{site_id}/{date_start}/{date_end}": { "get": { "deprecated": true, "security": [ { "Authorization": [] } ], "google_sheets": { "show": false }, "summary": "Keyword Groups", "description": "DEPRECATED
\nUse groups_list and group_details instead.

\n\nThe details for the keyword groups for a specific site.\n
Warning: Group details are only available when providing the load_keyword_ids parameter with a value of 1.", "parameters": [ { "name": "site_id", "in": "path", "description": "The unique site identifier", "required": true, "type": "integer" }, { "name": "date_start", "in": "path", "description": "The start of the period. (Accepts date format as YYYY-mm-dd or relative like \"1 week ago\", \"3 months ago\", etc.)", "required": true, "type": "string", "format": "YYYY-mm-dd or relative" }, { "name": "date_end", "in": "path", "description": "The end of the period. (Accepts date format as YYYY-mm-dd or relative like \"now\", \"today\", etc.)", "required": true, "type": "string", "format": "YYYY-mm-dd or relative" }, { "name": "offset", "in": "query", "description": "By default, a request is limited to 1000 groups (or 10 if load_keywords_ids is active), if you want more you can set the offset", "type": "number" }, { "name": "limit", "in": "query", "description": "By default, a request is limited to 1000 groups (or 10 if load_keywords_ids is active). Use the limit parameter to change the number of results per request (max. 10 if load_keyword_ids is active)", "type": "number" }, { "name": "load_keyword_ids", "in": "query", "description": "Loads Keyword IDs in the keywords array if set to 1. When active, the response is limited to 10 groups", "type": "number" } ], "tags": [ "Groups" ], "responses": { "200": { "description": "An array of groups", "schema": { "type": "array", "items": { "$ref": "#/definitions/KeywordGroups" } } }, "default": { "description": "Unexpected error", "schema": { "$ref": "#/definitions/Error" } } } } }, "/groups_list/{site_id}": { "get": { "security": [ { "Authorization": [] } ], "google_sheets": { "show": false }, "summary": "Groups List", "description": "Group List.\n", "info": "It returns Group ID, Group name and Group type (normal or smart) for the selected website.", "parameters": [ { "name": "site_id", "in": "path", "description": "The unique site identifier", "required": true, "type": "integer", "google_sheets": { "label": "Site" } } ], "tags": [ "Groups" ], "responses": { "200": { "description": "It returns Group ID, Group name and Group type (normal or smart) for the selected website.", "schema": { "type": "array", "items": { "$ref": "#/definitions/GroupsList" } } }, "default": { "description": "Unexpected error", "schema": { "$ref": "#/definitions/Error" } } } } }, "/group_details/{site_id}/{group_id}/{date_start}/{date_end}": { "get": { "security": [ { "Authorization": [] } ], "google_sheets": { "show": true, "title_param": "group", "secondary_header": { "search_data": { "name": "SEARCH DATA", "columns": 4, "background_color": "#0c343d", "color": "#ffffff", "full_columns_color": false, "alignment": "left" }, "desktop_visibility": { "name": "DESKTOP VISIBILITY", "columns": 2, "background_color": "#4a86e8", "color": "#ffffff", "full_columns_color": "#ecf8ff", "alignment": "left" }, "mobile_visibility": { "name": "MOBILE VISIBILITY", "columns": 2, "background_color": "#6aa84f", "color": "#ffffff", "full_columns_color": "#eeffed", "alignment": "left" } }, "header": { "group_name": { "name": "Group", "colWidth": 250, "style_rule": "alignment_left" }, "kw_count": { "name": "Keywords", "format_rule": "format_number", "note": "Number of keywords in each group.", "colWidth": 75, "style_rule": "alignment_right" }, "search_volume": { "name": "Search \n Volume", "format_rule": "format_number", "colWidth": 80, "style_rule": "alignment_right" }, "yoy.value": { "name": "YoY \n Trend", "format_rule": "percent", "style_rule": "percent_sign, alignment_right", "note": "Year-over-Year search trend.", "colWidth": 65 }, "vscore_stop_desktop": { "name": "Visibility", "format_rule": "percent", "style_rule": "percent_round, alignment_right", "note": "The desktop Visibility in the last day of the timeframe.", "colWidth": 70 }, "desktop_performance_change": { "name": "Change", "format_rule": "percent", "style_rule": "sign_color_percent, bold, alignment_right", "note": "The performance-related change in desktop Visibility for the given timeframe. \n\n Read more about this here - https://help.seomonitor.com/en/articles/886067-understanding-changes-in-visibility", "colWidth": 65 }, "vscore_stop_mobile": { "name": "Visibility", "format_rule": "percent", "style_rule": "percent_round, alignment_right", "note": "The mobile Visibility in the last day of the timeframe.", "colWidth": 70 }, "mobile_performance_change": { "name": "Change", "format_rule": "percent", "style_rule": "sign_color_percent, bold, alignment_right", "note": "The performance-related change in mobile Visibility for the given timeframe. \n\n Read more about this here - https://help.seomonitor.com/en/articles/886067-understanding-changes-in-visibility", "colWidth": 65 } } }, "summary": "Group Performance", "description": "Returns the keyword count, the search volumes, the desktop and mobile visibility at the end of the period and the performance-related visibility changes for the timeframe.", "parameters": [ { "name": "site_id", "in": "path", "description": "The unique site identifier", "required": true, "type": "integer", "google_sheets": { "label": "Site" } }, { "name": "group_id", "in": "path", "description": "The group identifier", "required": true, "type": "integer", "google_sheets": { "label": "Group" } }, { "name": "date_start", "in": "path", "description": "The start of the period. (Accepts date format as YYYY-mm-dd or relative like \"1 week ago\", \"3 months ago\", etc.)", "required": true, "type": "string", "format": "YYYY-mm-dd or relative", "google_sheets": { "label": "Start Date" } }, { "name": "date_end", "in": "path", "description": "The end of the period. (Accepts date format as YYYY-mm-dd or relative like \"now\", \"today\", etc.)", "required": true, "type": "string", "format": "YYYY-mm-dd or relative", "google_sheets": { "label": "End Date" } } ], "tags": [ "Groups" ], "responses": { "200": { "description": "An array of groups", "schema": { "type": "array", "items": { "$ref": "#/definitions/GroupDetails" } } }, "default": { "description": "Unexpected error", "schema": { "$ref": "#/definitions/Error" } } } } }, "/all_group_details/{site_id}/{date_start}/{date_end}": { "get": { "security": [ { "Authorization": [] } ], "google_sheets": { "show": false }, "summary": "Group performance", "description": "Keywords details for all groups\n", "info": "It returns the group name, number of keywords, total search volume for the keywords, desktop and mobile visibility score at the start of the period, desktop and mobile visibility score at the end of the period and desktop and mobile visibility score performance change for all groups", "parameters": [ { "name": "site_id", "in": "path", "description": "The unique site identifier", "required": true, "type": "integer" }, { "name": "date_start", "in": "path", "description": "The start of the period. (Accepts date format as YYYY-mm-dd or relative like \"1 week ago\", \"3 months ago\", etc.)", "required": true, "type": "string", "format": "YYYY-mm-dd or relative" }, { "name": "date_end", "in": "path", "description": "The end of the period. (Accepts date format as YYYY-mm-dd or relative like \"now\", \"today\", etc.)", "required": true, "type": "string", "format": "YYYY-mm-dd or relative" } ], "tags": [ "Groups" ], "responses": { "200": { "description": "An array of groups", "schema": { "type": "array", "items": { "$ref": "#/definitions/AllGroupDetails" } } }, "default": { "description": "Unexpected error", "schema": { "$ref": "#/definitions/Error" } } } } }, "/keyword_data/{site_id}/{date_start}/{date_end}": { "get": { "security": [ { "Authorization": [] } ], "google_sheets": { "show": false }, "summary": "Keyword Data", "description": "All SEO Campaign section keywords details.\n", "info": "It returns the name, search volume, cost per click, date and time the keyword was added, landing page for desktop and mobile in google for the keyword for this site, total visits, bounces, conversions, conversion rate, conversions value, goals, goals rate, goals value, last position both desktop and mobile, the difference between the first position in the period and the last position in the period both desktop and mobile, visibility impact (similar to a weighted average) both desktop and mobile, the group the keyword is in and estimated additional traffic, revenue and AdWords cost once in Top 3", "parameters": [ { "name": "site_id", "in": "path", "description": "The unique site identifier", "required": true, "type": "integer" }, { "name": "date_start", "in": "path", "description": "The start of the period. (Accepts date format as YYYY-mm-dd or relative like \"1 week ago\", \"3 months ago\", etc.)", "required": true, "type": "string", "format": "YYYY-mm-dd or relative" }, { "name": "date_end", "in": "path", "description": "The end of the period. (Accepts date format as YYYY-mm-dd or relative like \"now\", \"today\", etc.)", "required": true, "type": "string", "format": "YYYY-mm-dd or relative" }, { "name": "offset", "in": "query", "description": "By default a request is limited to 1000 rows, if you want more you can set the offset", "type": "number" }, { "name": "keyword_name", "in": "query", "description": "The keyword name you wish to retrieve data for", "required": false, "type": "string" } ], "tags": [ "Keyword Data" ], "responses": { "200": { "description": "An array of keywords details", "schema": { "type": "array", "items": { "$ref": "#/definitions/KeywordData" } } }, "default": { "description": "Unexpected error", "schema": { "$ref": "#/definitions/Error" } } } } }, "/keyword_data/{site_id}/{group_id}/{date_start}/{date_end}": { "get": { "security": [ { "Authorization": [] } ], "google_sheets": { "show": true, "title_param": "group", "lockColumns": 4, "lockRows": 4, "sort": 2, "secondary_header": { "search_data": { "name": "SEARCH DATA", "columns": 4, "background_color": "#0c343d", "color": "#ffffff", "full_columns_color": false, "alignment": "left" }, "desktop_ranking_data": { "name": "DESKTOP RANKING DATA", "columns": 4, "background_color": "#4a86e8", "color": "#ffffff", "full_columns_color": "#ecf8ff", "alignment": "left" }, "mobile_ranking_data": { "name": "MOBILE RANKING DATA", "columns": 4, "background_color": "#6aa84f", "color": "#ffffff", "full_columns_color": "#eeffed", "alignment": "left" }, "traffic_data": { "name": "TRAFFIC DATA", "columns": 5, "background_color": "#1c4587", "color": "#ffffff", "full_columns_color": false, "alignment": "left" }, "opportunity": { "name": "OPPORTUNITY", "columns": 3, "background_color": "#351c75", "color": "#ffffff", "full_columns_color": false, "alignment": "left" }, "other": { "name": "OTHER", "columns": 4, "background_color": "#000000", "color": "#ffffff", "full_columns_color": false, "alignment": "left" } }, "header": { "keyword_data.name": { "name": "Keyword", "note": "Keyword Name", "format_rule": "", "style_rule": "alignment_left", "colWidth": 155 }, "keyword_data.average_search_volume": { "name": "Search \n Volume", "note": "Monthly searches on the keyword.", "format_rule": "format_number", "style_rule": "alignment_right", "colWidth": 65 }, "keyword_data.yoy": { "name": "YOY \n Trend", "note": "Year-over-Year search trend.", "format_rule": "percent", "style_rule": "percent_round, alignment_right", "colWidth": 55 }, "keyword_data.average_cpc": { "name": "CPC", "note": "Cost Per Click", "format_rule": "number_two_decimal", "style_rule": "alignment_right", "colWidth": 55 }, "position": { "name": "Rank", "note": "The desktop rank in the last day of the timeframe.", "format_rule": "max_99", "style_rule": "alignment_right", "colWidth": 55 }, "position_trend": { "name": "Change", "note": "The change in desktop rank for the given timeframe.", "format_rule": "", "style_rule": "sign_color, bold, alignemnt_right", "colWidth": 55 }, "visibility_impact_desktop": { "name": "Visibility \n Impact", "note": "The impact of this keyword's rank change in the desktop Visibility change for the given timeframe. \n\n Read more about the performance-related Visibility changes here - https://help.seomonitor.com/en/articles/886067-understanding-changes-in-visibility", "format_rule": "", "style_rule": "sign_color, alignment_right", "colWidth": 65 }, "keyword_data.landing_page": { "name": "Landing Page", "format_rule": "landing_page", "style_rule": "alignment_left", "note": "The ranking landing page in the desktop search.", "colWidth": 130 }, "position_mobile": { "name": "Rank", "format_rule": "max_99", "style_rule": "alignment_right", "note": "The mobile rank in the last day of the timeframe.", "colWidth": 55 }, "position_trend_mobile": { "name": "Change", "format_rule": "", "style_rule": "sign_color, bold, alignment_right", "note": "The change in mobile rank for the given timeframe.", "colWidth": 55 }, "visibility_impact_mobile": { "name": "Visibility \n Impact", "format_rule": "", "style_rule": "sign_color, alignment_right", "note": "The impact of this keyword's rank change in the mobile Visibility change for the given timeframe. \n\n Read more about the performance-related Visibility changes here - https://help.seomonitor.com/en/articles/886067-understanding-changes-in-visibility", "colWidth": 65 }, "keyword_data.landing_page_mobile": { "name": "Landing Page", "format_rule": "landing_page", "style_rule": "alignment_left", "note": "The ranking landing page in the mobile search.", "colWidth": 130 }, "visits": { "name": "Sessions", "format_rule": "format_number", "style_rule": "alignment_right", "note": "Non-brand organic visits on the keyword, for the given timeframe.", "colWidth": 65 }, "bounces": { "name": "Bounces", "note": "Percentage of single-page sessions.", "format_rule": "format_number", "style_rule": "alignment_right", "colWidth": 65 }, "conversions_goals": { "name": "Conversions", "note": "Number of completed goals, based on the Analytics selection.", "format_rule": "format_number", "style_rule": "alignment_right", "colWidth": 87 }, "conversions_goals_rate": { "name": "Conv. \n Rate", "note": "Percentage of Conversions resulting from the organic sessions.", "format_rule": "number_two_decimal", "style_rule": "alignment_right", "colWidth": 45 }, "revenue_value": { "name": "Revenue/ \n Value", "note": "Percentage of single-page sessions.", "format_rule": "format_number", "style_rule": "alignment_right", "colWidth": 70 }, "keyword_data.top_10_difficulty": { "name": "Top 10 \n Difficulty", "format_rule": "", "style_rule": "alignment_right", "note": "The difficulty for the landing page to reach Top 10.", "colWidth": 75 }, "keyword_data.opportunity": { "name": "Opportunity", "note": "The effort necessary to reach the top versus the monthly estimated value (revenue) generated after that.", "format_rule": "", "style_rule": "alignment_right", "colWidth": 80 }, "keyword_data.lables_warning": { "name": "Labels & \n Warnings", "format_rule": "", "style_rule": "alignment_left", "note": "Helpful labels and/or warnings automatically added to the keyword.", "colWidth": 95 }, "group_name": { "name": "Groups", "note": "Groups in which the keyword is present.", "format_rule": "", "style_rule": "alignment_left", "colWidth": 75 }, "keyword_data.date_added": { "name": "Date Added", "format_rule": "format_date", "style_rule": "alignment_center", "note": "The date when the keyword started being tracked in the campaign.", "colWidth": 80 }, "keyword_data.main_keyword_id": { "name": "Main Keyword ID", "format_rule": "", "style_rule": "alignment_center", "colWidth": 60 }, "keyword_data.close_variation": { "name": "Close Variation", "format_rule": "", "style_rule": "alignment_center", "note": "If the keyword is a close variation of other keyword.", "colWidth": 80 } } }, "summary": "Keyword Performance", "description": "Returns all keyword data including ranking performance on both devices in the selected timeframe.", "parameters": [ { "name": "site_id", "in": "path", "description": "The unique site identifier", "required": true, "type": "integer", "google_sheets": { "label": "Site" } }, { "name": "group_id", "in": "path", "description": "Group id. For Brand folder you can use `brand` as value for group id", "required": true, "type": "integer", "google_sheets": { "label": "Group" } }, { "name": "date_start", "in": "path", "description": "The start of the period. (Accepts date format as YYYY-mm-dd or relative like \"1 week ago\", \"3 months ago\", etc.)", "required": true, "type": "string", "format": "YYYY-mm-dd or relative", "google_sheets": { "label": "Start Date" } }, { "name": "date_end", "in": "path", "description": "The end of the period. (Accepts date format as YYYY-mm-dd or relative like \"now\", \"today\", etc.)", "required": true, "type": "string", "format": "YYYY-mm-dd or relative", "google_sheets": { "label": "End Date" } }, { "name": "offset", "in": "query", "description": "By default, a request is limited to 1000 rows. If you need to get more, you can set an offset, accordingly (an offset of 1000 will provide the following 1000 rows). \n For example, if you need rows 3000-4000, you would set the offset at 3000.", "type": "number", "google_sheets": { "hide": true, "label": "Offset" } }, { "name": "keyword_name", "in": "query", "description": "The keyword (name, not ID) you need data for.", "required": false, "type": "string", "google_sheets": { "label": "Keyword Filter", "placeholder": "Enter Keyword" } } ], "tags": [ "Keyword Data" ], "responses": { "200": { "description": "Keyword details for a specific group.", "schema": { "type": "array", "items": { "$ref": "#/definitions/KeywordData" } } }, "default": { "description": "Unexpected error", "schema": { "$ref": "#/definitions/Error" } } } } }, "/ranks/{site_id}/{date_start}/{date_end}": { "get": { "security": [ { "Authorization": [] } ], "google_sheets": { "show": false }, "summary": "Ranks", "description": "Desktop and mobile ranks\n", "info": "It returns both desktop and mobile position for each date in your selected interval", "parameters": [ { "name": "site_id", "in": "path", "description": "The unique site identifier", "required": true, "type": "integer" }, { "name": "date_start", "in": "path", "description": "The start of the period. (Accepts date format as YYYY-mm-dd or relative like \"1 week ago\", \"3 months ago\", etc.)", "required": true, "type": "string", "format": "YYYY-mm-dd or relative" }, { "name": "date_end", "in": "path", "description": "The end of the period. (Accepts date format as YYYY-mm-dd or relative like \"now\", \"today\", etc.)", "required": true, "type": "string", "format": "YYYY-mm-dd or relative" }, { "name": "offset", "in": "query", "description": "By default a rank request is limited to 100 keywords, if you want the next 100 keywords you can set the offset", "type": "number" }, { "name": "limit", "in": "query", "description": "If this field is not set, default value is 100.If this field is set, allowed values are between 100 and 1000", "type": "number" } ], "tags": [ "Ranks" ], "responses": { "200": { "description": "An array of positions grouped by keyword", "schema": { "type": "array", "items": { "$ref": "#/definitions/Ranks" } } }, "default": { "description": "Unexpected error", "schema": { "$ref": "#/definitions/Error" } } } } }, "/ranks/{site_id}/{date_start}/{date_end}/{group_id}": { "get": { "security": [ { "Authorization": [] } ], "google_sheets": { "show": true, "title_param": "group", "lockColumns": 2, "lockRows": 4, "sort": 2, "header": { "keyword_data.name": { "name": "Keyword", "style_rule": "alignment_left", "note": "Keyword name.", "colWidth": 180 }, "keyword_data.search_volume": { "name": "Search \n Volume", "format_rule": "format_number", "style_rule": "alignment_right", "note": "Monthly searches on the keyword.", "colWidth": 65 } }, "secondary_header": { "date": { "name": "DATE:", "columns": 2, "background_color": "#b7e1cd", "color": "#000", "full_columns_color": false, "alignment": "center" } } }, "summary": "Keywords Ranks", "description": "Returns both desktop and mobile ranks for each day in the selected interval, filtered by group.", "info": "It returns both desktop and mobile position for each date in your selected interval filtered by group", "parameters": [ { "name": "site_id", "in": "path", "description": "The unique site identifier", "required": true, "type": "integer", "google_sheets": { "label": "Site" } }, { "name": "group_id", "in": "path", "description": "The unique group identifier", "required": true, "type": "string", "format": "integer", "google_sheets": { "label": "Group" } }, { "name": "date_start", "in": "path", "description": "The start of the period. (Accepts date format as YYYY-mm-dd or relative like \"1 week ago\", \"3 months ago\", etc.)", "required": true, "type": "string", "format": "YYYY-mm-dd or relative", "google_sheets": { "label": "Start Date" } }, { "name": "date_end", "in": "path", "description": "The end of the period. (Accepts date format as YYYY-mm-dd or relative like \"now\", \"today\", etc.)", "required": true, "type": "string", "format": "YYYY-mm-dd or relative", "google_sheets": { "label": "End Date" } }, { "name": "offset", "in": "query", "description": "By default, a rank request is limited to 100 keywords. If you need to get more, you can set an offset, accordingly (an offset of 100 will provide the following 100 keywords). \n For example, if you need keywords 300-400, you would set the offset at 300.", "type": "number", "google_sheets": { "label": "Offset", "placeholder": "Offset" } }, { "name": "limit", "in": "query", "description": "If this field is not set, default value is 100.If this field is set, allowed values are between 100 and 1000", "type": "number", "google_sheets": { "label": "Limit", "placeholder": "Limit" } } ], "tags": [ "Ranks" ], "responses": { "200": { "description": "An array of positions grouped by keyword", "schema": { "type": "array", "items": { "$ref": "#/definitions/Ranks" } } }, "default": { "description": "Unexpected error", "schema": { "$ref": "#/definitions/Error" } } } } }, "/organic_traffic/{site_id}/{date_start}/{date_end}": { "get": { "security": [ { "Authorization": [] } ], "google_sheets": { "show": true, "header": { "date": { "name": "Date", "format_rule": "format_date", "style_rule": "alignment_center" }, "visits_non_brand": { "name": "Sessions", "format_rule": "format_number", "note": "Non-brand organic sessions.", "style_rule": "alignment_right" }, "goals_conversions_non_brand": { "name": "Conversions", "format_rule": "format_number", "note": "Conversions generated by the non-brand organic sessions.", "style_rule": "alignment_right" }, "conversion_rate_non_brand": { "name": "Conv. Rate", "format_rule": "percent", "note": "Percentage of conversions generated by the non-brand organic sessions.", "style_rule": "alignment_right, percent" }, "goals_conversions_value_non_brand": { "name": "Conv. Value", "format_rule": "format_number", "note": "Revenue generated by the non-brand conversions.", "style_rule": "alignment_right" }, "visits_brand": { "name": "Sessions", "format_rule": "format_number", "note": "Branded organic sessions.", "style_rule": "alignment_right" }, "goals_conversions_brand": { "name": "Conversions", "format_rule": "format_number", "note": "Conversions generated by the brand organic sessions.", "style_rule": "alignment_right" }, "conversion_rate_brand": { "name": "Conv. Rate", "format_rule": "percent", "note": "Percentage of conversions generated by the branded organic sessions.", "style_rule": "alignment_right, percent" }, "goals_conversions_value_brand": { "name": "Conv. Value", "format_rule": "format_number", "note": "Revenue generated by the branded conversions.", "style_rule": "alignment_right" } }, "secondary_header": { "date": { "name": "", "columns": 1, "background_color": "#b7e1cd", "color": "#000", "full_columns_color": false, "alignment": "center" }, "non_branded": { "name": "NON-BRANDED:", "columns": 4, "background_color": "#b7e1cd", "color": "#000", "full_columns_color": false, "alignment": "center" }, "branded": { "name": "BRANDED:", "columns": 4, "background_color": "#b7e1cd", "color": "#000", "full_columns_color": false, "alignment": "center" } } }, "summary": "Organic Traffic Performance", "description": "Returns the sessions, conversions, conversion rates and conversion values, split by brand and non-brand, for each day in the selected interval.", "info": "It returns the visits, conversion rate (e-commerce), goals rate, revenue (e-commerce), goals revenue and date for brand and non-brand.", "parameters": [ { "name": "site_id", "in": "path", "description": "The unique site identifier", "required": true, "type": "integer", "google_sheets": { "label": "Site" } }, { "name": "date_start", "in": "path", "description": "The start of the period. (Accepts date format as YYYY-mm-dd or relative like \"1 week ago\", \"3 months ago\", etc.)", "required": true, "type": "string", "format": "YYYY-mm-dd or relative", "google_sheets": { "label": "Start Date" } }, { "name": "date_end", "in": "path", "description": "The end of the period. (Accepts date format as YYYY-mm-dd or relative like \"now\", \"today\", etc.)", "required": true, "type": "string", "format": "YYYY-mm-dd or relative", "google_sheets": { "label": "End Date" } } ], "tags": [ "Organic Traffic" ], "responses": { "200": { "description": "An array of Organic Traffic statistics grouped by date", "schema": { "type": "array", "items": { "$ref": "#/definitions/OrganicTraffic" } } }, "default": { "description": "Unexpected error", "schema": { "$ref": "#/definitions/Error" } } } } }, "/organic_traffic/split/{site_id}/{date_start}/{date_end}": { "get": { "security": [ { "Authorization": [] } ], "google_sheets": { "show": false }, "summary": "Organic Traffic", "description": "Organic Traffic split by brand/non-brand.\n", "info": "It returns the visits, conversion rate (e-commerce), goals rate, revenue (e-commerce), goals revenue, date and type for brand, non-brand or both.", "parameters": [ { "name": "site_id", "in": "path", "description": "The unique site identifier", "required": true, "type": "integer", "google_sheets": { "label": "Site" } }, { "name": "date_start", "in": "path", "description": "The start of the period. (Accepts date format as YYYY-mm-dd or relative like \"1 week ago\", \"3 months ago\", etc.)", "required": true, "type": "string", "format": "YYYY-mm-dd or relative", "google_sheets": { "label": "Start Date" } }, { "name": "date_end", "in": "path", "description": "The end of the period. (Accepts date format as YYYY-mm-dd or relative like \"now\", \"today\", etc.)", "required": true, "type": "string", "format": "YYYY-mm-dd or relative", "google_sheets": { "label": "End Date" } }, { "name": "type", "in": "query", "description": "Possible values: brand | non-brand.", "type": "string", "google_sheets": { "label": "Type", "options": { "type": "select", "options": { "Both": "", "Brand": "brand", "Non-brand": "non-brand" } } } } ], "tags": [ "Organic Traffic" ], "responses": { "200": { "description": "An array of Organic Traffic statistics grouped by date", "schema": { "type": "array", "items": { "$ref": "#/definitions/OrganicTrafficSplit" } } }, "default": { "description": "Unexpected error", "schema": { "$ref": "#/definitions/Error" } } } } }, "/content/{site_id}/{date_start}/{date_end}": { "get": { "security": [ { "Authorization": [] } ], "google_sheets": { "show": false, "header": { "date": { "name": "Date", "note": "Publishing date for the linking article.", "format_rule": "format_date", "style_rule": "alignment_center", "colWidth": 85 }, "title": { "name": "Article Title", "note": "Title of the linking article.", "style_rule": "alignment_left", "colWidth": 205 }, "article_url": { "name": "URL", "note": "Full linking article URL.", "style_rule": "alignment_left", "colWidth": 205 }, "source": { "name": "Source", "note": "Source domain for the linking article.", "style_rule": "alignment_left", "colWidth": 110 }, "social.facebook": { "name": "Facebook", "note": "Facebook signals count.", "style_rule": "alignment_right", "colWidth": 70 }, "visits": { "name": "Sessions", "note": "Sessions generated by the linking article.", "style_rule": "alignment_right", "colWidth": 75 }, "conversions": { "name": "Conversions", "note": "Conversions generated by the linking article.", "style_rule": "alignment_right", "colWidth": 90 }, "conversions_value": { "name": "Conv. \n Value", "note": "Revenue generated by the linking article.", "style_rule": "alignment_right", "colWidth": 55 }, "landing_pages.url": { "name": "URL", "note": "Landing page linked in the article.", "format_rule": "landing_page", "style_rule": "alignment_left, clip", "colWidth": 170 }, "landing_pages.keywords": { "name": "Keywords", "note": "Tracked keywords pointing to the landing page linked in the article.", "style_rule": "alignment_left", "colWidth": 150 }, "landing_pages.search_volume": { "name": "Search \n Volume", "note": "Total search volume for the tracked keywords pointing to the landing pages linked in the article.", "style_rule": "alignment_right", "colWidth": 60 }, "landing_pages.visibility_score": { "name": "Visibility", "note": "Visibility score of the linked landing page, in the last day of the interval.", "format_rule": "percent", "style_rule": "alignment_right, percent", "colWidth": 65 }, "landing_pages.visibility_score_change": { "name": "Visibility \n Change", "note": "Visibility score trend for the linked landing page, between the first and the last day of the interval.", "format_rule": "percent", "style_rule": "sign_color_percent, alignment_right", "colWidth": 65 } }, "secondary_header": { "limking_article": { "name": "LINKING ARTICLE", "columns": 5, "background_color": "#1c4587", "color": "#fff", "full_columns_color": false, "alignment": "left" }, "generated_traffic": { "name": "GENERATED TRAFFIC:", "columns": 3, "background_color": "#274e13", "color": "#fff", "full_columns_color": false, "alignment": "left" }, "linked_landing_page": { "name": "LINKED LANDING PAGE:", "columns": 5, "background_color": "#20124d", "color": "#fff", "full_columns_color": false, "alignment": "left" } } }, "summary": "Content Performance", "description": "Returns all the content performance data in the selected timeframe", "tags": [ "Content Performance" ], "parameters": [ { "name": "site_id", "in": "path", "description": "The unique site identifier", "required": true, "type": "integer", "google_sheets": { "label": "Site" } }, { "name": "date_start", "in": "path", "description": "The start of the period. (Accepts date format as YYYY-mm-dd or relative like \"1 week ago\", \"3 months ago\", etc.)", "required": true, "type": "string", "google_sheets": { "label": "Start Date" } }, { "name": "date_end", "in": "path", "description": "The end of the period. (Accepts date format as YYYY-mm-dd or relative like \"now\", \"today\", etc.)", "required": true, "type": "string", "google_sheets": { "label": "End Date" } }, { "name": "offset", "in": "query", "description": "By default, a request is limited to 1000 rows. If you need to get more, you can set an offset, accordingly (an offset of 1000 will provide the following 1000 rows). \n For example, if you need rows 3000-4000, you would set the offset at 3000.", "required": false, "type": "integer", "google_sheets": { "label": "Offset", "placeholder": "Offset" } } ], "responses": { "200": { "description": "List of articles associated to your site", "schema": { "type": "array", "items": { "$ref": "#/definitions/Content" } } }, "default": { "description": "Unexpected error", "schema": { "$ref": "#/definitions/Error" } } } } }, "/keyword_serp/{site_id}": { "get": { "security": [ { "Authorization": [] } ], "google_sheets": { "show": true, "title_param": "keyword, device", "header": { "position": { "name": "Rank", "format_rule": "", "style_rule": "alignment_right", "colWidth": 45 }, "site": { "name": "Site", "format_rule": "", "style_rule": "alignment_left", "note": "Ranking domain.", "colWidth": 180 }, "full_lp": { "name": "URL", "format_rule": "", "style_rule": "alignment_left", "note": "LP that the domain is ranking for.", "colWidth": 180 } } }, "summary": "Keyword Competitors", "description": "Returns the top 100 ranking domains and URLs, for the given keyword.", "parameters": [ { "name": "site_id", "in": "path", "description": "The unique site identifier", "required": true, "type": "integer", "google_sheets": { "label": "Site" } }, { "name": "keyword_name", "in": "query", "description": "The keyword name", "required": true, "type": "string", "google_sheets": { "label": "Keyword", "placeholder": "Keyword" } }, { "name":"query_end_date", "in":"query", "description": "The end of the period. (Accepts date format as YYYY-mm-dd or relative like \"now\", \"today\", etc.)", "required": true, "type": "string", "google_sheets": { "label": "End Date" } }, { "name": "mobile", "in": "query", "description": "Check to retrieve mobile landing pages.", "type": "number", "google_sheets": { "label": "Mobile", "options": { "type": "checkbox", "default": 0 } } } ], "tags": [ "Keyword SERP" ], "responses": { "200": { "description": "An array of landing pages", "schema": { "type": "array", "items": { "$ref": "#/definitions/KeywordSERP" } } }, "default": { "description": "Unexpected error", "schema": { "$ref": "#/definitions/Error" } } } } }, "/visibility_score_data/{site_id}/{group_id}/{date_start}/{date_end}": { "get": { "security": [ { "Authorization": [] } ], "google_sheets": { "show": true, "header": { "date": { "name": "Date", "format_rule": "format_date", "style_rule": "alignment_center", "colWidth": 85 }, "vscore": { "name": "Visibility", "note": "Daily group Visibility on selected device.", "format_rule": "percent", "style_rule": "percent, alignment_right", "colWidth": 65 }, "annotations": { "name": "Annotations", "format_rule": "annotation", "note": "Annotations present on the Visibility graph.", "style_rule": "alignment_left", "colWidth": 230 } } }, "summary": "Daily Visibility", "description": "Returns the Visibility for mobile or desktop for each day in the selected interval, with any annotation present on the Visibility graph, correspondingly.", "parameters": [ { "name": "site_id", "in": "path", "description": "The unique site identifier", "required": true, "type": "integer", "google_sheets": { "label": "Site" } }, { "name": "group_id", "in": "path", "description": "The unique group identifier", "required": true, "type": "integer", "google_sheets": { "label": "Group" } }, { "name": "date_start", "in": "path", "description": "The start of the period. (Accepts date format as YYYY-mm-dd or relative like \"1 week ago\", \"3 months ago\", etc.)", "required": true, "type": "string", "google_sheets": { "label": "Start Date" } }, { "name": "date_end", "in": "path", "description": "The end of the period. (Accepts date format as YYYY-mm-dd or relative like \"now\", \"today\", etc.)", "required": true, "type": "string", "google_sheets": { "label": "End Date" } }, { "name": "device", "in": "query", "description": "Device value. If it's not provided, default value is 1 (desktop). Get all devices from "/devices" endpoint. Possible values: 1 or 2", "required": false, "type": "integer", "google_sheets": { "label": "Device", "options": { "type": "select", "options": { "Desktop": 1, "Mobile": 2 } } } } ], "tags": [ "Visibility Score" ], "responses": { "200": { "description": "An array containing dates and visibility scores for each date", "schema": { "type": "array", "items": { "$ref": "#/definitions/VisibilityScoreData" } } }, "default": { "description": "Unexpected error", "schema": { "$ref": "#/definitions/Error" } } } } }, "/visibility_score/{site_id}/{group_id}/{date_start}/{date_end}": { "get": { "deprecated": true, "security": [ { "Authorization": [] } ], "google_sheets": { "show": false }, "summary": "Visibility scores", "description": "DEPRECATED
\nUse /compare/competitors/visibility_score instead.

\n\nVisibility scores for group.\n", "parameters": [ { "name": "site_id", "in": "path", "description": "The unique site identifier", "required": true, "type": "integer", "google_sheets": { "label": "Site" } }, { "name": "group_id", "in": "path", "description": "The unique group identifier", "required": true, "type": "integer", "google_sheets": { "label": "Group" } }, { "name": "date_start", "in": "path", "description": "The start of the period. (Accepts date format as YYYY-mm-dd or relative like \"1 week ago\", \"3 months ago\", etc.)", "required": true, "type": "string", "google_sheets": { "label": "Start Date" } }, { "name": "date_end", "in": "path", "description": "The end of the period. (Accepts date format as YYYY-mm-dd or relative like \"now\", \"today\", etc.)", "required": true, "type": "string", "google_sheets": { "label": "End Date" } } ], "tags": [ "Visibility Score" ], "responses": { "200": { "description": "An array of visibility scores", "schema": { "type": "array", "items": { "$ref": "#/definitions/VisibilityScore" } } }, "default": { "description": "Unexpected error", "schema": { "$ref": "#/definitions/Error" } } } } }, "/compare/keywords/{site_id}/{start_date}/{end_date}/{competitors}": { "get": { "security": [ { "Authorization": [] } ], "google_sheets": { "show": false }, "tags": [ "Compare" ], "summary": "Get competitors keywords", "description": "Get competitors keywords.\n", "info": "It returns the keyword, average CPC, YOY, position and position change of each requested competitor.", "parameters": [ { "name": "site_id", "in": "path", "description": "The unique site identifier", "required": true, "type": "integer", "google_sheets": { "label": "Site" } }, { "name": "start_date", "in": "path", "description": "The start of the period. (Relative date)", "required": true, "type": "string", "google_sheets": { "label": "Start Date" } }, { "name": "end_date", "in": "path", "description": "The end of the period. (Relative date)", "required": true, "type": "string", "google_sheets": { "label": "End Date" } }, { "name": "competitors", "in": "path", "description": "Maximum 10 competitors, separated by comma.", "required": true, "type": "string", "google_sheets": { "label": "Competitors" } }, { "name": "offset", "in": "query", "description": "By default a request is limited to 1000 rows, if you want more you can set the offset", "type": "number", "google_sheets": { "label": "Offset", "placeholder": "Offset" } } ], "responses": { "200": { "description": "Competition data for keywords", "schema": { "type": "object", "$ref": "#/definitions/CompareKeywords" } }, "default": { "description": "Unexpected error", "schema": { "$ref": "#/definitions/Error" } } } } }, "/compare/keywords/{site_id}/{start_date}/{end_date}/{competitors}/{group_id}": { "get": { "security": [ { "Authorization": [] } ], "google_sheets": { "show": true, "title_param": "group, device", "lockColumns": 4, "lockRows": 4, "header": { "name": { "name": "Keyword", "note": null, "style_rule": "alignment_left", "colWidth": 180 }, "search_volume": { "name": "Search \n Volume", "format_rule": "format_number", "note": "Monthly searches on the keyword.", "style_rule": "alignment_right", "colWidth": 65 }, "avg_cpc": { "name": "CPC", "note": "Cost Per Click", "style_rule": "alignment_right", "colWidth": 80 }, "yoy": { "name": "YoY \n Trend", "note": "Year-over-Year search trend.", "format_rule": "percent", "style_rule": "percent_sign, alignment_right", "colWidth": 60 } }, "secondary_header": { "search_data": { "name": "SEARCH DATA", "columns": 4, "background_color": "#38761d", "color": "#fff", "full_columns_color": false, "alignment": "left" } } }, "tags": [ "Compare" ], "summary": "Competitors' Rankings", "description": "Returns the keyword search and ranking data for the requested competitors in the selected timeframe.", "parameters": [ { "name": "site_id", "in": "path", "description": "The unique site identifier", "required": true, "type": "integer", "google_sheets": { "label": "Site" } }, { "name": "start_date", "in": "path", "description": "The start of the period. (Relative date)", "required": true, "type": "string", "google_sheets": { "label": "Start Date" } }, { "name": "end_date", "in": "path", "description": "The end of the period. (Relative date)", "required": true, "type": "string", "google_sheets": { "label": "End Date" } }, { "name": "competitors", "in": "path", "description": "Maximum 10 competitors, separated by comma.", "required": true, "type": "string", "google_sheets": { "label": "Competitors", "placeholder": "Competitors" } }, { "name": "group_id", "in": "path", "description": "Group id from /groups_list/{site_id}. If it's not provided, default group is 'All keywords'", "required": false, "type": "string", "google_sheets": { "label": "Group" } }, { "name": "device", "in": "query", "description": "Check to retrieve mobile data.", "type": "number", "google_sheets": { "label": "Device", "options": { "type": "select", "options": { "Desktop": 1, "Mobile": 2 } } } }, { "name": "offset", "in": "query", "description": "By default, a request is limited to 1000 rows. If you need to get more, you can set an offset, accordingly (an offset of 1000 will provide the following 1000 rows). \n For example, if you need rows 3000-4000, you would set the offset at 3000.", "type": "number", "google_sheets": { "label": "Offset", "placeholder": "Offset" } } ], "responses": { "200": { "description": "Competition data for keywords", "schema": { "type": "object", "$ref": "#/definitions/CompareKeywords" } }, "default": { "description": "Unexpected error", "schema": { "$ref": "#/definitions/Error" } } } } }, "/compare/competitors/visibility_score/{site_id}/{start_date}/{end_date}": { "get": { "security": [ { "Authorization": [] } ], "google_sheets": { "show": false, "header": { "date": { "name": "Date", "format_rule": "format_date" } } }, "tags": [ "Compare" ], "summary": "Get competitors visibility score", "description": "Get competitors visibility score.\n", "info": "It returns the visibility score of you and the requested competitors segmented by dates", "parameters": [ { "name": "site_id", "in": "path", "description": "The unique site identifier", "required": true, "type": "integer", "google_sheets": { "label": "Site" } }, { "name": "start_date", "in": "path", "description": "The start of the period. (Relative date)", "required": true, "type": "string", "google_sheets": { "label": "Start Date" } }, { "name": "end_date", "in": "path", "description": "The end of the period. (Relative date)", "required": true, "type": "string", "google_sheets": { "label": "End Date" } }, { "name": "group_id", "in": "query", "description": "Group id from /groups_list/{site_id}. If it's not provided, default group is "All keywords". Use comma for multiple groups (Eg: group_id_1,group_id_2) ", "required": false, "type": "string", "google_sheets": { "label": "Group" } }, { "name": "competitors", "in": "query", "description": "Maximum 10 competitors, separated by comma.", "required": false, "type": "string", "google_sheets": { "label": "Copetitors" } }, { "name": "device", "in": "query", "description": "Device value. If it's not provided, default value is 1 (desktop). Get all devices from "/devices" endpoint. Possible values: 1 or 2", "required": false, "type": "integer", "google_sheets": { "label": "Device", "options": { "type": "select", "options": { "Desktop": 1, "Mobile": 2 } } } } ], "responses": { "200": { "description": "An array with all marked as \"default over all groups\" in competitors and their visibility score on interval [startDate - endDate ]", "schema": { "type": "object", "$ref": "#/definitions/CompareCompetitorsResponse" } }, "default": { "description": "Unexpected error", "schema": { "$ref": "#/definitions/Error" } } } } }, "/compare/competitors/visibility_score/{site_id}/{start_date}/{end_date}/{competitors}/{group_id}": { "get": { "security": [ { "Authorization": [] } ], "google_sheets": { "show": true, "title_param": "group", "lockColumns": 2, "lockRows": 3, "header": { "date": { "name": "Date", "format_rule": "format_date", "style_rule": "alignment_center", "colWidth": 90 }, "annotations": { "name": "Annotations", "format_rule": "annotation", "style_rule": "alignment_left", "colWidth": 180, "note": "Annotations present on the Visibility graph." } } }, "tags": [ "Compare" ], "summary": "Competitors' Daily visibility", "description": "Returns the Visibility for each day in the selected interval, with any annotation present on the Visibility graph, correspondingly, for you and each of the requested competitors.", "info": "It returns the visibility score of you and the requested competitors segmented by dates, filtered by group", "parameters": [ { "name": "site_id", "in": "path", "description": "The unique site identifier", "required": true, "type": "integer", "google_sheets": { "label": "Site" } }, { "name": "start_date", "in": "path", "description": "The start of the period. (Relative date)", "required": true, "type": "string", "google_sheets": { "label": "Start Date" } }, { "name": "end_date", "in": "path", "description": "The end of the period. (Relative date)", "required": true, "type": "string", "google_sheets": { "label": "End Date" } }, { "name": "competitors", "in": "path", "description": "Maximum 10 competitors, separated by comma.", "required": true, "type": "string", "google_sheets": { "label": "Competitors", "placeholder": "Enter competitors" } }, { "name": "group_id", "in": "path", "description": "Group id from /groups_list/{site_id}. If it's not provided, default group is "All keywords" ", "required": false, "type": "string", "google_sheets": { "label": "Group" } }, { "name": "device", "in": "query", "description": "Device value. If it's not provided, default value is 1 (desktop). Get all devices from "/devices" endpoint. Possible values: 1 or 2", "required": false, "type": "integer", "google_sheets": { "label": "Device", "options": { "type": "select", "options": { "Desktop": 1, "Mobile": 2 } } } } ], "responses": { "200": { "description": "An array with all competitors and their visibility score on interval [startDate - endDate ]", "schema": { "type": "object", "$ref": "#/definitions/CompareCompetitorsResponse" } }, "default": { "description": "Unexpected error", "schema": { "$ref": "#/definitions/Error" } } } } }, "/devices": { "get": { "security": [ { "Authorization": [] } ], "google_sheets": false, "tags": [ "Devices" ], "summary": "Get all devices", "description": "Get all devices.\n", "responses": { "200": { "description": "Result with all devices", "schema": { "type": "object" } } } } } }, "definitions": { "Site": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique identifier representing a specific site" }, "name": { "type": "string", "description": "Name of site" }, "url": { "type": "string", "description": "Url of the Site" }, "owner": { "type": "string", "description": "The owner of the site (the email address)" }, "date": { "type": "string", "description": "The date the site was added" }, "localized": { "type": "string", "description": "Location name (if localized)" }, "localized_canonical": { "type": "string", "description": "Canonical location name (if localized)" }, "pitching": { "type": "integer", "description": "Possible values: 0 (site is not pitching)/1 (site is pitching)." } } }, "ForecastExample": { "type": "object", "properties": { "manual": { "type": "string", "description": "Last updated forecast (if it's manual)" }, "real": { "type": "integer", "description": "Real traffic" }, "estimated": { "type": "integer", "description": "Estimated traffic" }, "on_target": { "type": "integer", "description": "On target percent" }, "type": { "type": "string", "description": "Forecast type: Visibility/Traffic" } } }, "ForecastExampleByDates": { "type": "object", "properties": { "date": { "type": "string", "google_sheets": { "show": true, "header_name": "Date" } }, "search_volume": { "type": "integer", "google_sheets": { "show": true, "header_name": "Search Volume", "format_rule": "number" } }, "real_traffic": { "type": "integer", "google_sheets": { "show": true, "header_name": "Real Traffic" } }, "estimated_traffic": { "type": "integer", "google_sheets": { "show": true, "header_name": "Estimated Traffic" } }, "visibility_score": { "type": "string", "google_sheets": { "show": true, "header_name": "Visibility Score" } } } }, "KeywordGroups": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier representing a specific group" }, "name": { "type": "string", "description": "The name of the group" }, "is_smart": { "type": "boolean", "description": "If the group is defined by a smart rule" }, "kw_count": { "type": "integer", "description": "The number of keywords in the group for the selected period" }, "search_volume": { "type": "number", "description": "The total search volume for the keywords in the group for the selected period" }, "vscore_start": { "type": "number", "description": "The desktop visibility score at the start of the period" }, "vscore_end": { "type": "number", "description": "The desktop visibility score at the end of the period" }, "vscore_start_mobile": { "type": "number", "description": "The mobile visibility score at the start of the period" }, "vscore_end_mobile": { "type": "number", "description": "The mobile visibility score at the end of the period" }, "keywords": { "type": "array", "items": { "$ref": "#/definitions/KeywordGroupsKIDS" }, "description": "List of Keyword IDs (when load_keyword_ids is active)" } } }, "GroupsList": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier representing a specific group", "google_sheets": { "show": true, "header_name": "Group ID" } }, "name": { "type": "string", "description": "The name of the group", "google_sheets": { "show": true, "header_name": "Group Name" } }, "is_smart": { "type": "boolean", "description": "If the group is defined by a smart rule", "google_sheets": { "show": true, "header_name": "Group Type", "format_rule": "boolean_to_string" } } } }, "GroupDetails": { "type": "object", "properties": { "kw_count": { "type": "integer", "description": "The number of keywords in the group for the selected period", "google_sheets": { "show": true, "header_name": "Keyword Count" } }, "search_volume": { "type": "number", "description": "The total search volume for the keywords in the group for the selected period", "google_sheets": { "show": true, "header_name": "Search Volume" } }, "vscore_start_desktop": { "type": "number", "description": "The desktop visibility score at the start of the period", "google_sheets": { "show": true, "header_name": "Desktop Visibility Score Start Date", "format_rule": "number_two_decimal" } }, "vscore_stop_desktop": { "type": "number", "description": "The desktop visibility score at the end of the period", "google_sheets": { "show": true, "header_name": "Desktop Visibility Score End Date", "format_rule": "number_two_decimal" } }, "vscore_start_mobile": { "type": "number", "description": "The mobile visibility score at the start of the period", "google_sheets": { "show": true, "header_name": "Mobile Visibility Score Start Date", "format_rule": "number_two_decimal" } }, "vscore_stop_mobile": { "type": "number", "description": "The mobile visibility score at the end of the period", "google_sheets": { "show": true, "header_name": "Mobile Visibility Score End Date", "format_rule": "number_two_decimal" } }, "desktop_performance_change": { "type": "number", "description": "The desktop visibility score performance change", "google_sheets": { "show": true, "header_name": "Desktop Visibility Score Change" } }, "mobile_performance_change": { "type": "number", "description": "The mobile visibility score performance change", "google_sheets": { "show": true, "header_name": "Mobile Visibility Score Change" } }, "keywords": { "type": "array", "items": { "$ref": "#/definitions/KeywordGroupsKIDS" }, "description": "List of Keyword IDs (when load_keyword_ids is active)", "google_sheets": { "show": false } } } }, "AllGroupDetails": { "type": "object", "properties": { "group_name": { "type": "string", "description": "Group name", "google_sheets": { "show": true, "header_name": "Group Name" } }, "kw_count": { "type": "integer", "description": "The number of keywords in the group for the selected period", "google_sheets": { "show": true, "header_name": "Keyword Count" } }, "search_volume": { "type": "number", "description": "The total search volume for the keywords in the group for the selected period", "google_sheets": { "show": true, "header_name": "Search Volume" } }, "vscore_start_desktop": { "type": "number", "description": "The desktop visibility score at the start of the period", "google_sheets": { "show": true, "header_name": "Desktop Visibility Score Start Date", "format_rule": "number_two_decimal" } }, "vscore_stop_desktop": { "type": "number", "description": "The desktop visibility score at the end of the period", "google_sheets": { "show": true, "header_name": "Desktop Visibility Score End Date", "format_rule": "number_two_decimal" } }, "vscore_start_mobile": { "type": "number", "description": "The mobile visibility score at the start of the period", "google_sheets": { "show": true, "header_name": "Mobile Visibility Score Start Date", "format_rule": "number_two_decimal" } }, "vscore_stop_mobile": { "type": "number", "description": "The mobile visibility score at the end of the period", "google_sheets": { "show": true, "header_name": "Mobile Visibility Score End Date", "format_rule": "number_two_decimal" } }, "desktop_performance_change": { "type": "number", "description": "The desktop visibility score performance change", "google_sheets": { "show": true, "header_name": "Desktop Visibility Score Change" } }, "mobile_performance_change": { "type": "number", "description": "The mobile visibility score performance change", "google_sheets": { "show": true, "header_name": "Mobile Visibility Score Change" } }, "keywords": { "type": "array", "items": { "$ref": "#/definitions/KeywordGroupsKIDS" }, "description": "List of Keyword IDs (when load_keyword_ids is active)", "google_sheets": { "show": false } } } }, "KeywordGroupsKIDS": { "type": "integer" }, "KeywordData": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier representing a specific keyword", "google_sheets": { "show": true, "header_name": "Keyword ID" } }, "visits": { "type": "number", "description": "Total visits for the selected period", "google_sheets": { "show": true, "header_name": "Visits" } }, "bounces": { "type": "number", "description": "Total bounces for the selected period", "google_sheets": { "show": true, "header_name": "Bounces" } }, "conversions": { "type": "number", "description": "Total conversions (e-commerce) for the selected period", "google_sheets": { "show": true, "header_name": "Conversions" } }, "conversions_rate": { "type": "number", "description": "Total conversion rate (e-commerce) for the selected period", "google_sheets": { "show": true, "header_name": "Conversion Rate" } }, "conversions_value": { "type": "number", "description": "Total conversions value (e-commerce) for the selected period", "google_sheets": { "show": true, "header_name": "Conversion Value" } }, "goals": { "type": "number", "description": "Total goals for the selected period", "google_sheets": { "show": true, "header_name": "Goals" } }, "goals_rate": { "type": "number", "description": "Total goals rate for the selected period", "google_sheets": { "show": true, "header_name": "Goals Rate" } }, "goals_value": { "type": "number", "description": "Total goals value for the selected period", "google_sheets": { "show": true, "header_name": "Goals Value" } }, "position": { "type": "number", "description": "Last position in the selected period", "google_sheets": { "show": true, "header_name": "Keyword Position" } }, "position_trend": { "type": "number", "description": "The difference between the first position in the period and the last position in the period", "google_sheets": { "show": true, "header_name": "Position Trend" } }, "position_mobile": { "type": "number", "description": "Last position (mobile devices) in the selected period", "google_sheets": { "show": true, "header_name": "Mobile Position" } }, "position_trend_mobile": { "type": "number", "description": "The difference between the first position in the period and the last position in the period (mobile devices)", "google_sheets": { "show": true, "header_name": "Mobile Position Trend" } }, "visibility_impact_desktop": { "type": "number", "description": "Visibility impact - similar to a weighted average; Use case: sorting the keywords by their impact in the Visibility Score", "google_sheets": { "show": true, "header_name": "Desktop Visibility Impact" } }, "visibility_impact_mobile": { "type": "number", "description": "Visibility impact - similar to a weighted average; Use case: sorting the keywords by their impact in the Visibility Score (mobile devices)", "google_sheets": { "show": true, "header_name": "Mobile Visibility Impact" } }, "group_name": { "type": "string", "description": "The name of the group the keyword is in", "google_sheets": { "show": true, "header_name": "Group Name" } }, "keyword_data": { "type": "object", "description": "Specific keyword data", "google_sheets": { "show": true, "drill_down": true, "header_name": "Keyword Data" }, "properties": { "name": { "type": "string", "description": "The keyword name", "google_sheets": { "show": true, "header_name": "Keyword" } }, "average_search_volume": { "type": "number", "description": "The avereage search volume", "google_sheets": { "show": true, "header_name": "Keyword Average Search Volume" } }, "average_cpc": { "type": "number", "description": "The avereage cost per click", "google_sheets": { "show": true, "header_name": "Keyword Average Cost per Click" } }, "date_added": { "type": "string", "description": "The date and time the keyword was added", "google_sheets": { "show": true, "header_name": "Keyword Date Added" } }, "landing_page": { "type": "string", "description": "The landing page for desktop devices", "google_sheets": { "show": true, "header_name": "Desktop Landing Page" } }, "landing_page_mobile": { "type": "string", "description": "The landing page for mobile devices", "google_sheets": { "show": true, "header_name": "Mobile Landing Page" } } } }, "est_additional_visits": { "type": "number", "description": "Estimated additional traffic once in Top 3", "google_sheets": { "show": true, "header_name": "Estimated Additional Traffic" } }, "est_additional_revenue": { "type": "number", "description": "Estimated additional revenue once in Top 3", "google_sheets": { "show": true, "header_name": "Estimated Additional Revenue" } }, "est_adwords_cost": { "type": "number", "description": "Estimated AdWords cost for the additional visits once in Top 3", "google_sheets": { "show": true, "header_name": "Estimated AdWords Cost" } } } }, "Ranks": { "type": "array", "items": { "type": "object", "properties": { "keyword_data": { "type": "object", "description": "The keyword details", "properties": { "id": { "type": "number", "description": "Unique identifer for keyword" } } }, "positions": { "type": "object", "description": "The positions for deskop devices for the dates in the interval selected(when available).\n The positions can go up to 100, 101 means that the keyword was not found in the first 10 google pages", "properties": { "date(YY-mm-dd)": { "type": "string", "additionalProperties": { "type": "integer" } } } }, "positions_mobile": { "type": "object", "description": "The positions for mobile devices for the dates in the interval selected(when available).\n The positions can go up to 100, 101 means that the keyword was not found in the first 10 google pages", "properties": { "date(YY-mm-dd)": { "type": "string", "additionalProperties": { "type": "integer" } } } } } }, "properties": { "keyword_data": { "type": "object", "description": "Specific keyword data", "google_sheets": { "show": true, "drill_down": true, "header_name": "Keyword Data" }, "properties": { "name": { "type": "string", "description": "The keyword name", "google_sheets": { "show": true, "header_name": "Keyword" } }, "id": { "type": "string", "description": "The keyword ID", "google_sheets": { "show": true, "header_name": "Keyword ID" } } } }, "positions": { "type": "object", "description": "Desktop Positions", "google_sheets": { "show": true, "drill_down": true, "header_name": "Desktop Positions" }, "properties": { "date": { "type": "string", "additionalProperties": { "type": "integer" }, "google_sheets": { "show": true, "header_name": "Desktop Positions" } } } }, "positions_mobile": { "type": "object", "description": "Mobile Positions", "google_sheets": { "show": true, "drill_down": true, "header_name": "Mobile Positions" }, "properties": { "date": { "type": "string", "additionalProperties": { "type": "integer" }, "google_sheets": { "show": true, "header_name": "Mobile Positions" } } } } } }, "OrganicTraffic": { "type": "object", "properties": { "visits_brand": { "type": "number", "description": "The brand visits", "google_sheets": { "show": true, "header_name": "Brand Visits" } }, "visits_non_brand": { "type": "number", "description": "The non brand visits", "google_sheets": { "show": true, "header_name": "Non-Brand Visits" } }, "conversions_rate_brand": { "type": "number", "description": "The conversion rate (e-commerce) for brand", "google_sheets": { "show": true, "header_name": "Brand Conversion Rate" } }, "conversions_rate_non_brand": { "type": "number", "description": "The conversion rate (e-commerce) for non-brand", "google_sheets": { "show": true, "header_name": "Non-Brand Visits" } }, "goals_rate_brand": { "type": "number", "description": "The goals rate for brand", "google_sheets": { "show": true, "header_name": "Brand Goals Rate" } }, "goals_rate_non_brand": { "type": "number", "description": "The goals rate for non-brand", "google_sheets": { "show": true, "header_name": "Non-Brand Goal Rate" } }, "conversions_value_brand": { "type": "number", "description": "The revenue (e-commerce) for brand", "google_sheets": { "show": true, "header_name": "Brand Revenue" } }, "conversions_value_non_brand": { "type": "number", "description": "The revenue (e-commerce) for non-brand", "google_sheets": { "show": true, "header_name": "Non-Brand Revenue" } }, "goals_conversions_value_brand": { "type": "number", "description": "The goals revenue for brand", "google_sheets": { "show": true, "header_name": "Brand Goals Revenue" } }, "goals_conversions_value_non_brand": { "type": "number", "description": "The goals revenue for non-brand", "google_sheets": { "show": true, "header_name": "Non-Brand Goals Revenue" } }, "date": { "type": "string", "description": "Date format(Y-m-d)", "google_sheets": { "show": true, "header_name": "Date" } } } }, "OrganicTrafficSplit": { "type": "object", "properties": { "visits": { "type": "number", "description": "Visits for brand/non-brand", "google_sheets": { "show": true, "header_name": "Visits" } }, "conversions_rate": { "type": "number", "description": "The conversion rate (e-commerce) for brand/non-brand", "google_sheets": { "show": true, "header_name": "Conversion Rate" } }, "goals_rate": { "type": "number", "description": "The goals rate for brand/non-brand", "google_sheets": { "show": true, "header_name": "Goals Rate" } }, "conversions_value": { "type": "number", "description": "The revenue (e-commerce) for brand/non-brand", "google_sheets": { "show": true, "header_name": "Revenue" } }, "goals_conversions_value": { "type": "number", "description": "The goals revenue for brand/non-brand", "google_sheets": { "show": true, "header_name": "Goals Revenue" } }, "date": { "type": "string", "description": "Date format(Y-m-d)", "google_sheets": { "show": true, "header_name": "Date" } }, "type": { "type": "string", "description": "Possible values: brand | non-brand", "google_sheets": { "show": true, "header_name": "Type" } } } }, "Content": { "type": "object", "properties": { "id": { "type": "integer", "format": "int32", "google_sheets": { "show": true, "header_name": "ID" } }, "date": { "type": "string", "google_sheets": { "show": true, "header_name": "Date" } }, "title": { "type": "string", "google_sheets": { "show": true, "header_name": "Title" } }, "article_url": { "type": "string", "google_sheets": { "show": true, "header_name": "Article URL" } }, "source": { "type": "string", "google_sheets": { "show": true, "header_name": "Article Source" } }, "visits": { "type": "integer", "format": "int32", "google_sheets": { "show": true, "header_name": "Visits" } }, "conversions": { "type": "integer", "format": "int32", "google_sheets": { "show": true, "header_name": "Conversions" } }, "conversions_value": { "type": "integer", "format": "int32", "google_sheets": { "show": true, "header_name": "Converions Value" } }, "transactions": { "type": "integer", "format": "int32", "google_sheets": { "show": true, "header_name": "Transactions" } }, "transactions_value": { "type": "integer", "format": "int32", "google_sheets": { "show": true, "header_name": "Transactions Value" } }, "social": { "type": "object", "google_sheets": { "show": true, "header_name": "Social", "drill_down": true }, "properties": { "total": { "type": "integer", "format": "int32", "google_sheets": { "show": true, "header_name": "Social Total" } }, "facebook": { "type": "integer", "format": "int32", "google_sheets": { "show": true, "header_name": "Facebook" } }, "twitter": { "type": "integer", "format": "int32", "google_sheets": { "show": true, "header_name": "Twitter" } }, "google_plus": { "type": "integer", "format": "int32", "google_sheets": { "show": true, "header_name": "Google Plus" } }, "linkedin": { "type": "integer", "format": "int32", "google_sheets": { "show": true, "header_name": "Linkedin" } }, "pinterest": { "type": "integer", "format": "int32", "google_sheets": { "show": true, "header_name": "Pintrest" } } } }, "landing_pages": { "type": "array", "items": { "$ref": "#/definitions/LandingPage" } } } }, "KeywordSERP": { "type": "object", "description": "The landing pages", "properties": { "landing page(text)": { "type": "string", "additionalProperties": { "type": "integer", "description": "position" } } } }, "Error": { "type": "object", "properties": { "code": { "type": "integer", "format": "int32" }, "message": { "type": "string" }, "fields": { "type": "string" } } }, "LandingPage": { "type": "object", "properties": { "url": { "type": "string" }, "search_volume": { "type": "integer" }, "visibility_score": { "type": "integer" }, "visibility_score_change": { "type": "integer" }, "keywords": { "type": "array", "items": { "$ref": "#/definitions/Keyword" } } } }, "Keyword": { "type": "object", "properties": { "id": { "type": "integer" }, "avg_search_volume": { "type": "integer" }, "name": { "type": "string" }, "rank": { "type": "integer" }, "rank_change": { "type": "integer" } } }, "VisibilityScore": { "type": "object", "properties": { "date": { "type": "string" }, "vscore": { "type": "integer" }, "vscore_mobile": { "type": "integer" } } }, "VisibilityScoreData": { "type": "object", "properties": { "date": { "type": "string" }, "vscore": { "type": "integer" } } }, "CompareCompetitorsResponse": { "type": "object", "properties": { "YYYY-MM-DD": { "type": "object", "description": "Date", "$ref": "#/definitions/CompareCompetitorsResponseVscore" } } }, "CompareCompetitorsResponseVscore": { "type": "object", "properties": { "competitor.tld": { "type": "number", "description": "Visibility Score for Competior" } } }, "CompareKeywordsCompetitors": { "type": "object", "properties": { "rank": { "type": "integer" }, "change": { "type": "string" } } }, "CompareKeywords": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/definitions/CompareKeywordsResults" } }, "limit": { "type": "number", "description": "Current limit" }, "offset": { "type": "number", "description": "Current offset" }, "pages": { "type": "number", "description": "Total number of pages" }, "total_results": { "type": "number", "description": "Total number of results" } } }, "CompareKeywordsResults": { "type": "object", "properties": { "name": { "type": "string" }, "search_volume": { "type": "integer" }, "avg_cpc": { "type": "string" }, "competitors": { "type": "array", "items": { "$ref": "#/definitions/CompareKeywordsCompetitors" } }, "yoy": { "type": "string" }, "serp_features": { "type": "array", "items": { "type": "string" }, "description": "Array of SERP features" } } } } }