Endpoints
Search
Description
This endpoint performs a Google web search and optionally scrapes the content of the top search results, returning both search results and scraped content.
Endpoint
POST /api/v1/search
Headers
- Content-Type:
application/json
- Authorization: Bearer
<API_KEY>
(required)
Request Body
{
"query": "string", // Required. The search query.
"country": "string", // Optional. Country code for location bias (e.g., "US" for United States).
"location": "string", // Optional. Specific location to focus the search (e.g., "New York, NY").
"language": "string", // Optional. Language code for the search results (e.g., "en" for English).
"dateRange": "string", // Optional. Can be "anyTime", "pastHour", "pastDay", "pastWeek", "pastMonth", or "pastYear".
"page": "number", // Optional. Page number for paginated results.
"scrapeResults": "boolean", // Optional. Whether to scrape top search results. Default: false.
"numResultsToScrape": "number", // Optional. Number of top results to scrape. Default: 3. Max: 10.
"scrapeOptions": {
// Optional. Options for scraping, if scrapeResults is true.
"format": "string", // Optional. The format of the output. Valid values: "markdown", "html", "screenshot". Default: "markdown".
"cleaned": "boolean" // Optional. Whether the output should be cleaned. Default: true.
}
}
Responses
Success (200)
Returns the search results and optionally scraped content.
{
"searchParameters": {
"q": "string", // The search query
"type": "string", // e.g., "search"
"engine": "string", // e.g., "google"
"gl": "string", // Optional. Google country code
"hl": "string" // Optional. Host language
},
"organic": [
{
"title": "string",
"link": "string",
"snippet": "string",
"position": "number",
"sitelinks": [
{
"title": "string",
"link": "string"
}
],
"date": "string", // Optional. Publication date if available
"scrapeOutput": {
// Optional. Present only if scraping was requested
"title": "string",
"metadata": "object",
"url": "string",
"format": "string", // "markdown", "html", or "screenshot"
"cleaned": "boolean",
"content": "string"
}
}
],
"featuredSnippet": {
"title": "string",
"link": "string",
"snippet": "string",
"position": "number",
"type": "string"
},
"relatedSearches": [
{
"query": "string"
}
],
"peopleAlsoAsk": [
{
"question": "string",
"snippet": "string",
"title": "string",
"link": "string"
}
]
}
- Content-Type: application/json
- X-RateLimit-Limit: The rate limit for the user.
- X-RateLimit-Remaining: The remaining number of requests for the user.
Bad Request (400)
Returned if the request is invalid.
{
"error": "Error message describing the issue"
}
Unauthorized (401)
Returned if the API key is invalid or missing.
{
"error": "Invalid or missing Authorization header"
}
Internal Server Error (500)
Returned if there’s an error during the search or scraping process.
{
"error": "Failed to perform search: [error message]"
}
Example Request
curl -X POST https://app.dumplingai.com/api/v1/search \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
"query": "Dumpling ai",
"country": "US",
"language": "en",
"dateRange": "pastMonth",
"scrapeResults": true,
"numResultsToScrape": 3,
"scrapeOptions": {
"format": "html",
"cleaned": false
}
}'
Notes
- The maximum number of results that can be scraped is 10.
- If
numResultsToScrape
is set higher than 10, it will be capped at 10. - If
numResultsToScrape
is not provided, the default value is 3. - Credit usage:
- Base cost for search: 3 credits per page of results
- Additional credits for scraping are charged normally on the /scrape endpoint.
- If
scrapeResults
is false, no URLs will be scraped and thescrapeOutput
field will not be present in the organic results. - The
scrapeOptions
field allows customization of the scraping process:format
can be “markdown”, “html”, or “screenshot”. If not specified, “markdown” is used.cleaned
determines whether the output should be cleaned. If not specified, it defaults to true.
- The
dateRange
parameter can be used to filter results by date. Valid values are “anyTime”, “pastHour”, “pastDay”, “pastWeek”, “pastMonth”, or “pastYear”. - The
country
parameter should be a two-letter country code (e.g., “US” for United States). - The
location
parameter can be used to focus the search on a specific area. You can find a list of supported locations at GET:/api/v1/google-locations
- The
language
parameter can be used to specify the desired language for the search results. - Usage is recorded with detailed parameters for each request.
- Events may be logged for analytics purposes if enabled.
Rate Limiting
Rate limit headers (X-RateLimit-Limit
and X-RateLimit-Remaining
) are included in the response to indicate the user’s current rate limit status.