Links
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.