Software Development

Introduction to serpstack’s Free, Real-Time Google Search Results API

Welcome to today’s tutorial on serpstack, a free, real-time Google search results API used to monitor brand performance on search engine results pages around the world. That’s what “serp” stands for, search engine results pages. serpstack is a vital SEO tool to research and understand search engine performance.

Search engines dynamically change the results of user keyword searches based on a variety of factors such as location, the user’s device, language and browsing history. Depending on when and where a user queries from, the results can be very different. To fully comprehend how search engines respond to different users, you need a sophisticated SEO API.

serpstack allows you to regularly monitor search engine performance to your brand or designated keywords from different locations, devices and languages over time. These qualities also make serpstack an excellent tool for Internet researchers.

Home page of apilayer's serpstack real-time accurate Google search results and SEO API

Home page of apilayer’s serpstack real-time accurate Google search results and SEO API

For example, if you’re running a political campaign, you can use the API to see the ads that appear in New York City when a user queries Elizabeth Warren from her iPhone. Or, if you’re running a lawn mowing business you can study the organic search results when a Londoner searches for “find someone to mow my lawn”.

serpstack is a comprehensive solution to search engine analysis. Its API provides 17 kinds of responses from Google search: Ad Results, Organic Results, Image Results, Video Results, News Results, Shopping Results, Local Results, Answer Box, Weather Box, Top Carousel, Top Stories, Knowledge Graph, Inline Tweets, Related Searches, Related Questions, Related Places and Paginate. If it appears in search results, serpstack provides it.

While it would be easy to get lost in this complexity, serpstack’s well-organized documentation makes it simple to get started programming and straightforward to interpret the results.

screenshot of features from the serpstack home page including simple integration, bank-level security, world-class support, JSON & CSV, unparalleled speed and extensive documentation.

screenshot of features from the serpstack home page including simple integration, bank-level security, world-class support, JSON & CSV, unparalleled speed and extensive documentation.

Initially, serpstack supports Google Search with additional search engines coming over time.

Since it is a REST API, serpstack can be used from any programming language. To help you get started quickly, it includes coding examples for PHP, Python, Node.js, jQuery, Go and Ruby.

And serpstack is high performing and scalable, processing queries in milliseconds.

The company behind serpstack is apilayer. This is my ninth article about its services, and I’m a big fan of the simplicity and accessibility of its services. apilayer provides similar pricing models, sign up, quickstart guides and clearly structured documentation.

Here are a few of apilayer’s services, I’ve written about previously at ProgrammableWeb:

If you’ve used any of its services before, starting with the serpstack API will be familiar to you. The documentation and REST API structure is consistent across its suite of products, most of which are perfect for strengthening your application or website. And, each offers a status page where you can review the nearly 100% uptime of the service.

If you’re a startup or independent developer, apilayer always offers a generous free plan with all of its services, as it has with the serpstack API.

Let’s begin researching search engine result pages for different examples.

Getting Started with the serpstack API

To begin exploring serpstack, you’ll need to register for an account, the free account level is great for exploring the API and initial usage, allowing 100 searches per month.

Get Your Free serpstack API Key

Screenshot of serpstack pricing page. Sign up for free, or choose from four paid plans: Basic, Business, Business pro or Enterprise.

Screenshot of serpstack pricing page. Sign up for free, or choose from four paid plans: Basic, Business, Business pro or Enterprise.

The Free plan includes 100 API requests. Other plans add capacity, encryption and more advanced features which we’ll describe further below.

By paying yearly, you can save 20 percent on any plan (except on the free plan, haha).

The Sign-Up Form

Once you’ve chosen a plan you’ll be asked to complete a Sign Up form. It’s very straightforward:

serpstack sign up and registration form. The example shown is the free plan with email, password, name and address information. The image shows the below-the-scroll portion of the form for Company Details and Google CAPTCHA at the right.

serpstack sign up and registration form. The example shown is the free plan with email, password, name and address information. The image shows the below-the-scroll portion of the form for Company Details and Google CAPTCHA at the right.

Once you click Sign Up, a welcome letter with links to the documentation will arrive in your email.

The welcome email from serpstack real time Google search results API includes a link to the serpstack documentation and its customer support email.

The welcome email from serpstack real time Google search results API includes a link to the serpstack documentation and its customer support email.

Let’s check out the Dashboard, which customers of other apilayer services will immediately recognize. If you use one apilayer service, getting started with any other is quite simple.

The serpstack API Dashboard

serpstack’s API dashboard provides your API key and a simple 3 step quickstart guide:

Step 1 – Your API Access Key

Your API access key provides access to the serpstack API. It’s required to be included as a parameter in every call. You can also reset the key to secure a new one whenever you wish.

The serpstack API 3-Step Quickstart Guide for getting started using the real time Google search results services.

The serpstack API 3-Step Quickstart Guide for getting started using the real time Google search results services.

Step 2 – Make Your First API Request

Now, let’s try our first programmatic Google search request. From the Quickstart, you can click on the link in the SEARCH tab and it will initiate a simple query for Google search results for McDonalds.

serpstack API Quickstart Make API Request screenshot. It shows the parameters for a REST API request to search for results at Google.

serpstack API Quickstart Make API Request screenshot. It shows the parameters for a REST API request to search for results at Google.

If you want to try your own query, you will need to replace the letter x’s below with your API access key.

https://api.serpstack.com/search?access_key=xxxxx&query=your-query

Typically, serpstack returns a large amount of data. It’s not easy to quickly visualize. I placed the results in this web based JSON parser (e.g. http://json.parser.online.fr) so I can more clearly show you the JSON response structure. I purposefully collapsed a number of response elements to simplify its appearance. The plus signs below represent the elements I collapsed.

serpstack API response example of quickstart query for Google results from mcdonalds, serp results in JSON format. See organic results, inline images, related searches, knowledge graph et al.

serpstack API response example of quickstart query for Google results from mcdonalds, serp results in JSON format. See organic results, inline images, related searches, knowledge graph et al.

Step 3 – Integrate into Your Application

To finish the Quickstart and move on, let’s dive into the API more closely.

Screenshot of last step of the serpstack API Quickstart, Integrate serp into your application.

Screenshot of last step of the serpstack API Quickstart, Integrate serp into your application.

All of apilayer’s services, including serpstack provide programming examples to help you get started. serpstack provides coding examples for six languages: PHP, Python, Node.js, jQuery, Go and Ruby. To take a look at how you might use serpstack from code, here’s a Python example:

import requests
params = {
‘access_key’: ‘YOUR_ACCESS_KEY’,
‘query’: ‘mcdonalds’
}
api_result = requests.get(‘https://api.serpstack.com/search’, params)
api_response = api_result.json()
print “Total results: “, api_response[‘search_information’][‘total_results’] for number, result in enumerate(api_response[‘organic_results’], start=1):
print “%s. %s” % (number, result[‘title’])

I’ll show more of these further below.

Beyond the basics, serpstack offers a number of important advanced features for tracking Google search results from locations around the world. Let’s take a look at these.

Understanding serpstack’s Google Search API

serpstack API query and its parameters

serpstack’s primary SEO API is the search engine query. Most of the rest of your time will be spent understanding serpstack’s detailed response data. Let’s review how to use the query method for the information you need.

screenshot of documentation of serpstack's primary SEO query method API parameters: engine, type, device, location, auto_location and google_domain.

screenshot of documentation of serpstack’s primary SEO query method API parameters: engine, type, device, location, auto_location and google_domain.

Here are the parameters that you’ll be using:

query is the search that you’d like to gather data for e.g. “impossible burger”.engine specifies the search engine to use, the default is Google.type allows you to specify a standard web search or images, videos, news or shopping results.device allows you to specify desktop, mobile or tablet.location specifies a geographic location to run your search query from. The Locations API which I’ll describe further below can help disambiguate locations.auto_location allows you to automatically set the domain, g1 and h1 parameters below to query from a foreign Google domain e.g. Google.fr for France

And there’s more:

screenshot of documentation of serpstack's primary query method API parameters: google_domain, gl, hl, safe, period, period_start, period_end, news_type, exclude_autocorrected_resuls and images_page.

screenshot of documentation of serpstack’s primary query method API parameters: google_domain, gl, hl, safe, period, period_start, period_end, news_type, exclude_autocorrected_resuls and images_page.

google_domain, gl and hl allow you to set the Google domain to query from, gl is the country code and hl is the language to use.safe allows you to turn on or off explicit search resultsperiod allows you to search from preset date ranges: last_hour, last_day, last_week, last_month, last_year or custom which requires period_start and period_end datesnews_type allows you to focus on news publishers or blogs only exclude_autocorrected_resuls omits search results based on an autocorrected version of your query. If you’re trying to analyze what people see when they mistype your keywords, turn this on.images_page specifies the number of image results

You can find still more parameters for query in the documentation.

Note that if you use the request API commonly from JavaScript frontends, it’s not a bad idea to change your access key on a regular schedule. You can reset your key from the account dashboard, click the black reset button beside your API key.

Now finally, let’s look at the results that the search engine results pages API provides:

serpstack Search Engine Results Pages

serpstack is an amazingly powerful API that responds with a broad set of data. The screenshot below diagrams each element which the API provides a structured response, not all are shown here:

Screenshot of the top portion of Google Search response categories, but with outlines around each section connected to underlined title on left of the screen with canonical name of the element. Tabs exist at the top to see the response in data format for API Result.

Screenshot of the top portion of Google Search response categories, but with outlines around each section connected to underlined title on left of the screen with canonical name of the element. Tabs exist at the top to see the response in the data format for API Result.

Here are the response objects which the API returns that describe your original query, useful if you’ve automated a large number of tasks, and structural aspects of the response such as the number of pages of the response and the total number of results.

Screenshot of the top portion of serpstack query method response objects, mostly search parameters returned for clarity, which helps with automated tasks.

Screenshot of the top portion of serpstack query method response objects, mostly search parameters returned for clarity, which helps with automated tasks.

The individual response elements, which I’ll describe below, are distinct from the above responses. For example, you’ll see each element described in its own data structure, ads, local_map, local_results, knowledge_graph, related_searches, pagination, etc.

I’m only going to describe a few of these components in detail and will simply enumerate the rest with visual examples and links. The serpstack documentation makes it easy to explore these on your own.

serpstack API Response Elements and Definitions

I’ve chosen three elements to showcase today to give you a sense of how the API operates and what it’s capable of. Keep in mind, each of these represents just a subset of response data of the kind of query that we made earlier.

https://api.serpstack.com/search?access_key=xxxxx&query=mcdonalds

First, let’s explore the subset of response data for organic search results.

Organic Search Results

The primary goal of most search engine results page analysis is to raise your organization’s appearance in top organic search results.

serpstack allows you to track the organic results of the search engine for any location, device, domain and user language in real-time, over a period of time.

Here is an example of the organic search results which you can follow along from the documentation:

Screenshot of serpstack documentation for Organic Results, left tab shown has visual of Google Result, the right tab shows data objects returned for API Result.

Screenshot of serpstack documentation for Organic Results, left tab shown has visual of Google Result, the right tab shows data objects returned for API Result.

If you click the API Result tab, you can see the response data. Here is a screenshot of the data in JSON format:

Screenshot of JSON for serpstack API organic search results for query McDonalds. Positions 2 - 5 of search results are closed.

Screenshot of JSON for serpstack API organic search results for query McDonalds. Positions 2 – 5 of search results are closed.

The response data for organic search results are well described in the documentation as shown below:

Screenshot of JSON formatted response for organic search results element via serpstack API.

Screenshot of JSON formatted response for organic search results element via serpstack API

Now let’s explore the subset of response data for related search results.

Related Search Results

Here is an example of the Related Search results which you can follow along from the documentation:

Screenshot of serpstack documentation for Related Searches, left tab shown has visual of Google Result, the right tab shows data objects returned for API Result.

Screenshot of serpstack documentation for Related Searches, left tab shown has visual of Google Result, the right tab shows data objects returned for API Result.

If you click the API Result tab, you can see this subsection of response data. Here it is in JSON format:

Screenshot of JSON for serpstack API related searches from results for query McDonalds.

Screenshot of JSON for serpstack API related searches from results for query McDonalds.

The response objects for related searches is much simpler:

Screenshot of serpstack API response objects for query method related searches structure element.

Screenshot of serpstack API response objects for query method related searches structure element.

Now let’s explore the subset of response data for search engine ads.

Ad Results

One counter-intuitive aspect of SEO is tracking competitive advertisements that appear whenever people search for keywords that relate to your product. With serpstack, you can track advertisements that appear in real-time, over any period of time.

Here you can find the Ad Result documentation and follow along.

Screenshot of serpstack documentation for Ad Results, left tab shown has visual of Google Result, right tab shows data objects returned for API Result.

Screenshot of serpstack documentation for Ad Results, left tab shown has visual of Google Result, right tab shows data objects returned for API Result.

You can browse the response data by clicking the API Result tab and below I’m showing a JSON parsed version of the ads results:

screenshot of JSON formatted response for ad results element

screenshot of JSON formatted response for ad results element

As you can see, search engine ads such as Google’s can be quite detailed and multi-dimensional and serpstack provides all of this.

The serpstack documentation also provides a summary of the data structures that are returned for ad results:

Screenshot from serpstack documentation of ad results response objects.

Screenshot from serpstack documentation of ad results response objects.

I hope you have a basic introduction to exploring the serpstack search engine results pages API. The query method is a powerful feature as far as APIs go. While I do not want to delve deeply into all the other response types, I will enumerate visual examples for each below.

serpstack’s Remaining Search Engine API Responses

Browse serpstack Image Results here:

Screenshot of serpstack documentation Image Results, for a single row of images, left tab shown has visual of Google Result, right tab shows data objects returned for API Result.

Screenshot of serpstack documentation Image Results, for a single row of images, left tab shown has visual of Google Result, right tab shows data objects returned for API Result.

Here are serpstack Video Results:

Screenshot of serpstack documentation for Video Results, left tab shown has visual of Google Result, the right tab shows data objects returned for API Result.

Screenshot of serpstack documentation for Video Results, left tab shown has visual of Google Result, the right tab shows data objects returned for API Result.

You can browse serpstack API News Results here:

Screenshot of serpstack documentation for News Results, left tab shown has visual of Google Result, the right tab shows data objects returned for API Result.

Screenshot of serpstack documentation for News Results, left tab shown has visual of Google Result, the right tab shows data objects returned for API Result.

Here are serpstack Shopping Results:

Screenshot of serpstack documentation for Shopping Results, left tab shown has visual of Google Result, the right tab shows data objects returned for API Result.

Screenshot of serpstack documentation for Shopping Results, left tab shown has visual of Google Result, the right tab shows data objects returned for API Result.

And, serpstack API Local Results:

Screenshot of serpstack documentation for Local Results, left tab shown has visual of Google Result, the right tab shows data objects returned for API Result.

Screenshot of serpstack documentation for Local Results, left tab shown has visual of Google Result, the right tab shows data objects returned for API Result.

Here are the serpstack API Answer Box Results:

Screenshot of serpstack documentation for Answer Box, the left tab shown has visual of Google Result, the right tab shows data objects returned for API Result.

Screenshot of serpstack documentation for Answer Box, left tab shown has visual of Google Result, right tab shows data objects returned for API Result.

And, serpstack Weather Box Results:

Screenshot of serpstack documentation for Weather Box, left tab shown has visual of Google Result, right tab shows data objects returned for API Result.

Screenshot of serpstack documentation for Weather Box, left tab shown has visual of Google Result, right tab shows data objects returned for API Result.

And, serpstack Events Results, such as concerts, movies, et al.:

Screenshot of serpstack documentation for Events e.g. concerts, plays, et al., the left tab shown has visual of Google Result, the right tab shows data objects returned for API Result.

Screenshot of serpstack documentation for Events e.g. concerts, plays, et al., the left tab shown has visual of Google Result, the right tab shows data objects returned for API Result.

Here is the serpstack Top Carousel, which often appears with queries for books or music:

Screenshot of serpstack documentation for Top Carousel e.g. books or music albums, et al., left tab shown has visual of Google Result, right tab shows data objects returned for API Result.

Screenshot of serpstack documentation for Top Carousel e.g. books or music albums, et al., left tab shown has visual of Google Result, right tab shows data objects returned for API Result.

And the familiar serpstack, search engine Knowledge Graph:

Screenshot of serpstack documentation for Knowledge Graph, basic information of query, social profiles et al., left tab shown has visual of Google Result, right tab shows data objects returned for API Result.

Screenshot of serpstack documentation for Knowledge Graph, basic information of query, social profiles et al., left tab shown has visual of Google Result, right tab shows data objects returned for API Result.

And the serpstack API Inline Tweets:

Screenshot of serpstack documentation for Inline Tweets, left tab shown has visual of Google Result, right tab shows data objects returned for API Result.

Screenshot of serpstack documentation for Inline Tweets, left tab shown has visual of Google Result, right tab shows data objects returned for API Result.

Here is serpstack’s Top Stories:

Screenshot of serpstack documentation for Top Stories, left tab shown has visual of Google Result, right tab shows data objects returned for API Result.

Screenshot of serpstack documentation for Top Stories, left tab shown has visual of Google Result, right tab shows data objects returned for API Result.

And Related Questions:

 Screenshot of serpstack documentation for Related Questions, left tab shown has visual of Google Result, right tab shows data objects returned for API Result.

Screenshot of serpstack documentation for Related Questions, left tab shown has visual of Google Result, right tab shows data objects returned for API Result.

Here are the serpstack result for Related Places:

Screenshot of serpstack documentation for Related Places, left tab shown has visual of Google Result, right tab shows data objects returned for API Result.

Screenshot of serpstack documentation for Related Places, left tab shown has visual of Google Result, right tab shows data objects returned for API Result.

And finally, last but not least, the search engine response result API from serpstack for search engine Pagination:

Screenshot of serpstack documentation for Pagination, left tab shown has visual of Google Result, right tab shows data objects returned for API Result.

Screenshot of serpstack documentation for Pagination, left tab shown has visual of Google Result, right tab shows data objects returned for API Result.

Pagination is often critical for navigating pages of results from the query method.

It’s clear that the serpstack keyword API query is incredibly powerful and broad. Now, let’s cover the other serpstack method, the Locations API.

The Locations API

serpstack provides a simple locations query to help disambiguate overlapping location names, such as Springfield, Missouri, Springfield, Illinois and Springfield, Virginia and the home of Bart and Lisa Simpson, Springfield, Massachusetts.

Screenshot of documentation of the serpstack locations method, requires a query for a basic location string and the responses disambiguate the location.

Screenshot of documentation of the serpstack locations method, requires a query for a basic location string and the responses disambiguate the location.

Click the Run API Request button to run an example for New York, or replace your API key with the query below for Springfield:

https://api.serpstack.com/locations?access_key=xxxxx&query=springfield

I pasted the JSON results into my parsers to visualize them and you can see CANONICAL_NAMES for each of the distinct city locations:

serpstack locations api disambiguates cities such as Springfield into distinct canonical names for the API.

serpstack locations api disambiguates cities such as Springfield into distinct canonical names for the API.

As you can see in the response, all the locations of Springfield named cities have their own canonical_name value. Use the canonical_name string to dial the serpstack query method into a specific city.

If you want to know what search engine results pages show up as in Springfield, Virginia, use canonical_name “Springfield,Virginia,United States”.

Programming Language Examples

As I mentioned earlier, serpstack provides programming examples for six of the most popular languages: PHP, Python, Node.js, jQuery, Go and Ruby.

Here’s an example for jQuery:

$.ajax({
url: ‘https://api.serpstack.com/search’,
data: {
access_key: ‘YOUR_ACCESS_KEY’,
query: ‘mcdonalds’
},
dataType: ‘json’,
success: function(apiResponse) {
console.log(“Total results:”, apiResponse.search_information.total_results);
apiResponse.organic_results.map(function(result, number) {
console.log(number + 1 + “.”, result.title);
});
}
});

And, here’s an example of PHP using curl:

$queryString = http_build_query([
‘access_key’ => ‘YOUR_ACCESS_KEY’,
‘query’ => ‘mcdonalds’,
]);
$ch = curl_init(sprintf(‘%s?%s’, ‘https://api.serpstack.com/search’, $queryString));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$json = curl_exec($ch);
curl_close($ch);
$api_result = json_decode($json, true);
echo “Total results: “, $api_result[‘search_information’][‘total_results’], PHP_EOL;
foreach ($api_result[‘organic_results’] as $number =>> $result) {
echo “{$number}. {$result[‘title’]}”, PHP_EOL;
}

And, here’s an example using Ruby:

require ‘net/http’
require ‘json’
params = {
:access_key => “YOUR_ACCESS_KEY”,
:query => “mcdonalds”
}
uri = URI(‘https://api.serpstack.com/search’)
uri.query = URI.encode_www_form(params)
json = Net::HTTP.get(uri)
api_response = JSON.parse(json)
puts “Total results: #{api_response[‘search_information’][‘total_results’]}”
api_response[‘organic_results’].each_with_index do |result, number|
puts “#{number + 1}. #{result[‘title’]}”
end

These examples make it so easy to quickly integrate serpstack into your development platform and SEO optimization programs. Making it easy to get started with an API service is one of apilayer’s specialties.

Let’s talk about usage levels and your account.

Upgrading Your Account

serpstack is a subscription-based service and your chosen plan renews automatically each month. You can upgrade, downgrade or cancel anytime.

To make changes, visit your Subscription Plan page from the Dashboard. In the image below, you can see I’m on the Business Pro trial plan but can switch to any other plan.

serpstack plan by usage and features to upgrade or downgrade pricing plans for real time SEO keyword analysis and Google search results API.

serpstack plan by usage and features to upgrade or downgrade pricing plans for real time SEO keyword analysis and Google search results API.

The Basic level plan provides 5,000 queries per month and all of the paid features that are not available in the Free plan:

HTTPS encryption for your REST API requestsCSV response format to supplement JSONNo rate limit on the frequency of requestsPremium support

If you need a higher volume of queries, then upgrade to Business plan for 20,000 per month, Business Pro for 50,000 per month or contact serpstack for a custom enterprise plan.

And, serpstack provides a page to calculate your usage statistics in the current period and historically over time. Just visit your Dashboard and click API Usage (I’ve just recently been using my account so the usage is over a brief timeframe.):

The serpstack Dashboard's API Usage page displays the number of Google search API requests all time as well as a statistical daily log for your internal tracking.

The serpstack Dashboard’s API Usage page displays the number of Google search API requests all time as well as a statistical daily log for your internal tracking.

You can use this log to help you in deciding to upgrade or downgrade subscription levels. For example, Free plans are allowed 100 calls per month whereas Basic are allowed 5,000 requests and Professional Pro are allowed 50,000. If that isn’t enough to meet your requirements, contact serpstack for a custom enterprise plan.

In Conclusion

I hope you’ve enjoyed learning about serpstack’s Google search engine results API and how to analyze search engine results pages from around the world. It’s a sophisticated REST API for professional search engine optimization and search engine research. It’s a vital resource for companies of all sizes, especially startups trying to develop a prominent spot in search engine results.

I enjoy writing for the folks behind serpstack, the apilayer team, and sharing their new projects. They are skillful technologists that provide powerful services at affordable prices with easy to integrate APIs and scalable performance and capacity.

Check out their suite of products and you’ll likely find more that interest you.

apilayer and serpstack appreciate your questions, comments and feedback. You can also follow them on Twitter @apilayer and the apilayer Facebook page.

About apilayer

serpstack is the latest service from apilayer, an established leader in service APIs. It aims to help developers and businesses automate and outsource complex processes by serving them with dedicated and handy programming interfaces.

Two other products by apilayer include scrapestack, the free, real-time, scalable proxy & web scraping API and weatherstack, the free real time weather data and forecast API, both of which I wrote about previously for ProgrammableWeb.

Show More

Related Articles

Leave a Reply

Your email address will not be published. Required fields are marked *