Endpoints
Search News
Description
This endpoint performs a Google News search using the provided query and optional parameters. It returns information about news articles matching the search criteria.
Endpoint
POST /api/v1/search-news
Headers
- Content-Type:
application/json
- Authorization: Bearer
<API_KEY>
(required)
Request Body
{
"query": "string", // Required. The search query for Google News.
"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.
}
Responses
Success (200)
Returns the search results from Google News.
{
"searchParameters": {
"q": "string",
"gl": "string", // Optional. Country code if provided.
"type": "string",
"location": "string", // Optional. Location if provided.
"engine": "string"
},
"news": [
{
"title": "string",
"link": "string",
"snippet": "string",
"date": "string",
"source": "string",
"imageUrl": "string",
"position": "number"
}
]
}
- 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": "query parameter is required"
}
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 process.
{
"error": "Failed to perform news search: [error message]"
}
Example Request
curl -X POST https://app.dumplingai.com/api/v1/search-news \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
"query": "climate change",
"country": "US",
"language": "en"
}'
Notes
- This endpoint uses 3 credits per page of results.
- 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.