What is the Web Search API?
The Web Search API lets you search the internet just like Google, Bing, or any search engine - but programmatically! Get structured JSON results from:Web & News
Search websites and recent news articles
Media
Find images and videos from across the web
Specialized
Search products and academic papers
No AI processing - This returns raw search results. Want AI-powered answers? Use the Answer API instead.
Pricing (Simple & Transparent)
Standard Searches
$0.001 per searchGeneral, News, Images, Videos, Scholar= $1 for 1,000 searches
Shopping Searches
$0.002 per searchProduct search with prices & ratings= $2 for 1,000 searches
Every response includes a
cost field showing exactly what you paid for that request.Before You Start
Authentication
All requests need your API key in theAuthorization header:
Your First Search (2-Minute Start)
Let’s search the web in under 2 minutes!Done! You just searched the web programmatically. You’ll get up to 10 results with titles, links, and snippets.
Search Types Explained
The Web Search API supports 6 different search types. Each returns different data structures.Quick Reference
| Search Type | Use For | Cost | Example Query |
|---|---|---|---|
| general | Regular web search | $0.001 | ”how to learn python” |
| news | Recent news articles | $0.001 | ”tech industry layoffs” |
| images | Find images | $0.001 | ”golden gate bridge sunset” |
| videos | Find videos | $0.001 | ”how to tie a tie tutorial” |
| shopping | Product search | $0.002 | ”iphone 15 pro” |
| scholar | Academic papers | $0.001 | ”climate change mitigation” |
General Search (Web-Wide)
Search across the entire web with optional filters. Endpoint:POST /api/v2/web_search
What You Get
- Up to 10 results
- Title, link, snippet for each
- Publication date (when available)
- Works with
recencyanddomainFilter
Basic Example
Filter by Time (Recent Results Only)
Get only recent results with therecency parameter.
hour, day, week, month, year
Filter by Domain
Control which websites appear in your results.News Search
Get recent news articles from news sources worldwide.What You Get
- Up to 10 news articles
- Title, link, snippet, date
- News source name
- Article thumbnail image
- Publication position
Example
Image Search
Find images from across the web with metadata.What You Get
- Up to 10 images
- Full-size image URL
- Thumbnail URL
- Image dimensions (width, height)
- Source website
- Page containing the image
Example
Use case ideas:
- Build image galleries
- Visual search features
- Content discovery tools
- Inspiration boards
Video Search
Find videos from YouTube, Vimeo, and other platforms.What You Get
- Up to 10 videos
- Title, link, snippet
- Video duration
- Channel/creator name
- Upload date
- Thumbnail image
- Direct video URL (when available)
Example
Shopping Search
Search for products with prices, ratings, and merchant info.What You Get
- Up to 10 products
- Product name and image
- Current price
- Merchant/marketplace name
- Rating and review count
- Product ID
- Direct link to product page
Example
Use case ideas:
- Price comparison tools
- Product aggregators
- Deal finders
- E-commerce research
Scholar Search
Search academic papers, journals, and scholarly articles.What You Get
- Up to 10 academic papers
- Paper title and link
- Abstract/excerpt
- Publication info (journal, conference)
- Publication year
- Citation count
- PDF link (when available)
Example
Use case ideas:
- Research aggregators
- Citation tools
- Academic discovery platforms
- Literature review automation
Request Parameters (Complete Reference)
Endpoint:POST /api/v2/web_search
Required Parameters
Your search query. Be specific for better results.Examples:
- ✅ “best Italian restaurants in Boston”
- ✅ “iPhone 15 pro max 256gb price”
- ❌ “restaurants” (too vague)
Optional Parameters
Type of search to perform.Options:
general- Web-wide search ($0.001)news- News articles ($0.001)images- Image search ($0.001)videos- Video search ($0.001)shopping- Product search ($0.002)scholar- Academic papers ($0.001)
Country code for localized results. Uses ISO 3166-1 alpha-2 codes.Common values:
us, uk, ca, au, de, fr, es, it, jp, in, br, mxFilter results by time period. Only works with
general and news searches.Options: hour, day, week, month, yearInclude or exclude specific domains. Only works with Exclude domains (note the Mix both:
general search.Include domains:- prefix):Response Format
Every response has this structure:Response Fields by Search Type
- General Search
- News Search
- Image Search
- Video Search
- Shopping Search
- Scholar Search
Real-World Examples
Example 1: News Aggregator
Build a news aggregator that tracks multiple topics.Example 2: Price Comparison Tool
Compare prices across multiple stores.Example 3: Academic Research Tool
Find relevant papers for your research.Error Handling
Error Format
All errors use this structure:Common Errors
401 - Authentication Error
401 - Authentication Error
Missing or invalid API keyFix: Add your API key to the Authorization header.
400 - Validation Errors
400 - Validation Errors
Invalid Search TypeFix: Use one of: Fix: Provide a non-empty search query.
general, news, images, videos, shopping, scholarEmpty Query429 - Rate Limit
429 - Rate Limit
Too many requestsFix: Wait and retry with exponential backoff.
500 - Server Error
500 - Server Error
Search failedFix: Retry the request. If it persists, contact support.
Robust Error Handling
Best Practices
💰 Cost Optimization
Use the right search type
- Don’t use
shopping(0.001) works - Shopping search is specifically for product comparisons
- Search results don’t change every second
- Cache for 1 hour for most use cases
- Cache for 5 minutes for news/recent content
- Search multiple queries together
- Process in parallel for better performance
⚡ Performance Tips
Keep queries focused
- Specific queries = better results
- “iPhone 15 pro max 256gb price” > “phone”
recencyfor time-sensitive contentdomainFilterto reduce noiselocationfor localized results
- You get up to 10 results
- Process only what you need
- Top 3-5 results are usually most relevant
✨ Better Results
Write good queries
- Be specific and descriptive
- Use natural language
- Include relevant keywords
- Use user’s country code when available
- Match content language to location
dayorweekfor current eventsmonthfor recent trends- No filter for evergreen content
🛡️ Reliability
Handle errors gracefully
- Always catch and handle errors
- Retry with exponential backoff
- Have fallback content ready
- Check query is not empty
- Validate search_type before sending
- Sanitize user input
- Track API calls and costs
- Set up alerts for unusual patterns
- Log errors for debugging
Important Limitations
Quick Tips
Frequently Asked Questions
Can I get more than 10 results?
Can I get more than 10 results?
No, the API returns a maximum of 10 results per search. This is a hard limit.Workarounds:
- Make multiple searches with different queries
- Use more specific queries to get better top 10 results
- Combine with pagination on your side
Why does shopping search cost more?
Why does shopping search cost more?
Shopping searches cost 0.001) because they:
- Query multiple e-commerce platforms
- Extract structured product data (price, ratings, etc.)
- Require more processing power
- Return richer metadata
Can I use recency filters with image search?
Can I use recency filters with image search?
No,
recency filters only work with:search_type: 'general'search_type: 'news'
How do I search a specific website?
How do I search a specific website?
Use Note: This only works with
domainFilter with general search:search_type: 'general'What's the difference between Web Search and Answer API?
What's the difference between Web Search and Answer API?
Web Search API:
- Returns raw search results (like Google)
- No AI processing
- Cheaper ($0.001-0.002 per search)
- Use when you need structured search data
- Searches web + generates AI answer
- Combines multiple sources
- More expensive ($0.004+ base fee + LLM costs)
- Use when you need an actual answer
Can I search in languages other than English?
Can I search in languages other than English?
Yes! Use the The API will return results in the language dominant in that region.
location parameter to get results in different regions:How do I handle rate limits?
How do I handle rate limits?
Can I get PDF links for scholar search results?
Can I get PDF links for scholar search results?
Sometimes! The Not all papers have publicly accessible PDFs, but when they do, we include the link.
pdfUrl field is included when available:Next Steps
Answer API
Combine search with AI-powered answers
Scraper API
Extract content from search results
Examples
Ready-to-run code examples
Need Help?
Found a bug or have a feature request? We’d love to hear from you! Join our Discord or email us at [email protected]
