Skip to main content

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
Perfect for: Research tools, price comparison apps, news aggregators, content discovery, and any app that needs search data.
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 the Authorization header:
Authorization: Bearer YOUR_LLMLAYER_API_KEY
Keep your API key secure! Never expose it in client-side code. Always call from your backend.

Your First Search (2-Minute Start)

Let’s search the web in under 2 minutes!
import { LLMLayerClient } from 'llmlayer';

// 1. Create a client
const client = new LLMLayerClient({
  apiKey: process.env.LLMLAYER_API_KEY
});

// 2. Search the web
const response = await client.searchWeb({
  query: 'best pizza restaurants in New York',
  searchType: 'general',  // Basic web search
  location: 'us'          // US-based results
});

// 3. Loop through results
for (const result of response.results) {
  console.log(result.title);
  console.log(result.link);
  console.log(result.snippet);
  console.log('---');
}

// 4. Check the cost
console.log(`Cost: $${response.cost}`);  // $0.001
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 TypeUse ForCostExample Query
generalRegular web search$0.001”how to learn python”
newsRecent news articles$0.001”tech industry layoffs”
imagesFind images$0.001”golden gate bridge sunset”
videosFind videos$0.001”how to tie a tie tutorial”
shoppingProduct search$0.002”iphone 15 pro”
scholarAcademic 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 recency and domainFilter

Basic Example

import { LLMLayerClient } from 'llmlayer';

const client = new LLMLayerClient({
  apiKey: process.env.LLMLAYER_API_KEY
});

const response = await client.searchWeb({
  query: 'latest advancements in renewable energy',
  searchType: 'general',
  location: 'us'
});

// Print each result
for (const result of response.results) {
  console.log(`Title: ${result.title}`);
  console.log(`URL: ${result.link}`);
  console.log(`Snippet: ${result.snippet}`);
  console.log('---');
}

console.log(`Found ${response.results.length} results`);
console.log(`Cost: $${response.cost}`);

Filter by Time (Recent Results Only)

Get only recent results with the recency parameter.
const response = await client.searchWeb({
  query: 'latest advancements in renewable energy',
  searchType: 'general',
  location: 'us',
  recency: 'month'  // Only results from the past month
});

console.log(`Recent results from the past month:`);
for (const result of response.results) {
  console.log(`${result.title} (${result.date || 'No date'})`);
  console.log(result.link);
}
Recency options: hour, day, week, month, year

Filter by Domain

Control which websites appear in your results.
// Only search specific trusted sources
const response = await client.searchWeb({
  query: 'climate change research',
  searchType: 'general',
  location: 'us',
  domainFilter: [
    'nature.com',      // Include Nature
    'science.org',     // Include Science Magazine
    '-wikipedia.org'   // Exclude Wikipedia (note the -)
  ]
});

for (const result of response.results) {
  const domain = new URL(result.link).hostname;
  console.log(`${result.title} (from ${domain})`);
}
Domain filter tips:
  • Use - prefix to exclude domains: "-reddit.com"
  • No prefix means include only those domains
  • Mix both: ["nature.com", "-wikipedia.org"]

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

const response = await client.searchWeb({
  query: 'tech industry layoffs 2025',
  searchType: 'news',
  location: 'us',
  recency: 'week'  // News from the past week
});

console.log(`Latest news articles:\n`);

for (const article of response.results) {
  console.log(`📰 ${article.title}`);
  console.log(`   Source: ${article.source}`);
  console.log(`   Date: ${article.date}`);
  console.log(`   URL: ${article.link}`);
  if (article.imageUrl) {
    console.log(`   Image: ${article.imageUrl}`);
  }
  console.log(`   ${article.snippet}\n`);
}

console.log(`Cost: $${response.cost}`);
Output example:
📰 Major Tech Company Announces Restructuring
   Source: TechCrunch
   Date: 2025-01-15
   URL: https://techcrunch.com/...
   Image: https://...thumbnail.jpg
   Company X announced plans to restructure...

Cost: $0.001

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

const response = await client.searchWeb({
  query: 'golden gate bridge sunset',
  searchType: 'images',
  location: 'us'
});

console.log(`Found ${response.results.length} images:\n`);

for (const image of response.results) {
  console.log(`🖼️  ${image.title}`);
  console.log(`   Full size: ${image.imageUrl}`);
  console.log(`   Thumbnail: ${image.thumbnailUrl}`);
  console.log(`   Dimensions: ${image.width}x${image.height}px`);
  console.log(`   Source: ${image.source}`);
  console.log(`   Page: ${image.link}\n`);
}

console.log(`Cost: $${response.cost}`);
Use case ideas:
  • Build image galleries
  • Visual search features
  • Content discovery tools
  • Inspiration boards

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

const response = await client.searchWeb({
  query: 'how to cook pasta perfectly',
  searchType: 'videos',
  location: 'us'
});

console.log(`Found ${response.results.length} videos:\n`);

for (const video of response.results) {
  console.log(`🎥 ${video.title}`);
  console.log(`   URL: ${video.link}`);
  console.log(`   Duration: ${video.duration}`);
  console.log(`   Channel: ${video.channel}`);
  console.log(`   Source: ${video.source}`);
  console.log(`   Published: ${video.date}`);
  console.log(`   Thumbnail: ${video.imageUrl}`);
  if (video.videoUrl) {
    console.log(`   Direct video: ${video.videoUrl}`);
  }
  console.log(`   ${video.snippet}\n`);
}

console.log(`Cost: $${response.cost}`);

Search for products with prices, ratings, and merchant info.
Shopping searches cost 2x more: 0.002persearch(vs0.002 per search (vs 0.001 for other types) due to additional data complexity.

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

const response = await client.searchWeb({
  query: 'iphone 15 pro max',
  searchType: 'shopping',
  location: 'us'
});

console.log(`Found ${response.results.length} products:\n`);

for (const product of response.results) {
  console.log(`🛒 ${product.title}`);
  console.log(`   Price: ${product.price}`);
  console.log(`   Merchant: ${product.source}`);
  console.log(`   Rating: ${product.rating}/5 (${product.ratingCount} reviews)`);
  console.log(`   Product ID: ${product.productId}`);
  console.log(`   URL: ${product.link}`);
  console.log(`   Image: ${product.imageUrl}\n`);
}

console.log(`Cost: $${response.cost}`);  // $0.002
Output example:
🛒 Apple iPhone 15 Pro Max 256GB Blue Titanium
   Price: $1,199.00
   Merchant: Best Buy
   Rating: 4.8/5 (2,341 reviews)
   Product ID: 6525624
   URL: https://www.bestbuy.com/...
   Image: https://...product.jpg

Cost: $0.002
Use case ideas:
  • Price comparison tools
  • Product aggregators
  • Deal finders
  • E-commerce research

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

const response = await client.searchWeb({
  query: 'machine learning climate change prediction',
  searchType: 'scholar',
  location: 'us'
});

console.log(`Found ${response.results.length} papers:\n`);

for (const paper of response.results) {
  console.log(`📄 ${paper.title}`);
  console.log(`   Year: ${paper.year}`);
  console.log(`   Citations: ${paper.citedBy}`);
  console.log(`   Publication: ${paper.publicationInfo}`);
  console.log(`   URL: ${paper.link}`);
  if (paper.pdfUrl) {
    console.log(`   PDF: ${paper.pdfUrl}`);
  }
  console.log(`   Abstract: ${paper.snippet}\n`);
  console.log('---\n');
}

console.log(`Cost: $${response.cost}`);
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

query
string
required
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

search_type
string
default:"general"
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)
searchType: 'news'  // Get news articles
location
string
default:"us"
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, mx
location: 'uk'  // UK-based results
recency
string
Filter results by time period. Only works with general and news searches.Options: hour, day, week, month, year
recency: 'week'  // Only results from the past week
Does NOT work with images, videos, shopping, or scholar search types.
domain_filter
array
Include or exclude specific domains. Only works with general search.Include domains:
domainFilter: ['nature.com', 'science.org']
Exclude domains (note the - prefix):
domainFilter: ['-reddit.com', '-pinterest.com']
Mix both:
domainFilter: ['nature.com', '-wikipedia.org']
Only works with search_type: 'general'. Ignored for other search types.

Response Format

Every response has this structure:
{
  "results": [...],  // Array of results (structure varies by search type)
  "cost": 0.001      // Cost in USD for this request
}

Response Fields by Search Type


Real-World Examples

Example 1: News Aggregator

Build a news aggregator that tracks multiple topics.
const topics = [
  'artificial intelligence breakthroughs',
  'renewable energy innovations',
  'space exploration updates'
];

console.log('📰 Daily News Digest\n');

for (const topic of topics) {
  console.log(`\n--- ${topic.toUpperCase()} ---\n`);

  const response = await client.searchWeb({
    query: topic,
    searchType: 'news',
    location: 'us',
    recency: 'day'  // Today's news only
  });

  // Show top 3 articles
  for (const article of response.results.slice(0, 3)) {
    console.log(`📌 ${article.title}`);
    console.log(`   ${article.source} - ${article.date}`);
    console.log(`   ${article.link}\n`);
  }
}

Example 2: Price Comparison Tool

Compare prices across multiple stores.
async function compareProductPrices(productName: string) {
  const response = await client.searchWeb({
    query: productName,
    searchType: 'shopping',
    location: 'us'
  });

  console.log(`💰 Price Comparison: ${productName}\n`);

  // Sort by price (convert price string to number)
  const sorted = response.results
    .map(p => ({
      ...p,
      numPrice: parseFloat(p.price.replace(/[$,]/g, ''))
    }))
    .sort((a, b) => a.numPrice - b.numPrice);

  // Show best deals
  console.log('Best deals:');
  for (const product of sorted.slice(0, 5)) {
    console.log(`${product.price} - ${product.source}`);
    console.log(`Rating: ${product.rating}/5 (${product.ratingCount} reviews)`);
    console.log(`${product.link}\n`);
  }

  // Price stats
  const prices = sorted.map(p => p.numPrice);
  const min = Math.min(...prices);
  const max = Math.max(...prices);
  const avg = prices.reduce((a, b) => a + b, 0) / prices.length;

  console.log(`\n📊 Price Range: $${min} - $${max}`);
  console.log(`   Average: $${avg.toFixed(2)}`);
  console.log(`   You save: $${(max - min).toFixed(2)} buying from cheapest store`);

  return sorted;
}

// Use it
await compareProductPrices('Sony WH-1000XM5 headphones');

Example 3: Academic Research Tool

Find relevant papers for your research.
async function researchPapers(topic: string, minCitations: number = 50) {
  const response = await client.searchWeb({
    query: topic,
    searchType: 'scholar',
    location: 'us'
  });

  console.log(`📚 Research Papers: ${topic}\n`);

  // Filter by citation count and sort
  const highImpact = response.results
    .map(paper => ({
      ...paper,
      citations: parseInt(paper.citedBy.replace(/,/g, '')) || 0
    }))
    .filter(paper => paper.citations >= minCitations)
    .sort((a, b) => b.citations - a.citations);

  console.log(`Found ${highImpact.length} papers with ${minCitations}+ citations:\n`);

  for (const paper of highImpact) {
    console.log(`📄 ${paper.title}`);
    console.log(`   📊 Citations: ${paper.citedBy}`);
    console.log(`   📅 Year: ${paper.year}`);
    console.log(`   📖 ${paper.publicationInfo}`);
    console.log(`   🔗 ${paper.link}`);
    if (paper.pdfUrl) {
      console.log(`   📥 PDF: ${paper.pdfUrl}`);
    }
    console.log();
  }

  // Citation stats
  const citationCounts = highImpact.map(p => p.citations);
  const totalCitations = citationCounts.reduce((a, b) => a + b, 0);
  const avgCitations = totalCitations / citationCounts.length;

  console.log(`\n📈 Statistics:`);
  console.log(`   Total citations: ${totalCitations.toLocaleString()}`);
  console.log(`   Average: ${avgCitations.toFixed(0)} citations/paper`);
  console.log(`   Most cited: ${Math.max(...citationCounts).toLocaleString()}`);

  return highImpact;
}

// Use it
await researchPapers('deep learning computer vision', 100);

Error Handling

Error Format

All errors use this structure:
{
  "detail": {
    "error_type": "validation_error",
    "error_code": "invalid_search_type",
    "message": "Search type 'invalid' is not supported. Choose from 'general', 'news', 'shopping', 'videos', 'images', 'scholar'."
  }
}

Common Errors

Missing or invalid API key
{
  "error_code": "missing_llmlayer_api_key",
  "message": "Provide LLMLayer API key via 'Authorization: Bearer <token>'"
}
Fix: Add your API key to the Authorization header.
Invalid Search Type
{
  "error_code": "invalid_search_type",
  "message": "Search type 'invalid' is not supported..."
}
Fix: Use one of: general, news, images, videos, shopping, scholarEmpty Query
{
  "error_code": "missing_query",
  "message": "Query parameter cannot be empty"
}
Fix: Provide a non-empty search query.
Too many requests
{
  "error_code": "rate_limit_exceeded",
  "message": "Rate limit exceeded. Please try again later"
}
Fix: Wait and retry with exponential backoff.
Search failed
{
  "error_code": "search_error",
  "message": "Failed to retrieve search results"
}
Fix: Retry the request. If it persists, contact support.

Robust Error Handling

import {
  LLMLayerClient,
  RateLimitError,
  InvalidRequest,
  AuthenticationError
} from 'llmlayer';

const client = new LLMLayerClient({
  apiKey: process.env.LLMLAYER_API_KEY
});

async function robustSearch(query: string, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await client.searchWeb({
        query,
        searchType: 'general',
        location: 'us'
      });

    } catch (error) {
      // Don't retry authentication errors
      if (error instanceof AuthenticationError) {
        console.error('❌ Fix your API key');
        throw error;
      }

      // Don't retry validation errors
      if (error instanceof InvalidRequest) {
        console.error('❌ Invalid request:', error.message);
        throw error;
      }

      // Retry rate limits with backoff
      if (error instanceof RateLimitError) {
        const waitTime = Math.pow(2, attempt) * 1000;
        console.log(`⏳ Rate limited. Waiting ${waitTime}ms...`);
        await new Promise(resolve => setTimeout(resolve, waitTime));
        continue;
      }

      // Last attempt - give up
      if (attempt === maxRetries - 1) {
        console.error('❌ Max retries exceeded');
        throw error;
      }

      // Wait before retry
      await new Promise(resolve => setTimeout(resolve, 1000));
    }
  }
}

// Usage
try {
  const results = await robustSearch('your query');
  console.log(`Found ${results.results.length} results`);
} catch (error) {
  console.error('Search failed:', error);
}

Best Practices

💰 Cost Optimization

Use the right search type
  • Don’t use shopping (0.002)whengeneral(0.002) when `general` (0.001) works
  • Shopping search is specifically for product comparisons
Cache results
  • Search results don’t change every second
  • Cache for 1 hour for most use cases
  • Cache for 5 minutes for news/recent content
Batch requests
  • 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”
Use appropriate filters
  • recency for time-sensitive content
  • domainFilter to reduce noise
  • location for localized results
Limit result processing
  • 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
Choose the right location
  • Use user’s country code when available
  • Match content language to location
Use recency filters
  • day or week for current events
  • month for recent trends
  • No filter for evergreen content

🛡️ Reliability

Handle errors gracefully
  • Always catch and handle errors
  • Retry with exponential backoff
  • Have fallback content ready
Validate inputs
  • Check query is not empty
  • Validate search_type before sending
  • Sanitize user input
Monitor usage
  • Track API calls and costs
  • Set up alerts for unusual patterns
  • Log errors for debugging

Important Limitations

Result Limits
  • All searches return maximum 10 results
  • This is a hard limit and cannot be increased
Filter Compatibility
  • recency only works with general and news searches
  • domainFilter only works with general search
  • These filters are ignored for other search types
Shopping Search Cost
  • Shopping searches cost 2x more (0.002vs0.002 vs 0.001)
  • Use only when you need product-specific data (prices, ratings)
  • For general product information, use regular search

Quick Tips

Starting out? Use this config for most searches:
{
  searchType: 'general',
  location: 'us'
}
Need recent content? Add recency filter:
{
  searchType: 'news',
  recency: 'week'  // Past week only
}
Building price comparison? Shopping search gives you everything:
{
  searchType: 'shopping'  // Gets price, rating, merchant, etc.
}
Filter out spam domains? Use domain exclusions:
{
  domainFilter: ['-spam-site.com', '-pinterest.com']
}

Frequently Asked Questions

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
Shopping searches cost 0.002(vs0.002 (vs 0.001) because they:
  • Query multiple e-commerce platforms
  • Extract structured product data (price, ratings, etc.)
  • Require more processing power
  • Return richer metadata
Only use shopping search when you specifically need product pricing/ratings. For general product info, use regular search.
Use domainFilter with general search:
domainFilter: ['example.com']  // Only search this site
Note: This only works with search_type: 'general'
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
Answer API:
  • Searches web + generates AI answer
  • Combines multiple sources
  • More expensive ($0.004+ base fee + LLM costs)
  • Use when you need an actual answer
Yes! Use the location parameter to get results in different regions:
location: 'fr'  // French results
location: 'de'  // German results
location: 'jp'  // Japanese results
The API will return results in the language dominant in that region.
Implement exponential backoff:
for (let attempt = 0; attempt < 3; attempt++) {
  try {
    return await client.searchWeb({...});
  } catch (error) {
    if (error instanceof RateLimitError) {
      await sleep(Math.pow(2, attempt) * 1000);
      continue;
    }
    throw error;
  }
}
See the Error Handling section for complete examples.

Next Steps


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]