Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.llmlayer.ai/llms.txt

Use this file to discover all available pages before exploring further.

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)

All Search Types

$0.002 per searchGeneral, News, Images, Videos, Shopping, Scholar= $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.002
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.002”how to learn python”
newsRecent news articles$0.002”tech industry layoffs”
imagesFind images$0.002”golden gate bridge sunset”
videosFind videos$0.002”how to tie a tie tutorial”
shoppingProduct search$0.002”iphone 15 pro”
scholarAcademic papers$0.002”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.002

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.
$0.002 per search - Same price as all other search types.

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.002)
  • news - News articles ($0.002)
  • images - Image search ($0.002)
  • videos - Video search ($0.002)
  • shopping - Product search ($0.002)
  • scholar - Academic papers ($0.002)
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.002      // 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
  • All search types cost $0.002
  • Use the right type for your needs
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
  • Same $0.002 cost as all search types
  • Use when you need product-specific data (prices, ratings)

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
No, all search types cost the same: $0.002 per search. Shopping search returns richer product data (prices, ratings, merchants) at the same price as other types.
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.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

Answer API

Combine search with AI-powered answers

Scraper API

Extract content from search results

Examples

Ready-to-run code examples

Python SDK

Python client documentation

TypeScript SDK

TypeScript client documentation

Need Help?

Discord Community

Chat with other developers

Email Support

Found a bug or have a feature request? We’d love to hear from you! Join our Discord or email us at support@llmlayer.ai