OpenAPI Specification
openapi: 3.0.3
info:
title: ValueSERP Images Search API
description: Real-time Google SERP data API supporting organic search, shopping, news, images, places, and product results via simple GET requests authenticated with an API key. Returns structured JSON with organic results, ads, knowledge graphs, answer boxes, AI overviews, and more. Operated by Traject Data.
version: '1.0'
contact:
name: ValueSERP Support
url: https://trajectdata.com/serp/value-serp-api/
termsOfService: https://trajectdata.com/serp/value-serp-api/
x-api-id: valueserp-search
servers:
- url: https://api.valueserp.com
description: ValueSERP Production API
security:
- apiKeyQuery: []
tags:
- name: Search
description: Google organic web search results.
paths:
/search:
get:
operationId: googleSearch
summary: Google Search (Organic)
description: Retrieve real-time Google organic search results for a given keyword. Returns organic listings, ads, knowledge graph data, answer boxes, AI overviews, related questions, and more.
tags:
- Search
parameters:
- $ref: '#/components/parameters/api_key'
- $ref: '#/components/parameters/q'
- $ref: '#/components/parameters/location'
- $ref: '#/components/parameters/location_auto'
- $ref: '#/components/parameters/google_domain'
- $ref: '#/components/parameters/gl'
- $ref: '#/components/parameters/hl'
- $ref: '#/components/parameters/lr'
- $ref: '#/components/parameters/cr'
- $ref: '#/components/parameters/page'
- $ref: '#/components/parameters/max_page'
- $ref: '#/components/parameters/safe'
- $ref: '#/components/parameters/nfpr'
- $ref: '#/components/parameters/filter'
- $ref: '#/components/parameters/tbs'
- $ref: '#/components/parameters/uule'
- $ref: '#/components/parameters/time_period'
- $ref: '#/components/parameters/time_period_min'
- $ref: '#/components/parameters/time_period_max'
- $ref: '#/components/parameters/knowledge_graph_id'
- name: include_ai_overview
in: query
required: false
schema:
type: boolean
description: Adds Google's AI overview content to the response. Costs 1 additional credit when an AI overview is returned.
- name: include_ai_overview_paa
in: query
required: false
schema:
type: boolean
description: Includes AI overview answers in related questions (People Also Ask). Costs 1 credit per overview.
- name: include_answer_box
in: query
required: false
schema:
type: boolean
description: When true, includes the featured snippet/answer box as the first item in organic results.
- name: flatten_results
in: query
required: false
schema:
type: boolean
description: Flattens inline videos, inline images, and other inline content blocks so they appear inline in results.
- name: fields
in: query
required: false
schema:
type: string
description: Comma-separated list of top-level response objects to return (web-only feature). Reduces response size.
example: organic_results,knowledge_graph
- name: order_online
in: query
required: false
schema:
type: boolean
description: Returns pickup/delivery ordering info for restaurants (US only). Costs 2 credits instead of 1.
- name: ads_optimized
in: query
required: false
schema:
type: boolean
description: Optimizes ad return rates in the response. Costs 3 additional credits.
responses:
'200':
description: Successful search response
content:
application/json:
schema:
$ref: '#/components/schemas/SearchResponse'
example:
request_info:
success: true
search_metadata:
id: SEARCH_ID
google_url: https://www.google.com/search?q=pizza
total_time_taken: 1.23
search_parameters:
q: pizza
gl: us
hl: en
organic_results:
- position: 1
title: Best Pizza Recipes
link: https://example.com/pizza
domain: example.com
snippet: Find the best pizza recipes here.
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'402':
$ref: '#/components/responses/PaymentRequired'
'429':
$ref: '#/components/responses/TooManyRequests'
'500':
$ref: '#/components/responses/InternalServerError'
'503':
$ref: '#/components/responses/ServiceUnavailable'
components:
parameters:
hl:
name: hl
in: query
required: false
schema:
type: string
default: en
description: Determines the Google UI language to return results in. BCP-47 language code.
example: en
safe:
name: safe
in: query
required: false
schema:
type: string
enum:
- active
- 'off'
description: Safe search filter setting.
example: active
uule:
name: uule
in: query
required: false
schema:
type: string
description: Custom Google UULE parameter to override the location.
lr:
name: lr
in: query
required: false
schema:
type: string
description: Limits results to pages in the specified language.
example: lang_en
location_auto:
name: location_auto
in: query
required: false
schema:
type: boolean
default: true
description: When true, automatically updates gl and hl parameters based on the built-in location value. Defaults to true.
time_period_min:
name: time_period_min
in: query
required: false
schema:
type: string
pattern: ^\d{2}/\d{2}/\d{4}$
description: Custom time period start date in MM/DD/YYYY format. Required when time_period=custom.
example: 01/01/2024
google_domain:
name: google_domain
in: query
required: false
schema:
type: string
default: google.com
description: The Google domain to use for the search.
example: google.com
filter:
name: filter
in: query
required: false
schema:
type: integer
enum:
- 0
- 1
default: 1
description: Toggle similar/omitted result filters. 1 enables filtering (default), 0 disables it.
example: 1
location:
name: location
in: query
required: false
schema:
type: string
description: Geographic location for the search. Accepts location names (e.g., "manhattan,new york,united states") or GPS coordinates (e.g., "lat 43.437677,lon 3.8392765").
example: united states
page:
name: page
in: query
required: false
schema:
type: integer
minimum: 1
default: 1
description: The results page number to retrieve. Defaults to 1.
example: 1
nfpr:
name: nfpr
in: query
required: false
schema:
type: integer
enum:
- 0
- 1
description: Exclude auto-corrected spelling results. Set to 1 to exclude, 0 to include (default).
example: 0
gl:
name: gl
in: query
required: false
schema:
type: string
default: us
description: Determines the Google country to use for the query. ISO 3166-1 alpha-2 country code.
example: us
cr:
name: cr
in: query
required: false
schema:
type: string
description: Limits results to pages from the specified country.
example: countryUS
tbs:
name: tbs
in: query
required: false
schema:
type: string
description: Custom Google TBS parameter value for advanced filtering.
api_key:
name: api_key
in: query
required: true
schema:
type: string
description: Your ValueSERP API key. Use "demo" for testing limited queries.
example: demo
knowledge_graph_id:
name: knowledge_graph_id
in: query
required: false
schema:
type: string
description: Specific Google Knowledge Graph entity ID.
example: /m/0jg24
time_period:
name: time_period
in: query
required: false
schema:
type: string
enum:
- last hour
- last day
- last week
- last month
- last year
- custom
description: Filter results by time period.
example: last week
time_period_max:
name: time_period_max
in: query
required: false
schema:
type: string
pattern: ^\d{2}/\d{2}/\d{4}$
description: Custom time period end date in MM/DD/YYYY format. Required when time_period=custom.
example: 12/31/2024
q:
name: q
in: query
required: true
schema:
type: string
description: The keyword or search query to use.
example: pizza
max_page:
name: max_page
in: query
required: false
schema:
type: integer
minimum: 1
description: Retrieve multiple result pages in a single API request. Specifies the maximum page number to retrieve.
example: 3
schemas:
AnswerBox:
type: object
description: Featured snippet / answer box data.
properties:
type:
type: string
description: Type of answer box (e.g., organic, list, table).
title:
type: string
description: Answer box title.
answer:
type: string
description: The direct answer text.
link:
type: string
format: uri
description: Source URL for the answer.
ErrorResponse:
type: object
description: Error response body.
properties:
request_info:
type: object
properties:
success:
type: boolean
example: false
message:
type: string
description: Human-readable error message.
RequestInfo:
type: object
description: Meta-information about the API request status.
properties:
success:
type: boolean
description: Whether the request was processed successfully.
message:
type: string
description: Status message (present on errors or incidents).
credits_used:
type: integer
description: Number of credits consumed by this request.
credits_remaining:
type: integer
description: Number of credits remaining in the account.
SearchParameters:
type: object
description: Echo of the parameters used for the search.
properties:
q:
type: string
description: The search query keyword used.
search_type:
type: string
description: The type of search performed.
gl:
type: string
description: Country code used.
hl:
type: string
description: Language code used.
google_domain:
type: string
description: Google domain used.
SearchResponse:
type: object
description: Google organic search results response.
properties:
request_info:
$ref: '#/components/schemas/RequestInfo'
search_metadata:
$ref: '#/components/schemas/SearchMetadata'
search_parameters:
$ref: '#/components/schemas/SearchParameters'
organic_results:
type: array
items:
$ref: '#/components/schemas/OrganicResult'
description: Organic search result listings.
ads:
type: array
items:
$ref: '#/components/schemas/AdResult'
description: Paid advertisement results.
knowledge_graph:
$ref: '#/components/schemas/KnowledgeGraph'
answer_box:
$ref: '#/components/schemas/AnswerBox'
related_questions:
type: array
items:
$ref: '#/components/schemas/RelatedQuestion'
description: People Also Ask related questions.
related_searches:
type: array
items:
type: object
properties:
query:
type: string
description: Related search query text.
link:
type: string
format: uri
description: Related searches suggested by Google.
pagination:
type: object
properties:
current:
type: integer
description: Current page number.
next:
type: string
format: uri
description: URL for the next page of results.
other_pages:
type: object
additionalProperties:
type: string
description: Map of page numbers to page URLs.
SearchMetadata:
type: object
description: Metadata about the search execution.
properties:
id:
type: string
description: Unique identifier for this search request.
google_url:
type: string
format: uri
description: The Google URL that was scraped to generate results.
total_time_taken:
type: number
format: float
description: Total time taken to process the request in seconds.
created_at:
type: string
format: date-time
description: Timestamp when the search was created.
AdResult:
type: object
description: A paid advertisement result.
properties:
position:
type: integer
description: Ad position.
title:
type: string
description: Ad headline.
link:
type: string
format: uri
description: Ad destination URL.
display_link:
type: string
description: Display URL shown in the ad.
snippet:
type: string
description: Ad description text.
KnowledgeGraph:
type: object
description: Google Knowledge Graph panel data.
properties:
title:
type: string
description: Entity name.
type:
type: string
description: Entity type or category.
description:
type: string
description: Brief description of the entity.
source:
type: object
properties:
name:
type: string
link:
type: string
format: uri
image:
type: object
properties:
src:
type: string
format: uri
alt:
type: string
RelatedQuestion:
type: object
description: A People Also Ask related question.
properties:
question:
type: string
description: The related question text.
answer:
type: string
description: Answer text for the question.
link:
type: string
format: uri
description: Source URL for the answer.
OrganicResult:
type: object
description: A single organic search result.
properties:
position:
type: integer
description: Position/rank of the result on the page.
title:
type: string
description: Title of the result.
link:
type: string
format: uri
description: URL of the result.
domain:
type: string
description: Domain of the result URL.
snippet:
type: string
description: Text snippet/excerpt from the result page.
cached_page_link:
type: string
format: uri
description: Link to Google's cached version of the page.
related_pages_link:
type: string
format: uri
description: Link to related pages on the same domain.
sitelinks:
type: array
items:
type: object
properties:
title:
type: string
link:
type: string
format: uri
description: Sitelinks shown beneath the result.
responses:
InternalServerError:
description: Internal Server Error - Retry after a delay; contact support if the issue persists.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
PaymentRequired:
description: Payment Required - Your ValueSERP account has run out of available credits or there is a payment issue.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
Unauthorized:
description: Unauthorized - The api_key supplied is not valid.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
BadRequest:
description: Bad Request - Invalid parameters or unsupported parameter combinations.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
ServiceUnavailable:
description: Service Unavailable - Returned during parsing incidents. Requests are not charged. Use skip_on_incident=true to opt out automatically.
headers:
Retry-After:
schema:
type: integer
description: Seconds to wait before retrying.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
TooManyRequests:
description: Too Many Requests - Your plan's rate limit has been exceeded.
headers:
Retry-After:
schema:
type: integer
description: Seconds to wait before retrying.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
securitySchemes:
apiKeyQuery:
type: apiKey
in: query
name: api_key
description: API key for authentication. Pass as the api_key query parameter. Use "demo" as the key for testing.