LogoLogo
Nimble HomeLoginCreate an Account
  • Home
  • Quick Start Tutorials
    • Tutorial Library
      • Track SEO and SEM Ranking
      • Reddit as a Guerilla Marketing Strategy
  • Nimble Platform
    • Nimble Platform Overview
    • Online Pipelines
      • Supermarkets
        • ASDA
        • Tesco Groceries
        • Sainsbury’s
        • Morrisons
      • eCommerce
      • Restaurants
        • Yelp
        • Tabelog
        • Uber Eats Japan
        • Demaecan
        • Uber Eats US
      • Real Estate
        • Zillow
  • Nimble SDK
    • SDK Overview
    • Web API
      • Web API Overview
      • API Product Specs
      • Nimble Web API Quick Start Guide
        • Introduction
        • Nimble APIs Authentication
        • Real-time URL request
        • Delivery methods
        • Batch processing
        • Response codes
        • FAQs
      • Nimble Web API Functions
        • Realtime, Async & Batch Request
        • Geo Location Targeting
        • Javascript Rendering
        • Page Interaction
          • Wait (delay)
          • Wait for Selector
          • Wait and Click
          • Wait and Type
          • Scroll
          • Scroll to
          • Infinite Scrolling
          • Capturing Screenshots
          • Collecting Cookies
          • Executing HTTP Requests
          • Operation Reference
        • Network Capture
          • Filter by URL Matching
          • Filter By Resource Type
            • Real World Demo: Capturing Ajax Requests
          • Wait for Requests
          • Capturing XHR without Rendering
          • Operation Reference
        • Data Parsing
          • Parsing Templates
          • Merge Dynamic Parser
        • Custom Headers & Cookies
        • General Params
      • Vertical Endpoints
        • SERP API
          • Real-time search request
          • Getting local data
          • Browsing SERP pagination
          • Delivery methods
          • Batch Processing
          • Endpoints and Response Codes
        • Maps API
          • Searching for places
          • Getting information about a place
          • Collecting reviews
          • Delivery methods
          • Batch processing
          • Endpoints and Response Codes
    • Web Retrieval API
      • Web Retrieval API Overview
    • Proxy API
      • Nimble IP Overview
      • Nimble IP Quick Start Guide
        • Send a request
        • Nimble IP Autentication
        • Geotargeting and session control
        • Response codes
        • FAQs
      • Nimble IP Functions
        • Country/state/city geotargeting
        • Controlling IP rotation
        • Geo-sessions: longer, stickier, more accurate sessions
        • Using IPv6 Proxies
        • Response Codes
      • Integration Guides
        • Incogniton
        • Kameleo
        • VMLogin
        • AdsPower
        • FoxyProxy
        • Android
        • Multilogin
        • iOS
        • SwitchyOmega
        • Windows
        • macOS
        • Proxifier
        • MuLogin
        • Puppeteer
        • Selenium
        • Scrapy
    • Client Libraries
      • Installation
      • Quick Start
    • LangChain Integration
  • Technologies
    • Browserless Drivers
      • API Driver-Based Pricing
    • IP Optimization Models
    • AI Parsing Skills
  • Management Tools
    • Nimble Dashboard
      • Exploring the User Dashboard
      • Managing Pipelines
      • Reporting and Analytics
      • Account Settings
      • Experimenting with the Playground
      • Billing and history
    • Nimble Admin API
      • Admin API basics
      • Admin API reference
  • General
    • Onboarding Guide
      • Getting started with Nimble's User Dashboard
      • Nimble IP Basics
      • Nimble API Basics
      • Helpful Resources
    • FAQs
      • Account Settings and Security
      • Billing and Pricing
      • Tools and Integrations
      • Nimble API
      • Nimble IP
    • Deprecated APIs
      • E-commerce API
        • E-commerce API Authentication
        • Real-time product request
        • Real-time product search request
        • Delivery methods
        • Batch Processing
        • Endpoints and Response Codes
      • Unlocker Proxy Overview
        • Unlocker Proxy Quick Start Guide
          • Real-time request
          • FAQs
        • Unlocker Proxy FAQ
Powered by GitBook
On this page
  • Request Options
  • Response
  • Response Codes
  1. Nimble SDK
  2. Web API
  3. Vertical Endpoints
  4. SERP API

Real-time search request

PreviousSERP APINextGetting local data

Last updated 3 months ago

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 currently supports the following search engines:

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 .

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": "US",
    "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

google_sge

bing_search

yandex_search

The search engine from which to collect results.

tab

Optional (default = null)

Enum: news

Select the tab of results to return from google_search engine. Currently, news is supported.

num_results

Optional

Integer

Set the mount of retuned search 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

state

Optional

String

For targeting US states (does not include regions or territories in other countries). Two-letter state code, e.g. NY, IL, etc.

city

Optional

String

locale

Optional (default = en)

String

String | LCID standard locale used for the URL request. Alternatively, user can use auto for automatic locale based on country targeting.

location

Optional

String

parse

Optional (default = true)

Boolean

Instructs Nimble whether to structure the results into a JSON format or return the raw HTML.

ads_optimization

Optional (default = false)

Boolean

This flag increases the number of paid ads (sponsored ads) in the results. It works by running the requests in 'incognito' mode (requires JS rendering)

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.

For targeting large cities and metro areas around the globe. When targeting major US cities, you must include state as well.

Search Google through a custom geolocation, regardless of country or proxy location. eg: "London,Ohio,United States". See for more information.

Jan 25: Due to latest Google changes, the ads_optimization flag requires JS rendering which forces the request to use and hence increase the request's computing costs.

Nimble SERP API
Web API Authentication
VX8 Driver
Getting local data
Click here for a list of available cities.