DocsLive DEMOFeaturesIntegration

SERPMaster Full Walkthrough

SERPMaster processes search requests in real time, taking care of proxy management, captchas, retries, result localization and other data acquisition aspects in order to return 100% correct results in "JSON" or "HTML" format. To help you get the most out of our Google Search API, we will walk you through the entire process of making increasingly complex requests.

Throughout this walkthrough we will outline the use of the most useful SERPMaster parameters and some general guidelines for their use. For a full list of all available parameter values, visit our documentation

After finishing the entire walkthrough, you should be able to send requests to the SERPMaster endpoint without any hassle. 

NB! If you haven’t yet sent any requests to APIs, we recommend using the Browser integration for this tutorial. Remember to change the "access_token" parameter to the one provided in your welcome email. Sending requests of a different type will require an application (e.g. Postman).

Making a Request

Performing a search is as simple as making a GET HTTPS request to the SERPMaster "queries" endpoint. To make the simplest query, just provide a value for the parameter "q" (search query) and your authentication information (depending on the integration option, either in an "access_token" or in your authentication header). With some integration options, you will also have to specify that you're sending "application/json" content.

Now we will outline what needs to be edited in order to send different requests. Within each section we provide a sample request that can be used repeatedly or easily modified upon necessity.

Browser requests

Sending requests through the Browser integration is the simplest way to begin. It can be utilized by simply copying and pasting the provided URL into any browser’s address bar.

A sample request would be formed as such: 

https://rt.serpmaster.com/?q=lorem%20ipsum&access_token=1234abcd

NB! Access tokens are a form of authentication. They are sent to each user after registration.

cURL requests

With cURL you can apply parameters through the use of curly brackets and -d (or -data) flags:

-d '{"q": "lorem ipsum"}' 


A sample request would be formed as such:

curl -u username:password 'https://rt.serpmaster.com/v1/queries' -d '{"q": "lorem ipsum"}' -H "Content-Type: application/json"


NB!
Don't forget to send the "Content-Type: application/json" header with your requests.


Python requests

Whenever requests are sent through Python to the SERPMaster endpoint, a dictionary is created in order to send the details:

job_params = {
    'q': 'lorem ipsum',
}


A sample request would be formed as such:

{
import requests
from pprint import pprint
// Specify content type and form the request body
headers = {'Content-Type': 'application/json'}
job_params = {
    'q': 'lorem ipsum',
}
// Post job and get response
response = requests.post(
    'https://rt.serpmaster.com/v1/queries',
    headers=headers,
    json=job_params,
    auth=('user', 'pass1')
)
// Print the response body
pprint(response.json())
}


PHP requests

Finally, PHP requests function in a similar manner to the way Python is used, only the notation is different:

$data = [
    "q" => "lorem ipsum",
];


A sample request would be formed as such:

<?php
$ch = curl_init();
# Form the request body
$data = [
    "q" => "lorem ipsum",
];
# Set request headers, authentication and other parameters
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_USERPWD, "user" . ":" . "pass1");
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_URL, "https://rt.serpmaster.com/v1/queries");
curl_setopt($ch, CURLOPT_HTTPHEADER, ["Content-Type: application/json"]);
$response = curl_exec($ch);
curl_close($ch);
$json = json_decode($response);
var_dump($json);
?>


Formatting Guidelines

Previously we provided sample requests that can be easily edited to suit your needs. In most cases, editing the examples provided will be more than enough. Formatting guidelines are only required if you want to delve deeper into the possible request customization options.

Browser

Requests are specified by editing our URL (https://rt.serpmaster.com/?):

  1. & (or empty if it is the first parameter),
  2. A parameter, such as “q”, “geo” etc.,
  3. =,
  4. An applicable value

cURL

Parameter sets can be specified by opening with a single parenthesis (‘) and opening curly brackets. Each parameter is then listed by enveloping it in regular parentheses (“ “) and adding a colon (:) at the end. Parameter values are listed by enveloping the value in parentheses. Finally, the curly brackets are closed and a single parenthesis is added to the end as in the example outlined above.

Numbers (or values that are not strings) do not require parentheses. E.g.:

'{"q": "lorem ipsum", “num”: 100}' 


Python

By editing the dictionary object, you can add more parameters such as “geo” and others by applying the same process.

As in the cURL request, curly brackets open the dictionary and then each parameter and value is listed in a new line through the use of parentheses. Numbers and non-string values do not require parentheses:

job_params = {
    'q': 'lorem ipsum',
    ‘num’: 100,
}


PHP

Instead of using curly brackets, regular ones are employed. Values are stated through the use of “=>”. Finally, remember to close brackets and to add a semicolon at the end of the statement.

Parentheses are only used for values that are sent as strings:

$data = [
    "q" => "lorem ipsum",
    "num" => 100,
];


Using Location Parameters

Making requests like the one above is good fun, but inputting additional parameters will make Google SERP page more useful in practice. Google heavily relies on the user's location when putting together a results page, therefore using our "geo" parameter correctly is vital to getting actionable data. Let's say we would like to search for "hotels near me" in New York, New York, USA. 

NB! In requests we use Google’s canonical location names, e.g. Boston,Massachusetts,United States.

Here's how we would form the request to achieve this goal:

https://rt.serpmaster.com/?q=hotels%20near%20me&geo=New%20York,New%20York,United%20States&access_token=1234abcd


Let’s try switching up the location and making another search. Pick "Berlin,Germany" for the next test. In your result, you will see how we adapt the URL parameters accordingly.

https://rt.serpmaster.com/?q=hotels%20near%20me&geo=Berlin,Germany&access_token=1234abcd


Getting More Pages

Google normally only returns 10 organic search results per page. SERPMaster can get up to 100 organic results on your SERPs. To achieve this, use the "num" parameter. You can set it to any value between "1" and "100". You can also specify which page number you would like to get, if you want to get data for a specific result from Google.

Let's get the 3rd results page with 100 organic results on it:

https://rt.serpmaster.com/?q=lorem%20ipsum&num=100&page=3&access_token=1234abcd


Receiving Parsed Data

All results delivered from SERPMaster endpoint can be sent in either "JSON" or "HTML" format. Parsed data is delivered in a JSON format and nested according to SERPs features. There are only two values to add: either an empty field (which returns raw HTML) or "JSON". 

https://rt.serpmaster.com/?q=lorem%20ipsum&num=100&page=3&parse=json&access_token=1234abcd


Setting a Device

SERPMaster accepts device and Browser parameters. By sending these parameters in your initial payload, you will receive data as displayed for the devices in question. There are three broad categories we offer ("desktop", "mobile", "tablet") which can then be narrowed down based on operating systems or browsers.

https://rt.serpmaster.com/?q=lorem%20ipsum&num=100&page=3&device=desktop&parse=json&access_token=1234abcd

SERPMaster supports many more parameters for search requests. We have only gone through the most useful ones so far. For most cases, using the parameters outlined above should be enough.

Additionally, you can set requests to ignore spell check, use localized languages, setting a specific Google domain and filtering results by specific type of content. You can find every parameter and its accepted value in our documentation.

DocsTerms and ConditionsPrivacy Policy

All rights reserved © 2020

Artboard 11