Returns Semrush domain history for a specified domain from January 2012 onwards
12 |Returns Semrush Organic keywords for a specified domain
15 |Returns Historical rankings for domain/keyword combination
18 |Returns Ranking Semrush Organic keywords per URL
21 |Returns Semrush Keyword Difficulty for a keyword
24 |Returns Semrush organic search results for a specific keyword
27 |Returns Related search queries for a keyword from Semrush
30 |Returns Keyword Volume from semrush
33 |Returns Questions asked for a keyword from Semrush
36 |"example.com" | REQUIRED The root domain, example: "nytimes.com", DO NOT include protocol (http/https) |
51 | | db | "us" | OPTIONAL The country database you want to search from. Default is US |
52 | | date | 201601 | OPTIONAL Leave this blank for current data. YYYYMM format for historical reports, note: always reports on the 15th of the month. |
53 | | excludeHeaders | true | OPTIONAL true to EXCLUDE column headers or false to include. Default is false. |
54 | | cache | "TRUE" | OPTIONAL use FALSE if you DO NOT want to cache these results or DO NOT want to return cached results, default is TRUE (cache enabled) |
55 |
56 |
57 |
58 | ## DOMAIN\_ORGANIC\_KEYWORDS\_SEMRUSH(domain, filterBy, matchType, query, limit, db, date, excludeHeaders, cache) ⇒
59 | Returns Semrush Organic keywords for a specified domain
60 |
61 | **Kind**: global function
62 | **Returns**: Access organic keywords for a domain from semrush.com database.
63 | **Customfunction**:
64 |
65 | | Param | Type | Description |
66 | | --- | --- | --- |
67 | | domain | "example.com" | REQUIRED The root domain, example: "nytimes.com", DO NOT include protocol (http/https) |
68 | | filterBy | true | OPTIONAL Use true to include the query in the filter or false to remove the query in the filter. Default is true |
69 | | matchType | true | OPTIONAL Use true for partial match, use false for exact match. Default is true, partial match |
70 | | query | "apartments" | OPTIONAL The keyword you want to filter by. Relies on previous 2 parameters. Example: "brown shoes". |
71 | | limit | 10 | OPTIONAL Number from 1 to 10000 |
72 | | db | "us" | OPTIONAL The country database you want to search from. Default is US |
73 | | date | 201601 | OPTIONAL Leave this blank for current data. YYYYMM format for historical reports, note: always reports on the 15th of the month. |
74 | | excludeHeaders | true | OPTIONAL true to EXCLUDE column headers or false to include. Default is false. |
75 | | cache | "TRUE" | OPTIONAL use FALSE if you DO NOT want to cache these results or DO NOT want to return cached results, default is TRUE (cache enabled) |
76 |
77 |
78 |
79 | ## HISTORICAL\_RANKING\_KEYWORD\_SEMRUSH(domain, query, limit, db, date, excludeHeaders, cache) ⇒
80 | Returns Historical rankings for domain/keyword combination
81 |
82 | **Kind**: global function
83 | **Returns**: Access organic keywords for a domain from semrush.com database
84 | **Customfunction**:
85 |
86 | | Param | Type | Description |
87 | | --- | --- | --- |
88 | | domain | "example.com" | REQUIRED The root domain, example: "nytimes.com", DO NOT include protocol (http/https) |
89 | | query | "apartments" | OPTIONAL The keyword you want to filter by. Relies on previous 2 parameters. Example: "brown shoes". |
90 | | limit | 10 | OPTIONAL Number from 1 to 10000 |
91 | | db | "us" | OPTIONAL The country database you want to search from. Default is US |
92 | | date | 201601 | OPTIONAL Leave this blank for current data. YYYYMM format for historical reports, note: always reports on the 15th of the month. |
93 | | excludeHeaders | true | OPTIONAL true to EXCLUDE column headers or false to include. Default is false. |
94 | | cache | "TRUE" | OPTIONAL use FALSE if you DO NOT want to cache these results or DO NOT want to return cached results, default is TRUE (cache enabled) |
95 |
96 |
97 |
98 | ## URL\_ORGANIC\_KEYWORDS\_SEMRUSH(url, limit, db, excludeHeaders, cache) ⇒
99 | Returns Ranking Semrush Organic keywords per URL
100 |
101 | **Kind**: global function
102 | **Returns**: Access organic keywords for a url from semrush.com database
103 | **Customfunction**:
104 |
105 | | Param | Type | Description |
106 | | --- | --- | --- |
107 | | url | "http://example.com" | REQUIRED The exact URL you want data for, MUST include protocol (http/https) |
108 | | limit | "10" | OPTIONAL Number from 1 to 10,000, for number of results |
109 | | db | "US" | OPTIONAL The database, example "US" for American database. Default is US |
110 | | excludeHeaders | true | OPTIONAL true to EXCLUDE column headers or false to include. Default is false. |
111 | | cache | "TRUE" | OPTIONAL use FALSE if you DO NOT want to cache these results or DO NOT want to return cached results, default is TRUE (cache enabled) |
112 |
113 |
114 |
115 | ## KEYWORD\_DIFFICULTY\_SEMRUSH(query, db, excludeHeaders, cache) ⇒
116 | Returns Semrush Keyword Difficulty for a keyword
117 |
118 | **Kind**: global function
119 | **Returns**: Access keyword difficulty for keyword from semrush
120 | **Customfunction**:
121 |
122 | | Param | Type | Description |
123 | | --- | --- | --- |
124 | | query | "apartments" | REQUIRED The keyword you want information for. Example: "brown shoes". |
125 | | db | "us" | OPTIONAL The country database you want to search from. Default is US |
126 | | excludeHeaders | true | OPTIONAL true to EXCLUDE column headers or false to include. Default is false. |
127 | | cache | "TRUE" | OPTIONAL use FALSE if you DO NOT want to cache these results or DO NOT want to return cached results, default is TRUE (cache enabled) |
128 |
129 |
130 |
131 | ## SERPS\_SEMRUSH(query, limit, db, excludeHeaders, cache) ⇒
132 | Returns Semrush organic search results for a specific keyword
133 |
134 | **Kind**: global function
135 | **Returns**: Access organic search results for a keyword from semrush.com database
136 | **Customfunction**:
137 |
138 | | Param | Type | Description |
139 | | --- | --- | --- |
140 | | query | "apartments" | REQUIRED The keyword you want information for. Example: "brown shoes". |
141 | | limit | 10 | OPTIONAL Number from 10 to 20, for number of results. Default is 10 |
142 | | db | "us" | OPTIONAL The country database you want to search from. Default is US |
143 | | excludeHeaders | true | OPTIONAL true to EXCLUDE column headers or false to include. Default is false. |
144 | | cache | "TRUE" | OPTIONAL use FALSE if you DO NOT want to cache these results or DO NOT want to return cached results, default is TRUE (cache enabled) |
145 |
146 |
147 |
148 | ## RELATED\_QUERIES\_SEMRUSH(query, limit, db, excludeHeaders, cache) ⇒
149 | Returns Related search queries for a keyword from Semrush
150 |
151 | **Kind**: global function
152 | **Returns**: Returns related queries for a specific keyword from semrush.com
153 | **Customfunction**:
154 |
155 | | Param | Type | Description |
156 | | --- | --- | --- |
157 | | query | "apartments" | REQUIRED The keyword you want information for. Example: "brown shoes". |
158 | | limit | 10 | OPTIONAL The number of results. Default is 1 |
159 | | db | "us" | OPTIONAL The country database you want to search from. Default is US |
160 | | excludeHeaders | true | OPTIONAL true to EXCLUDE column headers or false to include. Default is false. |
161 | | cache | "TRUE" | OPTIONAL use FALSE if you DO NOT want to cache these results or DO NOT want to return cached results, default is TRUE (cache enabled) |
162 |
163 |
164 |
165 | ## KEYWORD\_VOLUME\_SEMRUSH(query, db, excludeHeaders, cache) ⇒
166 | Returns Keyword Volume from semrush
167 |
168 | **Kind**: global function
169 | **Returns**: Returns search volume, cpc, etc..
170 | **Customfunction**:
171 |
172 | | Param | Type | Description |
173 | | --- | --- | --- |
174 | | query | "apartments" | REQUIRED The keyword you want information for. Example: "brown shoes". |
175 | | db | "us" | OPTIONAL The country database you want to search from, default is "us" |
176 | | excludeHeaders | true | OPTIONAL true to EXCLUDE column headers or false to include. Default is false. |
177 | | cache | "TRUE" | OPTIONAL use FALSE if you DO NOT want to cache these results or DO NOT want to return cached results, default is TRUE (cache enabled) |
178 |
179 |
180 |
181 | ## PHRASE\_QUESTIONS\_SEMRUSH(query, limit, db, filterBySearchVolume, searchVolumeFilter, searchVolume, excludeHeaders, cache) ⇒
182 | Returns Questions asked for a keyword from Semrush
183 |
184 | **Kind**: global function
185 | **Returns**: Returns Questions asked for a specific keyword from semrush.com
186 | **Customfunction**:
187 |
188 | | Param | Type | Description |
189 | | --- | --- | --- |
190 | | query | "apartments" | REQUIRED The keyword you want information for. Example: "brown shoes". |
191 | | limit | 10 | OPTIONAL The number of results. Default is 1 |
192 | | db | "us" | OPTIONAL The country database you want to search from. Default is US |
193 | | filterBySearchVolume | true | OPTIONAL If you want to filter by search volume, use TRUE, default is FALSE |
194 | | searchVolumeFilter | ">" | OPTIONAL Filters the search volume parameter (next). Use ">" for Greater than, or "<" for Less than. Default is ">" greater than |
195 | | searchVolume | 1000 | OPTIONAL A search volume number (per month) you want to filter results by. Both previous parameters need to be set for this to work. |
196 | | excludeHeaders | true | OPTIONAL true to EXCLUDE column headers or false to include. Default is false. |
197 | | cache | "TRUE" | OPTIONAL use FALSE if you DO NOT want to cache these results or DO NOT want to return cached results, default is TRUE (cache enabled) |
198 |
--------------------------------------------------------------------------------
/script.js:
--------------------------------------------------------------------------------
1 | /* ---------------------------------------------------------------------------
2 | * Semrush API functions (Google sheets) from Analytics API: https://www.semrush.com/api-analytics/
3 | *
4 | * @desc Access Organic API calls from the Semrush.com API using Google sheets formulas
5 | * @author Dave Sottimano @dsottimano Twitter
6 | * @license MIT (http://www.opensource.org/licenses/mit-license.php)
7 | * @version 1.0
8 | * -------------------------------------------------------------------------*/
9 |
10 | //----------------------------------------------------------------------------
11 |
12 | function onOpen() {
13 | SpreadsheetApp.getUi()
14 | .createMenu('Helper Functions')
15 | .addItem('Check Semrush API balance', 'checkSemrushAccount')
16 | .addItem('Add your API key', 'addApiKey')
17 | .addItem('Flush the cache', 'flushAllCacheAndProperties')
18 | .addItem('Show formula reference', 'formulaReferenceSidebar')
19 | .addToUi();
20 |
21 | if (!SemrushGlobal.data.API_KEY) SpreadsheetApp.getActiveSpreadsheet().toast('In the Helper Functions menu (menu bar), click on Add your API key to get started!', 'The Library is ready to rock :', 5);
22 |
23 | }
24 |
25 | function formulaReferenceSidebar () {
26 | var htmlOutput = HtmlService.createHtmlOutputFromFile('sidebar')
27 | .setTitle('Semrush API Library (Unofficial)');
28 |
29 | SpreadsheetApp.getUi().showSidebar(htmlOutput);
30 | }
31 |
32 |
33 | /* ---------------------------------------------------------------------------*
34 | SemrushGlobal Object START
35 | * -------------------------------------------------------------------------*/
36 |
37 | var SemrushGlobal = {
38 |
39 | data : {
40 | API_KEY : PropertiesService.getUserProperties().getProperty("semrushkey"),
41 | DEFAULT_DB : "us",
42 | API_KEY_PROPERTY_NAME: "semrushkey"
43 | },
44 | queries : {
45 | domainOrganic : "http://api.semrush.com/?type=domain_organic&key=",
46 | urlOrganic : "http://api.semrush.com/?type=url_organic&key=",
47 | keywordDifficulty: "http://api.semrush.com/?type=phrase_kdi&key=",
48 | phraseOrganic : "http://api.semrush.com/?type=phrase_organic&key=",
49 | keywordVolume : "http://api.semrush.com/?type=phrase_this&key=",
50 | relatedQueries : "http://api.semrush.com/?type=phrase_related&key=",
51 | phraseQuestions: "https://api.semrush.com/?type=phrase_questions&key=",
52 | domainOverview : "http://api.semrush.com/?type=domain_rank&key=",
53 | countUnits : "http://www.semrush.com/users/countapiunits.html?key="
54 | },
55 | methods : {
56 | giveApiRest : function giveApiRest () {
57 | Utilities.sleep(200)
58 | },
59 | checkAccount : function checkAccount () {
60 |
61 | try {
62 | if (!SemrushGlobal.data.API_KEY) return [false,"No valid API key found. Please run the Add Semrush Key function from the Spreadsheet menu under 'Helper functions'"]
63 | var result = UrlFetchApp.fetch(SemrushGlobal.queries.countUnits + SemrushGlobal.data.API_KEY,{"muteHttpExceptions":true})
64 |
65 | if (typeof result.getContentText() === "string") {
66 | if(parseInt(result.getContentText()) > -1) {
67 | return [true]
68 | }
69 | var parsedResult = JSON.parse(result.getContentText())
70 | if (parsedResult == 0) throw "The key:" + PropertiesService.getDocumentProperties().getProperty("semrushkey") + " has no credits left"
71 | if (parsedResult.data.error) throw parsedResult.data.error
72 | return [true]
73 | }
74 |
75 | } catch (e) {
76 | return [false,e]
77 | }
78 | },
79 | parseApiResponse : function parseApiResponse(result,valueBoolean) {
80 | var data = [], valueBoolean, filtered
81 | valueBoolean ? valueBoolean = 1 : valueBoolean = 0;
82 | var newLines = result.split("\n");
83 |
84 | try {
85 | for(i=valueBoolean;iOpensourceseo.org
34 | 35 |DOMAIN_ORGANIC_KEYWORDS_SEMRUSH
50 |Params: (domain, filterBy, matchType, query, limit, db, excludeHeaders, date, cache)
51 |Returns: lists keywords that bring users to a domain via Google’s top 20 organic search results.
52 | 53 |DOMAIN_OVERVIEW_SEMRUSH
54 |Params: (query, excludeHeaders, db, cache)
55 |Returns: provides live or historical data on a domain’s keyword rankings in both organic and paid search in a chosen regional database.
56 |KEYWORD_DIFFICULTY_SEMRUSH
71 |Params: (query, excludeHeaders, db, cache)
72 |Returns: provides keyword difficulty, an index that helps to estimate how difficult it would be to seize competitors’ positions in organic search within the Google’s top 20 with an indicated search term
73 | 74 |KEYWORD_VOLUME_SEMRUSH
75 |Params: (query, excludeHeaders, db, cache)
76 |Returns: provides a summary of a keyword, including its volume, CPC, competition, and the number of results in all regional databases
77 | 78 |RELATED_QUERIES_SEMRUSH
79 |Params: (query, excludeHeaders, limit, db, cache)
80 |Returns: provides an extended list of related keywords, synonyms, and variations relevant to a queried term in a chosen database.
81 | 82 |PHRASE_QUESTIONS_SEMRUSH
83 |Params: (query, limit, db, filterBySearchVolume, searchVolumeFilter, searchVolume, excludeHeaders, cache)
84 |Returns: provides a list of phrase questions relevant to a queried term in a chosen database
85 | 86 | 87 |URL_ORGANIC_KEYWORDS_SEMRUSH
102 |Params: (url, excludeHeaders, limit, db, cache)
103 |Returns: lists keywords that bring users to a URL via Google’s top 20 organic search results..
104 | 105 |SERPS_SEMRUSH
106 |Params: (query,limit,db,excludeHeaders,cache)
107 |Returns: lists domains that are ranking in Google’s top 20 organic search results with a requested keyword.
108 |