# Real-Time Web Search API (`openweb-ninja/real-time-web-search`) Actor

Fast and reliable Google Search & SERP API - organic results, AI Overviews, AI Mode, videos, places, news, knowledge graph, people also ask, related searches, and more in real-time.

- **URL**: https://apify.com/openweb-ninja/real-time-web-search.md
- **Developed by:** [OpenWeb Ninja](https://apify.com/openweb-ninja) (community)
- **Categories:** SEO tools, Developer tools
- **Security:** Limited permissions
- **Stats:** 3 total users, 2 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.50 / 1,000 api requests

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Real-Time Web Search API

Real-Time Web Search is a fast and reliable Google Search and SERP API. It returns organic results, AI Overviews, AI Mode answers, videos, places, news, knowledge graph, people also ask, and related searches as structured JSON via REST.

What it returns: full and lightweight SERP results across organic, AI Overviews, AI Mode, and rich result types.

This actor runs the same Real-Time Web Search API that developers use on RapidAPI and OpenWeb Ninja, with the same endpoints, parameters and output.

### What you can do with it

- Track keyword rankings and SERP features for SEO tools
- Collect search results at scale for market and competitor research
- Ground AI agents and LLM apps with fresh web results and AI Mode answers
- Monitor brand mentions and news coverage across the web
- Find leads and websites matching any query or advanced search operator

### Endpoints

Pick the endpoint in the **Endpoint** field. Each run makes one call to that endpoint and writes its results to the dataset.

#### Search Light

`GET /search-light`

Lightning fast endpoint for getting organic web search results in real-time. Returns raw organic results only, without AI Overviews, knowledge graph, or a total result count - use the Search endpoint when you need the full SERP. Supports all Google Advanced Search operators (site:, inurl:, intitle:, etc). Each request consumes 1 request credit.

| Parameter | Required | Description |
|---|---|---|
| `q` | Yes |  |
| `num` | No |  Default: `10`. |
| `gl` | No |  Default: `us`. |
| `hl` | No |  Default: `en`. |

#### Search

`GET /search`

Get real-time full-depth web search results via the heavy serp path, including organic results, ads, AI overviews, knowledge graph, places, top stories, inline videos, answer box, and discussions. Supports Google Search parameters (gl, hl, tbs, etc.) and city-level geo targeting. Note: Each request to this endpoint consumes 2 request credits.

| Parameter | Required | Description |
|---|---|---|
| `q` | Yes | Search query. Supports all Google Advanced Search operators (site:, inurl:, intitle:, etc). |
| `num` | No | Maximum number of organic results to return per request (1-10). Default: `10`. |
| `start` | No | Number of results to skip for pagination (default 0). Default: `0`. |
| `gl` | No | The country / region for which to make the query. 2-letter country code, see ISO 3166-1 alpha-2. Default: `us`. |
| `hl` | No | The language to use for the search (Google's hl parameter). 2-letter language code, see ISO 639-1 alpha-2. Default: `en`. |
| `location` | No | Where the search originates from. Recommended to specify at city level to simulate a real user's search (e.g. London, England, United Kingdom). |
| `uule` | No | Google's own encoded location string (e.g. w+CAIQICIgU2VhdHRsZSxXYXNoaW5ndG9uLFVuaXRlZCBTdGF0ZXM=), passed to Google as is. Use it instead of location when you already generate uule values. |
| `device` | No | The device to simulate for the search. Mobile and tablet return Google's mobile SERP layout, whose rankings and features can differ from desktop. Allowed values: desktop (default), mobile, tablet. Values: `desktop`, `mobile`, `tablet`. Default: `desktop`. |
| `lr` | No | Restrict search results to a specific language. Uses lang\_{two-letter language code} with | as delimiter (e.g. lang_fr|lang_de searches French and German pages only). |
| `tbs` | No | Advanced Google search parameters that aren't available using regular query parameters (e.g. qdr:d for the last day, qdr:w for the last week). |
| `nfpr` | No | Exclude results of the auto-corrected query when the original query is misspelled with nfpr=1, and include them with nfpr=0 (default). Values: `0`, `1`. Default: `0`. |
| `nhr` | No | Exclude 'People also ask' style related questions from the results with nhr=1. Include them with nhr=0 (default). Values: `0`, `1`. Default: `0`. |
| `fetch_ai_overviews` | No | Whether to return AI Overviews when available (false by default). When true or 1, if AI Overviews are available, each request consumes two request credits instead of one. Default: `false`. |
| `return_organic_result_video_thumbnail` | No | Whether to return a base64-encoded video_thumbnail field for organic video results (false by default). Default: `false`. |

#### Search by URL

`GET /search-by-url`

Fetch a Google search results page from a full Google search URL, exactly as given, instead of building it from q, gl, hl and the other search parameters. Returns the parsed results, or the raw HTML of the page (data.html) with return_raw_html=true. With expand_ai_overviews=true the AI Overview is returned fully expanded, and the response also includes text ads when Google shows them.

| Parameter | Required | Description |
|---|---|---|
| `url` | Yes | Full Google search URL to fetch, passed to Google as is. Must be a https://www.google.{domain}/search URL with a q parameter. Any other Google search parameters in the URL (gl, hl, start, tbs, uule, etc.) are kept. |
| `device` | No | The device to simulate for the search. Allowed values: desktop (default), mobile (an iPhone with iOS Safari), tablet (an iPad with Safari). Supported with and without expand_ai_overviews. Values: `desktop`, `mobile`, `tablet`. Default: `desktop`. |
| `return_raw_html` | No | Whether to return the raw HTML of the results page, without any parsing, as data.html with its length in data.html_length (false by default). Default: `false`. |
| `expand_ai_overviews` | No | Whether to return the AI Overview fully expanded (false by default). Default: `false`. |

#### AI Mode

`POST /ai-mode` (parameters go in the JSON body)

Send a prompt/query and get structured results and reference links from Google's AI Mode. POST variant of the AI Mode endpoint - accepts the same parameters in a JSON request body, with no URL length limit (recommended for long prompts). Each request consumes 2 request credits.

| Parameter | Required | Description |
|---|---|---|
| `prompt` | Yes | AI Mode prompt. |
| `session_token` | No | Specify a session token from previous AI Mode response to continue the chat from the same point (preserving history in context for continuous conversation). |
| `tbs` | No | This parameter defines advanced search parameters that aren't available using regular query parameters (to be searched). |
| `location` | No | Where the AI Mode search originates from, for location-dependent prompts such as local businesses, weather or events. Recommended to specify at city level to simulate a real user's search (e.g. |
| `uule` | No | Google's own encoded location string (e.g. w+CAIQICIgU2VhdHRsZSxXYXNoaW5ndG9uLFVuaXRlZCBTdGF0ZXM=), passed to Google as is. Use it instead of location when you already generate uule values. |
| `gl` | No | The country / region for which to make the query. 2-letter country code, see ISO 3166-1 alpha-2. Default: `us`. |
| `hl` | No | The language to use for the search (Google's hl parameter). 2-letter country code, see ISO 639-1 alpha-2. Default: `en`. |
| `attachments` | No | Optional list of document URLs (PDF) to attach to the prompt, as plain URL strings. Up to 5 files, 10 MB each. Images are not supported. Attaching one or more documents is charged a flat 1 extra request credit. |

#### People Also Ask

`GET /people-also-ask`

Get the People Also Ask block for a Google search query, optionally with the answer body and source link for each question.

| Parameter | Required | Description |
|---|---|---|
| `q` | Yes |  |
| `gl` | No |  Default: `us`. |
| `hl` | No |  Default: `en`. |
| `location` | No |  |
| `lr` | No | Restrict search results to a specific language. Uses lang\_{two-letter language code} with | as delimiter (e.g. lang_fr|lang_de searches French and German pages only). |
| `tbs` | No | Advanced Google search parameters that aren't available using regular query parameters (e.g. qdr:d for the last day, qdr:w for the last week). |
| `nfpr` | No | Exclude results of the auto-corrected query when the original query is misspelled with nfpr=1, and include them with nfpr=0 (default). Values: `0`, `1`. Default: `0`. |
| `nhr` | No | Exclude 'People also ask' style related questions from the results with nhr=1. Include them with nhr=0 (default). Those questions are exactly what this endpoint returns, so nhr=1 can produce an empty list. Values: `0`, `1`. Default: `0`. |
| `fetch_answers` | No |  Values: `true`, `false`, `0`, `1`. Default: `true`. |

#### Search Light Bulk

`POST /search-light-bulk` (parameters go in the JSON body)

Perform real-time web searches for up to 100 queries in a single request (each query is counted/charged as a request credit).

| Parameter | Required | Description |
|---|---|---|
| `queries` | Yes | Query or list of queries to search (max 100 items; each trimmed; each ≤ 5000 chars; duplicates removed server-side). |
| `limit` | No | Number of results to return (1–300; capped at 300). Default: `10`. |
| `gl` | No | Geo/region code (lowercased). Default: `us`. |
| `hl` | No | Language code (lowercased). Default: `en`. |

### Example input

```json
{
  "endpoint": "/search-light",
  "q": "how to build a website"
}
```

### Example output

One dataset item per result. A Search Light item looks like this (trimmed):

```json
{
  "title": "Website Builder - Create a Free Website | Canva",
  "snippet": "Create free professional websites on your own domain in minutes. Canva's website builder makes launching a one-page website easy with customizable templates ...",
  "url": "https://www.canva.com/website-builder/",
  "domain": "www.canva.com",
  "position": 1
}
```

The run's key-value store `OUTPUT` record holds the request parameters, the request id and any non-list fields of the response (for example a pagination cursor).

### Pricing

Pay per event: you pay per API request, at the same rates as our API plans. Most runs are one request; some parameters (such as fetching several pages at once) count as several, exactly as they do on the API.

| Apify plan | Price per 1,000 requests |
|---|---|
| Free | $4.00 |
| Starter (Bronze) | $1.25 |
| Scale (Silver) | $0.75 |
| Business (Gold) and above | $0.50 |

A request that fails is not charged.

### Using it from code

Run it through the [Apify API](https://docs.apify.com/api/v2) or a client library, with the input above as the JSON body:

```bash
curl -X POST "https://api.apify.com/v2/acts/openweb-ninja~real-time-web-search/run-sync-get-dataset-items?token=<YOUR_APIFY_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"endpoint":"/search-light","q":"how to build a website"}'
```

Need higher volume or a direct REST API? Real-Time Web Search API is also available as an API on [OpenWeb Ninja](https://www.openwebninja.com/api/real-time-web-search) and [RapidAPI](https://rapidapi.com/letscrape-6bRBa3QguO5/api/real-time-web-search).

### Support

For custom plans, high volumes or anything else:

- Email: support@openwebninja.com
- Discord: https://discord.gg/wxJxGsZgha

# Actor input Schema

## `endpoint` (type: `string`):

Which endpoint of the API to call. Each endpoint uses the parameters listed in its section below; parameters of other endpoints are ignored.

## `q` (type: `string`):

<br><br><em>Used by: Search Light, Search, People Also Ask. Required for Search Light, Search, People Also Ask.</em>

## `num` (type: `integer`):

<br><br><em>Used by: Search Light, Search.</em>

## `gl` (type: `string`):

<br><br><em>Used by: Search Light, Search, AI Mode, People Also Ask, Search Light Bulk.</em>

## `hl` (type: `string`):

<br><br><em>Used by: Search Light, Search, AI Mode, People Also Ask, Search Light Bulk.</em>

## `start` (type: `integer`):

Number of results to skip for pagination (default 0).<br><br><em>Used by: Search.</em>

## `location` (type: `string`):

Where the search originates from. Recommended to specify at city level to simulate a real user's search (e.g. London, England, United Kingdom). See https://openwebninja.s3.us-east-1.amazonaws.com/locations.json for the list of supported locations.<br><br><em>Used by: Search, AI Mode, People Also Ask.</em>

## `uule` (type: `string`):

Google's own encoded location string (e.g. w+CAIQICIgU2VhdHRsZSxXYXNoaW5ndG9uLFVuaXRlZCBTdGF0ZXM=), passed to Google as is. Use it instead of location when you already generate uule values. Cannot be combined with location.<br><br><em>Used by: Search, AI Mode.</em>

## `device` (type: `string`):

The device to simulate for the search. Mobile and tablet return Google's mobile SERP layout, whose rankings and features can differ from desktop. Allowed values: desktop (default), mobile, tablet.<br><br><em>Used by: Search, Search by URL.</em>

## `lr` (type: `string`):

Restrict search results to a specific language. Uses lang\_{two-letter language code} with | as delimiter (e.g. lang_fr|lang_de searches French and German pages only).<br><br><em>Used by: Search, People Also Ask.</em>

## `tbs` (type: `string`):

Advanced Google search parameters that aren't available using regular query parameters (e.g. qdr:d for the last day, qdr:w for the last week).<br><br><em>Used by: Search, AI Mode, People Also Ask.</em>

## `nfpr` (type: `string`):

Exclude results of the auto-corrected query when the original query is misspelled with nfpr=1, and include them with nfpr=0 (default).<br><br><em>Used by: Search, People Also Ask.</em>

## `nhr` (type: `string`):

Exclude 'People also ask' style related questions from the results with nhr=1. Include them with nhr=0 (default).<br><br><em>Used by: Search, People Also Ask.</em>

## `fetch_ai_overviews` (type: `boolean`):

Whether to return AI Overviews when available (false by default). When true or 1, if AI Overviews are available, each request consumes two request credits instead of one.<br><br><em>Used by: Search.</em>

## `return_organic_result_video_thumbnail` (type: `boolean`):

Whether to return a base64-encoded video_thumbnail field for organic video results (false by default).<br><br><em>Used by: Search.</em>

## `url` (type: `string`):

Full Google search URL to fetch, passed to Google as is. Must be a https://www.google.{domain}/search URL with a q parameter. Any other Google search parameters in the URL (gl, hl, start, tbs, uule, etc.) are kept.<br><br><strong>Examples:</strong><br><br><code>https://www.google.com/search?q=best+vpn+2026\&gl=us\&hl=en</code><br><br><code>https://www.google.co.uk/search?q=weather+london\&hl=en</code><br><br><em>Used by: Search by URL. Required for Search by URL.</em>

## `return_raw_html` (type: `boolean`):

Whether to return the raw HTML of the results page, without any parsing, as data.html with its length in data.html_length (false by default). With expand_ai_overviews=true, this is the whole page with the AI Overview expanded.<br><br><em>Used by: Search by URL.</em>

## `expand_ai_overviews` (type: `boolean`):

Whether to return the AI Overview fully expanded (false by default). Parsed responses then include has_ai_overviews, the parsed ai_overviews and text ads (when Google shows them); with return_raw_html=true, data.html is the whole page HTML with the AI Overview expanded. Works with every device (desktop, mobile, tablet).<br><br><strong>Note:</strong> With expand_ai_overviews=true each request consumes 3 request credits instead of 2.<br><br><em>Used by: Search by URL.</em>

## `prompt` (type: `string`):

AI Mode prompt.<br><br><em>Used by: AI Mode. Required for AI Mode.</em>

## `session_token` (type: `string`):

Specify a session token from previous AI Mode response to continue the chat from the same point (preserving history in context for continuous conversation).<br><br><em>Used by: AI Mode.</em>

## `attachments` (type: `array`):

Optional list of document URLs (PDF) to attach to the prompt, as plain URL strings. Up to 5 files, 10 MB each. Images are not supported. Attaching one or more documents is charged a flat 1 extra request credit.<br><br><em>Used by: AI Mode.</em>

## `fetch_answers` (type: `string`):

<br><br><em>Used by: People Also Ask.</em>

## `queries` (type: `array`):

Query or list of queries to search (max 100 items; each trimmed; each ≤ 5000 chars; duplicates removed server-side).<br><br><em>Used by: Search Light Bulk. Required for Search Light Bulk.</em>

## `limit` (type: `integer`):

Number of results to return (1–300; capped at 300).<br><br><em>Used by: Search Light Bulk.</em>

## Actor input object example

```json
{
  "endpoint": "/search-light",
  "q": "how to build a website",
  "num": 10,
  "gl": "us",
  "hl": "en",
  "start": 0,
  "device": "desktop",
  "nfpr": "0",
  "nhr": "0",
  "fetch_ai_overviews": false,
  "return_organic_result_video_thumbnail": false,
  "url": "https://www.google.com/search?q=best+vpn+2026&gl=us&hl=en",
  "return_raw_html": false,
  "expand_ai_overviews": false,
  "prompt": "How to make a pizza step by step?",
  "fetch_answers": "true",
  "limit": 10
}
```

# Actor output Schema

## `results` (type: `string`):

One dataset item per result of the API call.

## `summary` (type: `string`):

Endpoint, parameters, request id, billed requests and any non-list response fields (such as a pagination cursor).

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "q": "how to build a website",
    "num": 10,
    "gl": "us",
    "hl": "en",
    "start": 0,
    "limit": 10
};

// Run the Actor and wait for it to finish
const run = await client.actor("openweb-ninja/real-time-web-search").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "q": "how to build a website",
    "num": 10,
    "gl": "us",
    "hl": "en",
    "start": 0,
    "limit": 10,
}

# Run the Actor and wait for it to finish
run = client.actor("openweb-ninja/real-time-web-search").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "q": "how to build a website",
  "num": 10,
  "gl": "us",
  "hl": "en",
  "start": 0,
  "limit": 10
}' |
apify call openweb-ninja/real-time-web-search --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,openweb-ninja/real-time-web-search"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/bxtga3xMTEML6lw5t/builds/Y685h9M3wnbuKFeGO/openapi.json