Search Parameters
The Search API provides several parameters to control what results are returned. The query parameter is required, while locale, page, safe, and time_range are optional.
query
The query parameter contains the search query you want to submit.
It is the only required parameter.
Requirements
- Type:
string - Minimum length:
1 - Maximum length:
1000
Example
{
"query": "web scraping best practice"
}Required Parameter
Every Search request must include query. The value must contain between 1 and 1,000 characters.
locale
The locale parameter specifies the locale for the search.
It accepts:
- A language code, such as
en - A language-region tag, such as
en-US all
Example
{
"query": "web scraping",
"locale": "en-US"
}The locale parameter is optional.
page
The page parameter specifies which result page to fetch.
Requirements
- Type:
integer - Minimum:
1 - Maximum:
20 - Default:
1
Example
{
"query": "web scraping",
"page": 2
}The OpenAPI defines example values of 1, 2, and 20.
Page Limit
The page value must be between 1 and 20.
safe
The safe parameter controls the safe-search filtering level.
The accepted values are:
| Value | Description |
|---|---|
off | Safe-search filtering is disabled. |
moderate | Moderate safe-search filtering. |
strict | Strict safe-search filtering. |
The default value is off.
Example
{
"query": "web scraping",
"safe": "moderate"
}The OpenAPI only defines these three values for safe.
Accepted Values
Use only off, moderate, or strict for the safe parameter.
time_range
The time_range parameter restricts results to a recency window.
The accepted values are:
| Value | Recency window |
|---|---|
day | Day |
week | Week |
month | Month |
year | Year |
Example
{
"query": "web scraping",
"time_range": "week"
}The parameter is optional and can be set to day, week, month, or year.
Using Multiple Parameters
You can combine the optional parameters with the required query parameter in a single request.
For example:
{
"query": "web scraping best practice",
"locale": "en-US",
"page": 2,
"safe": "moderate",
"time_range": "month"
}The same parameters can be sent to:
POST /v1/searchComplete Request Example
The following request uses all available Search request parameters:
curl -X POST "YOUR_SCRAPER_API_URL/v1/search" \
-H "X-Api-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"query": "web scraping best practice",
"locale": "en-US",
"page": 2,
"safe": "moderate",
"time_range": "month"
}'Parameter Summary
| Parameter | Required | Type | Default | Accepted values / limits |
|---|---|---|---|---|
query | Yes | string | — | 1–1000 characters |
locale | No | string | — | Language code, language-region tag, or all |
page | No | integer | 1 | 1–20 |
safe | No | string | off | off, moderate, strict |
time_range | No | string | — | day, week, month, year |
These are the complete request parameters defined by the current SearchRequest schema.
What's Next?
You now know how to configure a Search request.
Continue with Understanding Search Results to learn how the API structures the returned search results.