Comment on page

Real-time search request

A real-time request allows users to collect data from the search of a single search term. The collected data is returned directly to the user performing the request. The Nimble SERP API currently supports the following search engines:
Google Search
Bing Search
Yandex Search
To send a request, use the /realtime/serp endpoint with the following syntax:
Nimble APIs requires that a base64 encoded credential string be sent with every request to authenticate your account. For detailed examples, see SERP API Authentication.
cURL
Python
Node.js
Go
curl -X POST 'https://api.webit.live/api/v1/realtime/serp' \
--header 'Authorization: Basic <credential string>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "search_engine": "google_search",
    "country": "FR",
    "locale": "fr",
    "query": "Sample search phrase"
}'
import requests
​
url = 'https://api.webit.live/api/v1/realtime/serp'
headers = {
    'Authorization': 'Basic <credential string>',
    'Content-Type': 'application/json'
}
data = {
    "search_engine": "google_search",
    "country": "FR",
    "locale": "fr",
    "query": "Sample search phrase"
}
​
response = requests.post(url, headers=headers, json=data)
​
print(response.status_code)
print(response.json())
​
const axios = require('axios');
​
const url = 'https://api.webit.live/api/v1/realtime/serp';
const headers = {
  'Authorization': 'Basic <credential string>',
  'Content-Type': 'application/json'
};
const data = {
  "search_engine": "google_search",
  "country": "FR",
  "locale": "fr",
  "query": "Sample search phrase"
};
​
axios.post(url, data, { headers })
  .then(response => {
    console.log(response.status);
    console.log(response.data);
  })
  .catch(error => {
    console.error(error);
  });
​
package main
​
import (
	"bytes"
	"fmt"
	"net/http"
	"encoding/json"
)
​
func main() {
	url := "https://api.webit.live/api/v1/realtime/serp"
	payload := []byte(`{
		"search_engine": "google_search",
		"country": "FR",
		"locale": "fr",
		"query": "Sample search phrase"
	}`)
	headers := map[string]string{
		"Authorization":  "Basic <credential string>",
		"Content-Type":   "application/json",
	}
​
	req, err := http.NewRequest("POST", url, bytes.NewBuffer(payload))
	if err != nil {
		fmt.Println(err)
		return
	}
​
	for key, value := range headers {
		req.Header.Set(key, value)
	}
​
	client := &http.Client{}
	resp, err := client.Do(req)
	if err != nil {
		fmt.Println(err)
		return
	}
	defer resp.Body.Close()
​
	fmt.Println(resp.StatusCode)
	// Read the response body if needed
	// body, err := ioutil.ReadAll(resp.Body)
	// fmt.Println(string(body))
}
​
Every request sent through Nimble API is automatically routed through Nimble IP - our premium proxy network!
Request Options
Parameter
Required
Type
Description
query
Required
String
The term or phrase to search for.
search_engine
Required
Enum: google_search | bing_search | yandex_search
The search engine from which to collect results.
domain
Optional
String
Search through a custom top-level domain of Google. eg: "co.uk"
country
Optional (default = all)
String
Country used to access the target URL, use ISO Alpha-2 Country Codes i.e. US, DE, GB
locale
Optional (default = en)
String
LCID standard locale used for the URL request.
location
Optional
String
Search Google through a custom geolocation, regardless of country or proxy location. eg: "London,Ohio,United States". See Getting local data for more information.
parse
Optional (default = true)
Enum: true | false
Instructs Nimble whether to structure the results into a JSON format or return the raw HTML.
Response
Headers
X-Task-ID: string
Payload examples:
If parsing is disabled, the resulting data will be the raw HTML of the requested SERP. If parsing is enabled, a JSON object with a parsed version of the SERP will be delivered in addition to the raw HTML, which is contained under the html_content property.
200 OK
{
  "status": "success",
  "html_content": "<html>The SERP's full HTML</html>",
  "parsing": {
    "status": "success",
    "entities": {
      "InlineVideos": [
        {
          "entityType": "InlineVideos",
          "videos": [
            {
              "channel": "FilmsActu",
              "date": "15 nov. 2021",
              "length": "1:52",
              "source": "YouTube",
              "thumbnail": "https://i.ytimg.com/vi/b1r_UR5-0tY/mqdefault.jpg?sqp=-oaymwEECHwQRg&rs=AMzJL3kXJ1udP5Pc4cVSVd0uvOsYe0mTCg",
              "title": "LE TEST Bande Annonce (2021)",
              "url": "https://www.youtube.com/watch?v=b1r_UR5-0tY"
            },
                        ...
          ]
        }
      ],
      "OrganicResult": [
        {
          "displayed_url": "https://fr.wikipedia.org › wiki › Test",
          "entityType": "OrganicResult",
          "position": 1,
          "sitelinks": [
            {
              "title": "Test (méthode) - Wikipédiahttps://fr.wikipedia.org › wiki › Test_(méthode)",
              "url": "https://fr.wikipedia.org/wiki/Test_(m%C3%A9thode)"
            }
          ],
          "snippet": "Le mot test est polysémique en français et issu de deux étymologies latines distinctes : testis (témoin) et testa (récipient rond).",
          "title": "Test - Wikipédia",
          "url": "https://fr.wikipedia.org/wiki/Test"
        },
        ...
            "Pagination": [
        {
          "current_page": 1,
          "entityType": "Pagination",
          "next_page_url": "/search?q=test&hl=fr&ei=6GvmYtLMIYKOlwS3wLTgDA&start=10&sa=N&ved=2ahUKEwjS4LSgh6P5AhUCx4UKHTcgDcwQ8NMDegQIAhBP",
          "other_page_urls": {
            "2": "/search?q=test&hl=fr&ei=6GvmYtLMIYKOlwS3wLTgDA&start=10&sa=N&ved=2ahUKEwjS4LSgh6P5AhUCx4UKHTcgDcwQ8tMDegQIAhA9",
            ...
          }
        }
      ],
        "RelatedSearch": [
        {
          "entityType": "RelatedSearch",
          "query": "test quiz",
          "url": "/search?hl=fr&q=Test+quiz&sa=X&ved=2ahUKEwjS4LSgh6P5AhUCx4UKHTcgDcwQ1QJ6BAglEAE"
        },
            ],
            "SearchInformation": [
        {
          "entityType": "SearchInformation",
          "query_displayed": "Sample search phrase",
          "total_results": "Environ 15 850 000 000 résultats "
        }
      ]
    },
    "total_entities_count": 19,
    "entities_count": {
      "InlineVideos": 1,
      "OrganicResult": 8,
      "Pagination": 1,
      "RelatedSearch": 8,
      "SearchInformation": 1
    },
    "metrics": {}
  },
  "url": "https://www.google.com/search?q=Sample+search+phrase&hl=fr",
  "nimble_pagination": {
    "next_page_url": "https://api.webit.live/api/v1/realtime/serp?parse=true&query=test&search_engine=google_search&format=json&render=false&country=FR&locale=fr&ei=vPBQZLakI86ckdUPwOuB6A0&sa=N&ved=2ahUKEwi28uXqwNb-AhVOTqQEHcB1AN0Q8NMDegQIBxAW&start=10",
    "other_pages": [
      "https://api.webit.live/api/v1/realtime/serp?parse=true&query=test&search_engine=google_search&format=json&render=false&country=FR&locale=fr&ei=vPBQZLakI86ckdUPwOuB6A0&sa=N&ved=2ahUKEwi28uXqwNb-AhVOTqQEHcB1AN0Q8tMDegQIBxAE&start=10",
      "https://api.webit.live/api/v1/realtime/serp?parse=true&query=test&search_engine=google_search&format=json&render=false&country=FR&locale=fr&ei=vPBQZLakI86ckdUPwOuB6A0&sa=N&ved=2ahUKEwi28uXqwNb-AhVOTqQEHcB1AN0Q8tMDegQIBxAG&start=20",
      ...
      ]
    }
}
500 Error
{
          "status": "error",
        "task_id": "<task_id>",
        "msg": "can't download the query response - please try again"
}
400 Input Error
{
        "status": "failed",
        "msg": error
}
Response Codes
Status
Description
200
OK.
400
The requested resource could not be reached.
401
Unauthorized/invalid credental string
500
Internal service error.
501
An error was encountered by the proxy service.

Parameter	Required	Type	Description
query	Required	String	The term or phrase to search for.
search_engine	Required	Enum: google_search \| bing_search \| yandex_search	The search engine from which to collect results.
domain	Optional	String	Search through a custom top-level domain of Google. eg: "co.uk"
country	Optional (default = all)	String	Country used to access the target URL, use ISO Alpha-2 Country Codes i.e. US, DE, GB
locale	Optional (default = en)	String	LCID standard locale used for the URL request.
location	Optional	String	Search Google through a custom geolocation, regardless of country or proxy location. eg: "London,Ohio,United States". See Getting local data for more information.
parse	Optional (default = true)	Enum: true \| false	Instructs Nimble whether to structure the results into a JSON format or return the raw HTML.

Status	Description
200	OK.
400	The requested resource could not be reached.
401	Unauthorized/invalid credental string
500	Internal service error.
501	An error was encountered by the proxy service.

SERP API Authentication

Getting local data