My experience with Serpstat SVCS
By: Buci Michal
Tags: SEO, Serpstat, Keyword Research, Google Sheets, PPC Marketing

Photo by Kirill Pershin on Unsplash

Overview:

Creating a Google Sheet template for Task Creation. Creating a Google Sheet template for Task list. Writing a code for Task creation. Writing a code for pulling Task records.

1. Creating a Google Sheet template for Task Creation.

Before diving into creating a template for our application, we need to know which parameters are going to be used as an input. Reading the documentation, we can see that there are 6 input values that are required in order to make a valid API request. Well, one input is optional. I’ll explain it shortly.

Country - A numerical value representing a country. This is a location where the queries will be performed on Google.

- A numerical value representing a country. This is a location where the queries will be performed on Google. Language - Another numerical value, which reflects the preferred language while searching the queries.

- Another numerical value, which reflects the preferred language while searching the queries. Region - Again, numerical value. This time representing a region where the queries should come from. It might come very handy to specify the exact region/city.

- Again, numerical value. This time representing a region where the queries should come from. It might come very handy to specify the exact region/city. Device - This one is voluntary. If not specified, queries will be done on desktop devices by default. Otherwise, number 1 is for desktop, number 2 for mobile.

- This one is voluntary. If not specified, queries will be done on desktop devices by default. Otherwise, number 1 is for desktop, number 2 for mobile. Keywords - An obvious one. A list of keywords we wish to query.

- An obvious one. A list of keywords we wish to query. Access Token - Required parameter for identifying Serpstat user account. It’s a long alphanumerical text which can be found at Serpstat account page.

Now that the parameters are known, we can create our Google Sheets template accordingly. Let's give the sheet name “Run”, and place labels and inputs in an orderly manner.

Google Sheet template for Task Creation

Looks relatively simple, right?

I added “Create Task” button, with the purpose of making it able to call a script function. You can add it from the menu “Insert” => “Drawing” (yes, we have to draw a button in order to be able to call a script function).

2. Creating a Google Sheet template for Task list.

When we send a request to create a Task via API, we get a bunch of information back. The most important piece is task_id, which should be preserved. It’ll be necessary to know the id, so we can pull the records once the crawling is finished.

Since we are already saving task_id, we can as well save all other parameters associated with the created Task. It’s nice to have a date of Task creation, and something like number of keywords queried (# Keywords) as well. It’ll help us orientate amidst all created Tasks in the past.

Google Sheet template for a List of Tasks

We did create a new sheet which we’ll call “Tasks” (we’ll refer to this sheet in the script by a name).

You can notice I added two more buttons, similar to the “Create Task” button in the first spreadsheet tab. “Display” will serve as a function call to pull results from Serpstat server, and append them in our third sheet tab. To specify which Taks we want results from, we have to manually input Task ID inside I:3 cell.

“Refresh” button serves to update Progress status of every unfinished Tasks. Since crawling the keywords may take more than an hour before the results became accessible, it comes handy to know current progress.

3. Writing a code for Task Creation.

One of the big advantages of Google Sheets is the possibility of use of Google Apps scripting. We can write javascript functions that interact with data in Google Sheets, and may perform myriad of other calculations and interactions.

I’m not a huge fan of javascript, but the fact that it can be easily integrated within Google Sheets is a game changer. I call myself a Python programmer, but for a client, it’s 100s times simpler to use an app in Google Sheets than a Python script.

The Script editor can be found in the menu “Tools” => “Script editor”.

When you open the Script editor, you should see a window like the one below. This is a place where the script will live and perform magic.

In order to create a Task via API, we need to read the parameters from the spreadsheet.

Function getParameters() returns a dictionary with our parameters. It’ll be fed to our next function postTaskCreation(parameters).

Our third function is appendTask(parameters, response). It’s important to write details regarding the created Task itself. Specifically, task_id returned from API. task_id is used to identify the crawling request and is necessary to get records afterwards.

Finally, we put everything in one place. Our last function is the one that we’ll use to call when we push the button “Create Task”.

To make the connection to our function, we assign a script to the button by selecting it and clicking on the 3 dots on the right.

Now, we simply type the name of the function we want to call.

4. Writing a code for pulling Task records.

The second part of API integration is pulling the records after the Task is finished. Code in this section will interact with “Tasks” and “Raw Records” spreadsheet tabs.

Again, we’ll write a couple of helper functions.

Function getAccessToken() will return an access token that we’ll use for making an API request.

Each API call returns data in JSON format that needs to be parsed. To achieve that, we created parseRecords(responseData) that will take the data and transform it into a list of dictionaries. We’ll use it in the code below.

getTaskRecords(accessToken, taskID) will return a list of all records by repeatedly calling API. Repeatedly, because there is a limit of how many records are returned in a single API request. This process is reiterated until next_page is not present in the response. Otherwise, we use this value to get the next batch.

The final piece to glue it all together is displayRecords(). It’ll clear “Raw Records” sheet, pull records as a list of dictionaries by calling getTaskRecords(accessToken, taskID), and output the data inside “Raw Records” sheet. Also, this is a function that will be called whenever we press “Display” button from “Tasks” sheet. We’ll repeat the process in a similar fashion as with “Create Task” button.

Not to forget about refreshing Task’s progress, we shall add the code beneath. Likewise the previous buttons, we’ll add a connection to the “Refresh” button to refresh function. By doing this, whenever we press “Refresh”, progress of all the Tasks will be updated.

When we put it all together, we get a functional app in Google Sheets, with a couple of convenient components to benefit from. Now, we can set parameters in “Run” sheet, create a Task, and then pull the records from “Tasks” sheet.

Conclusion

I hope you enjoyed reading about my experience building this tool. I tried to keep it as simple as possible, omitting a lot of “unnecessary” code. For example, originally when the Task Creation is pressed, user has to confirm the action to avoid the potential of missclick. Also, there was some neat data cleaning and processing. To keep it concise, I was reluctant to add everything.

If you like my simple tool, feel free to leave feedback or ask any questions.