OpenAPI Specification
openapi: 3.0.3
info:
title: ValueSERP Search Images News 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: News
description: Google News article results.
paths:
/search#news:
get:
operationId: googleNews
summary: Google News Search
description: Retrieve real-time Google News results for a given keyword. Set search_type=news. Supports time period filtering, language, country, and sorting.
tags:
- News
parameters:
- $ref: '#/components/parameters/api_key'
- name: search_type
in: query
required: true
schema:
type: string
enum:
- news
description: Must be set to "news".
example: news
- $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'
- name: sort_by
in: query
required: false
schema:
type: string
enum:
- relevance
- date
description: Sort news results by relevance or date.
example: relevance
- name: show_duplicates
in: query
required: false
schema:
type: boolean
description: Display duplicate results when sort_by=date is used.
- name: exclude_if_modified
in: query
required: false
schema:
type: boolean
description: Exclude results from queries that were modified by Google.
responses:
'200':
description: Successful news search response
content:
application/json:
schema:
$ref: '#/components/schemas/NewsResponse'
'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
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:
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.
NewsResult:
type: object
description: A single Google News article result.
properties:
position:
type: integer
description: Position in results.
title:
type: string
description: Article headline.
link:
type: string
format: uri
description: Article URL.
source:
type: string
description: News source/publisher name.
date:
type: string
description: Publication date (relative or absolute).
snippet:
type: string
description: Article excerpt.
thumbnail:
type: string
format: uri
description: Article thumbnail image URL.
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.
NewsResponse:
type: object
description: Google News search results response.
properties:
request_info:
$ref: '#/components/schemas/RequestInfo'
search_metadata:
$ref: '#/components/schemas/SearchMetadata'
search_parameters:
$ref: '#/components/schemas/SearchParameters'
news_results:
type: array
items:
$ref: '#/components/schemas/NewsResult'
description: News article results.
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.
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.