# Real-Time SERP Data API

> Complete reference documentation for the OpenWeb Ninja Real-Time SERP Data API. Includes code examples, data samples, and usage guides for searching every Google vertical - Web, Images, Videos, Shorts, News, Shopping, Books, Maps, and Forums - plus AI Overviews, AI Mode, People Also Ask, and autocomplete in Real-Time.

## Overview

Complete reference documentation for the OpenWeb Ninja Real-Time SERP Data API. Includes code examples, data samples, and usage guides for searching every Google vertical - Web, Images, Videos, Shorts, News, Shopping, Books, Maps, and Forums - plus AI Overviews, AI Mode, People Also Ask, and autocomplete in Real-Time.

This API exposes 15 REST endpoints (Search, Full Search, Light Search, Search, Search, Search, Search, Search, Search, Search, Search, AI Overviews, AI Mode, People Also Ask, Autocomplete), returning structured JSON. See the endpoints below for parameters and full URLs.

Need help integrating? Contact support@openwebninja.com.
For high volume / large scale plans, please contact support@openwebninja.com.

## Endpoints

### GET /web/search - Search
Get real-time organic search results from across the web, AI Overviews, total count, and more.
Parameters:
- **q** (string, required, e.g. `how to build a website`)
- fetch_ai_overviews (boolean)
- num (integer, default: `10`)
- start (integer, default: `0`)
- gl (string, default: `us`)
- hl (string, default: `en`)
- tbs (string)
- location (string)
- device (string, default: `desktop`, allowed: desktop | mobile): The device user agent to use for the call.
- nfpr (string, e.g. `0`)
- lr (string, e.g. `0`)
- return_organic_result_video_thumbnail (boolean)
- extra_speed (boolean)
Full URL: `https://api.openwebninja.com/realtime-serp-data/web/search`

### GET /web/search-full - Full 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.
Parameters:
- **q** (string, required, e.g. `albert einstein`): Search query. Supports all Google Advanced Search operators (site:, inurl:, intitle:, etc).
- gl (string, default: `us`): The country / region for which to make the query. 2-letter country code, see ISO 3166-1 alpha-2.
- hl (string, default: `en`): The language to use for the search (Google's hl parameter). 2-letter language code, see ISO 639-1 alpha-2.
- tbs (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).
- location (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://api.openwebninja.com/google-search-locations.json for the list of supported locations.
- lr (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).
- nfpr (string, default: `0`, allowed: 0 | 1): Exclude results of the auto-corrected query when the original query is misspelled with nfpr=1, and include them with nfpr=0 (default).
- nhr (string, default: `0`, allowed: 0 | 1): Exclude 'People also ask' style related questions from the results with nhr=1. Include them with nhr=0 (default).
- num (integer, default: `10`): Maximum number of organic results to return per request (1-10).
- start (integer, default: `0`): Number of results to skip for pagination (default 0).
- fetch_ai_overviews (boolean, default: `false`): 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.
- return_organic_result_video_thumbnail (boolean, default: `false`): Whether to return a base64-encoded video_thumbnail field for organic video results (false by default).
Full URL: `https://api.openwebninja.com/realtime-serp-data/web/search-full`

### GET /web/search-light - Light Search
Lightning fast endpoint for getting organic search results from across the web in real-time.
Parameters:
- **q** (string, required, e.g. `how to build a website`)
- limit (string, default: `10`)
Full URL: `https://api.openwebninja.com/realtime-serp-data/web/search-light`

### POST /web/search-light - Light Search (Bulk)
Perform real-time web searches for up to 100 queries in a single request (each query is counted/charged as a request credit).
Full URL: `https://api.openwebninja.com/realtime-serp-data/web/search-light`

### GET /images/search - Search
Get real-time image search results from across the web.
Parameters:
- **query** (string, required, e.g. `beach`): Search query / keyword
- limit (integer, default: `10`): Maximum number of results to return.
- size (string, default: `any`, allowed: any | large | medium | icon | 400x300_and_more | 640x480_and_more | 800x600_and_more | 1024x768_and_more | 2mp_and_more | 4mp_and_more | 6mp_and_more | 8mp_and_more | 10mp_and_more | 12mp_and_more | 15mp_and_more | 20mp_and_more | 40mp_and_more | 70mp_and_more): Find images of a specific size.
- color (string, default: `any`, allowed: any | red | orange | yellow | green | teal | blue | purple | pink | white | gray | black | brown | full | transparent | grayscale): Find images with a specific dominant color.
- type (string, default: `any`, allowed: any | face | photo | clipart | lineart | animated): Find images of a specific type.
- time (string, default: `any`, allowed: any | day | week | month | year): Find images last updated in a specific time range.
- usage_rights (string, default: `any`, allowed: any | creative_commons | commercial): Find images with specific usage rights / license / copyright.
- file_type (string, default: `any`, allowed: any | jpg | jpeg | png | gif | svg | webp | ico | raw): Find images of a specific format / file type.
- aspect_ratio (string, default: `any`, allowed: any | tall | square | wide | panoramic): Find images with a specific aspect ratio.
- country (string, e.g. `us`): Find images published in a specific country / region. Allowed values: 2-letter country code, see ISO 3166-1 alpha-2.
- safe_search (string, default: `blur`, allowed: false | blur | true): How to show explicit content in your search results, like sexual activity and graphic violence.
- region (string, default: `us`): The country / region from which to make the query. Allowed values: 2-letter country code, see ISO 3166-1 alpha-2.
- fields (string, e.g. `title,size,thumbnail_url,position`): A comma separated list of image fields to include in the response (field projection). By default all fields are returned.
Full URL: `https://api.openwebninja.com/realtime-serp-data/images/search`

### GET /videos/search - Search
Search Google Videos for any query and get real-time video results.
Parameters:
- **query** (string, required): The video search query. **Examples:** `how to invest` `product demo software` `lebron james highlights`
- page (integer, default: `1`): Page number for pagination. Each page returns up to 10 video results. **Allowed values:** `1` and above.
- country (string, default: `us`): Country code of the country to return video results for. See https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2 for supported values. **Default:** `us`
- language (string, default: `en`): The language of the results, specified as a 2-letter language code - see ISO 639-1. **Default:** `en`
- time_period (string, default: `any`, allowed: any | last_hour | last_day | last_week | last_month | last_year): Filter results to a specific time period. Cannot be used together with `date_from`/`date_to`. **Allowed values:** `any`, `last_hour`, `last_day`, `last_week`, `last_month`, `last_year` **Default:** `any`
- date_from (string): Start date for a custom date range filter, in `MM/DD/YYYY` format. Must be provided together with `date_to`. Cannot be used together with `time_period` (other than `any`). **Example:** `01/01/2026`
- date_to (string): End date for a custom date range filter, in `MM/DD/YYYY` format. Must be provided together with `date_from`. **Example:** `04/29/2026`
- sort_by (string, default: `relevance`, allowed: relevance | date): Sort order for the results. **Allowed values:** `relevance`, `date` **Default:** `relevance`
- duration (string, default: `any`, allowed: any | short | medium | long): Filter results by video duration. **Allowed values:** `any`, `short` (under 4 minutes), `medium` (4 to 20 minutes), `long` (over 20 minutes) **Default:** `any`
- safe (string, default: `off`, allowed: off | active): Safe search setting to filter explicit content. **Allowed values:** `off`, `active` **Default:** `off`
Full URL: `https://api.openwebninja.com/realtime-serp-data/videos/search`

### GET /shorts/search - Search
Get real-time short video search results from across the web with pagination and filtering support.
Parameters:
- **query** (string, required): Search query / keyword.
- page (number, default: `1`): Results page to return (pagination / scrolling)
- time (string, default: `any`, allowed: any | day | week | month | year): Find shorts posted in a specific relative time range.
- posted_date_from (string): Find shorts posted after a specific date (e.g. 1/19/2025).
- posted_date_to (string): Find shorts posted before a specific date (e.g. 3/19/2025).
- high_quality (boolean): Return only shorts of high quality.
- closed_captioned (boolean): Return only shorts with closed captions.
Full URL: `https://api.openwebninja.com/realtime-serp-data/shorts/search`

### GET /news/search - Search
Search Google News for any query and get real-time news results.
Parameters:
- **query** (string, required): The news search query. **Examples:** `climate change` `artificial intelligence startups` `bitcoin price 2026`
- page (integer, default: `1`): Page number for pagination. Each page returns up to 10 news results. **Allowed values:** `1` and above.
- country (string, default: `us`): Country code of the country to return news results for. See https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2 for supported values. **Default:** `us`
- language (string, default: `en`): The language of the results, specified as a 2-letter language code - see ISO 639-1. **Default:** `en`
- time_period (string, default: `any`, allowed: any | last_hour | last_day | last_week | last_month | last_year): Filter results to a specific time period. Cannot be used together with `date_from`/`date_to`. **Allowed values:** `any`, `last_hour`, `last_day`, `last_week`, `last_month`, `last_year` **Default:** `any`
- date_from (string): Start date for a custom date range filter, in `MM/DD/YYYY` format. Must be provided together with `date_to`. Cannot be used together with `time_period` (other than `any`). **Example:** `01/01/2026`
- date_to (string): End date for a custom date range filter, in `MM/DD/YYYY` format. Must be provided together with `date_from`. **Example:** `04/10/2026`
- sort_by (string, default: `relevance`, allowed: relevance | date): Sort order for the results. **Allowed values:** `relevance`, `date` **Default:** `relevance`
- safe (string, default: `off`, allowed: off | active): Safe search setting to filter explicit content. **Allowed values:** `off`, `active` **Default:** `off`
Full URL: `https://api.openwebninja.com/realtime-serp-data/news/search`

### GET /forums/search - Search
Search in Discussions and Forums across the web.
Parameters:
- **query** (string, required): Search query
- time (string, default: `any`, allowed: any | hour | day | week | month | year): Return results published in a specific time range.
- start (integer, default: `0`): Number of results to skip (for pagination).
- country (string, default: `us`): The country / region for which to make the query (Google's gl parameter). Allowed values: 2-letter country code, see ISO 3166-1 alpha-2.
- language (string, default: `en`): The language to use for the search (Google's hl parameter). Allowed values: 2-letter country code, see ISO 639-1 alpha-2.
Full URL: `https://api.openwebninja.com/realtime-serp-data/forums/search`

### GET /books/search - Search
Get real-time book search results from across the web with pagination and filtering support.
Parameters:
- **query** (string, required, e.g. `good thriller`)
- page (number, default: `1`)
- document_type (string, default: `any`, allowed: any | books | newspapers | magazines): Find books of a specific type.
- view_type (string, default: `any`, allowed: any | preview_and_full_view | full_view): Find books with a specific view type (preview / full).
- publication_year_from (number)
- publication_year_to (number)
- country (string, default: `us`)
- language (string, default: `en`)
Full URL: `https://api.openwebninja.com/realtime-serp-data/books/search`

### GET /shopping/search - Search
Search and get product listings (including full product details), sponsored products, and search filters / refinements from Google Shopping.
Parameters:
- **q** (string, required): Search query / keyword
- country (string, default: `us`): Country code of the region/country to return offers for. Allowed values: See https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2.
- language (string, default: `en`): The language of the results. Allowed values: See https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes.
- page (integer, default: `1`): Results page to return (each page contains up to 40 product results).
- limit (integer, default: `40`): Maximum number of products to return.
- sort_by (string, default: `BEST_MATCH`, allowed: BEST_MATCH | TOP_RATED | LOWEST_PRICE | HIGHEST_PRICE): Sort product offers by best match, top rated, lowest or highest price.
- min_price (number): Only return product offers with price greater than a certain value
- max_price (number): Only return product offers with price lower than a certain value
- product_condition (string, default: `ANY`, allowed: ANY | NEW | USED | REFURBISHED): Only return products with a specific condition.
- stores (string): Only return product offers from specific stores. Accepts a single or a comma delimited list of store names (e.g. best buy,walmart,amazon).
- free_returns (boolean, default: `false`): Only return product offers that offer free returns.
- free_shipping (boolean, default: `false`): Only return product offers that offer free shipping/delivery.
- on_sale (boolean, default: `false`): Only return product offers that are currently on sale.
- shoprs (string): The parameter controls filtering, along with the q parameter. It should be used in combination with the updated q parameter, which now contains the name of the filter applied next to your original query. You can get the shoprs filter value from the response of this endpoint, under the filters response field. In addition, it can be obtained directly from Google Shopping and used with the endpoint.
- return_filters (boolean): Whether to return filters / refinements from Google Shopping (left refinement filters panel on desktop).
Full URL: `https://api.openwebninja.com/realtime-serp-data/shopping/search`

### GET /maps/search - Search
Search local businesses on Google Maps with an option to pull emails and social profile links from their website (see the `extract_emails_and_contacts` parameter below).
Parameters:
- **query** (string, required, e.g. `Hotels in San Francisco, USA`): Search query / keyword **Examples:** `Plumbers near New-York, USA` `Bars in 94102, USA`
- limit (integer, default: `20`): Maximum number of businesses to return. **Allowed values:** `1-500`
- lat (string, default: `37.359428`): Latitude of the coordinates point from which the query is applied - recommended to use so that results are biased towards this location. Defaults to some central location in the region (see the region parameter).
- lng (string, default: `-121.925337`): Longitude of the coordinates point from which the query is applied - recommended to use so that results are biased towards this location. Defaults to some central location in the region (see the region parameter).
- zoom (string, default: `13`): Zoom level on which to make the search (the viewport is determined by lat, lng and zoom).
- language (string, default: `en`): Set the language of the results. For a list of supported language codes see *https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes*.
- region (string, default: `us`): Query Google Maps from a particular region or country. For a list of supported region/country codes see *https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes (Alpha-2 code)*.
- subtypes (string, e.g. `Plumber,Carpenter,Electrician`): Find businesses with specific subtypes, specified as a comma separated list of types (business categories). For the complete list of types, see *https://daltonluka.com/blog/google-my-business-categories*. **Examples:** `Plumber,Carpenter,Electrician` `Night club,Dance club,Bar,Pub`
- verified (boolean): Only return verified businesses
- business_status (string, e.g. `OPEN`): Find businesses with specific status, specified as a comma separated list of the following values: `OPEN, CLOSED_TEMPORARILY, CLOSED` **Examples:** `OPEN` `CLOSED_TEMPORARILY,CLOSED`
- extract_emails_and_contacts (boolean, default: `false`): Extract emails, contacts and social profiles for each business in the response. In case true, businesses will be enriched with a emails_and_contacts field with emails, phones, Facebook, LinkedIn, Instagram and other social profiles. **Note:** in case `true`, the endpoint will scrape emails and contacts from the business website (in case non-empty). For each such business, the API will charge an additional credit.
- fields (string, e.g. `business_id,type,phone_number,full_address`): A comma separated list of business fields to include in the response (field projection). By default all fields are returned.
Full URL: `https://api.openwebninja.com/realtime-serp-data/maps/search`

### GET /ai-overviews/ai-overviews - AI Overviews
Get Google Search AI Overviews, including text parts (paragraphs and lists) and reference links.
Parameters:
- **q** (string, required): Search query.
- location (string): Where you want the search to originate from. It is recommended to specify location at the city level in order to simulate a real user’s search (e.g. London, England, United Kingdom).
- gl (string, default: `us`): The country / region for which to make the query. 2-letter country code, see ISO 3166-1 alpha-2.
- hl (string, default: `en`): The language to use for the search (Google's hl parameter). 2-letter country code, see ISO 639-1 alpha-2.
Full URL: `https://api.openwebninja.com/realtime-serp-data/ai-overviews/ai-overviews`

### GET /ai-mode/ai-mode - AI Mode
Send a prompt/query and get structured results and reference links from Google AI Mode.
Parameters:
- **prompt** (string, required): AI Mode prompt.
- session_token (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).
- gl (string, default: `us`): The country / region for which to make the query. 2-letter country code, see ISO 3166-1 alpha-2.
- hl (string, default: `en`): The language to use for the search (Google's hl parameter). 2-letter country code, see ISO 639-1 alpha-2.
Full URL: `https://api.openwebninja.com/realtime-serp-data/ai-mode/ai-mode`

### POST /ai-mode/ai-mode - AI Mode (POST)
Send a prompt/query and get structured results and reference links from Google AI Mode.
Parameters:
- **prompt** (string, required, e.g. `How to make a pizza step by step?`): AI Mode prompt.
- session_token (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).
- tbs (string): This parameter defines advanced search parameters that aren't available using regular query parameters (to be searched).
- gl (string, default: `us`): The country / region for which to make the query. 2-letter country code, see ISO 3166-1 alpha-2.
- hl (string, default: `en`): The language to use for the search (Google's hl parameter). 2-letter country code, see ISO 639-1 alpha-2.
Full URL: `https://api.openwebninja.com/realtime-serp-data/ai-mode/ai-mode`

### GET /people-also-ask/people-also-ask - 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.
Parameters:
- **q** (string, required, e.g. `apple inc`)
- gl (string, default: `us`)
- hl (string, default: `en`)
- location (string)
- fetch_answers (string, default: `true`, allowed: true | false | 0 | 1)
Full URL: `https://api.openwebninja.com/realtime-serp-data/people-also-ask/people-also-ask`

### GET /autocomplete/autocomplete - Autocomplete
Get query suggestions from Google Search, including Knowledge Graph information when available.
Parameters:
- **query** (string, required): Autocomplete / typeahead search query.
- language (string, default: `en`): Set the language of the results. Allowed values: 2-letter language code, see ISO 639-1.
- region (string, default: `us`): The country / region from which to make the query. Allowed values: 2-letter country code, see ISO 3166-1 alpha-2.
- user_agent (string, default: `desktop`, allowed: desktop | mobile): Device type to use for the search.
- cursor_pointer (string): Cursor pointer defines the position of cursor for the query provided, position starts from 0 which is a case where cursor is placed before the query. If not provided acts as cursor is placed in the end of query (Google's cp parameter).
Full URL: `https://api.openwebninja.com/realtime-serp-data/autocomplete/autocomplete`

### POST /autocomplete/autocomplete - Autocomplete (Bulk)
Get query suggestions for multiple queries in a single request (up to 50 queries).
Full URL: `https://api.openwebninja.com/realtime-serp-data/autocomplete/autocomplete`

## Base URL and Authentication

- Base URL: `https://api.openwebninja.com/realtime-serp-data`
- Auth: API key in the `x-api-key` header. Get a key by subscribing (free tier available) at https://app.openwebninja.com/api/realtime-serp-data

## Links

- API page: https://www.openwebninja.com/api/realtime-serp-data
- Get an API key / subscribe: https://app.openwebninja.com/api/realtime-serp-data
- Pricing & plans: https://app.openwebninja.com/api/realtime-serp-data/pricing
- Website: https://www.openwebninja.com
- OpenAPI spec: https://openwebninja.s3.us-east-1.amazonaws.com/portal/openapi/realtime_serp_data.yaml
- Support: support@openwebninja.com

_Last updated: 2026-05-27_