0
# Search
1

2
Web search with optional result scraping across different sources (web, news, images) with advanced filtering.
3

4
## Core Search Method
5

6
```typescript { .api }
7
/**
8
 * Search the web and optionally scrape each result
9
 * @param query - Search query string
10
 * @param req - Additional search options
11
 * @returns Promise resolving to structured search results
12
 */
13
search(query: string, req?: Omit<SearchRequest, "query">): Promise<SearchData>;
14
```
15

16
## Search Configuration
17

18
```typescript { .api }
19
interface SearchRequest {
20
  query: string;
21
  
22
  // Search sources
23
  sources?: Array<"web" | "news" | "images" | { type: "web" | "news" | "images" }>;
24
  
25
  // Search categories
26
  categories?: Array<"github" | "research" | CategoryOption>;
27
  
28
  // Result limits
29
  limit?: number;
30
  
31
  // Search parameters
32
  tbs?: string;
33
  location?: string;
34
  ignoreInvalidURLs?: boolean;
35
  timeout?: number; // milliseconds
36
  
37
  // Content scraping
38
  scrapeOptions?: ScrapeOptions;
39
  
40
  // Integration tracking
41
  integration?: string;
42
}
43

44
interface CategoryOption {
45
  type: "github" | "research";
46
}
47
```
48

49
## Search Results
50

51
```typescript { .api }
52
interface SearchData {
53
  web?: Array<SearchResultWeb | Document>;
54
  news?: Array<SearchResultNews | Document>;
55
  images?: Array<SearchResultImages | Document>;
56
}
57

58
// Web search result
59
interface SearchResultWeb {
60
  url: string;
61
  title?: string;
62
  description?: string;
63
  category?: string;
64
}
65

66
// News search result  
67
interface SearchResultNews {
68
  title?: string;
69
  url?: string;
70
  snippet?: string;
71
  date?: string;
72
  imageUrl?: string;
73
  position?: number;
74
  category?: string;
75
}
76

77
// Image search result
78
interface SearchResultImages {
79
  title?: string;
80
  imageUrl?: string;
81
  imageWidth?: number;
82
  imageHeight?: number;
83
  url?: string;
84
  position?: number;
85
}
86
```
87

88
## Usage Examples
89

90
### Basic Web Search
91

92
```typescript
93
// Simple web search
94
const results = await app.search('artificial intelligence trends 2024');
95

96
console.log('Web results:', results.web);
97
// Array of SearchResultWeb objects with url, title, description
98
```
99

100
### Multi-Source Search
101

102
```typescript
103
// Search across web, news, and images
104
const results = await app.search('climate change', {
105
  sources: ['web', 'news', 'images'],
106
  limit: 20
107
});
108

109
console.log('Web results:', results.web?.length);
110
console.log('News results:', results.news?.length);
111
console.log('Image results:', results.images?.length);
112
```
113

114
### Search with Content Scraping
115

116
```typescript
117
// Search and scrape the content of each result
118
const results = await app.search('best javascript frameworks 2024', {
119
  sources: ['web'],
120
  limit: 10,
121
  scrapeOptions: {
122
    formats: ['markdown', 'json'],
123
    onlyMainContent: true
124
  }
125
});
126

127
// Results now include full scraped content
128
for (const result of results.web || []) {
129
  if ('markdown' in result) {
130
    console.log('Scraped content:', result.markdown);
131
  }
132
}
133
```
134

135
### Structured Data Extraction from Search
136

137
```typescript
138
import { z } from 'zod';
139

140
const ArticleSchema = z.object({
141
  title: z.string(),
142
  author: z.string().optional(),
143
  publishDate: z.string().optional(),
144
  mainPoints: z.array(z.string()),
145
  conclusion: z.string().optional()
146
});
147

148
const results = await app.search('machine learning research 2024', {
149
  sources: ['web'],
150
  limit: 15,
151
  scrapeOptions: {
152
    formats: [{
153
      type: 'json',
154
      schema: ArticleSchema
155
    }],
156
    onlyMainContent: true
157
  }
158
});
159

160
// Extract structured data from search results
161
for (const result of results.web || []) {
162
  if ('json' in result && result.json) {
163
    console.log('Structured article data:', result.json);
164
  }
165
}
166
```
167

168
### GitHub Code Search
169

170
```typescript
171
// Search for code repositories and projects
172
const results = await app.search('react typescript authentication', {
173
  categories: ['github'],
174
  limit: 20
175
});
176

177
console.log('GitHub results:', results.web);
178
// Returns relevant GitHub repositories and code examples
179
```
180

181
### Research-Focused Search
182

183
```typescript
184
// Search academic and research content
185
const results = await app.search('quantum computing algorithms', {
186
  categories: ['research'],
187
  sources: ['web'],
188
  limit: 25,
189
  scrapeOptions: {
190
    formats: ['markdown'],
191
    onlyMainContent: true
192
  }
193
});
194

195
// Get research papers and academic content
196
for (const result of results.web || []) {
197
  if ('markdown' in result) {
198
    console.log(`Research content from ${result.metadata?.sourceURL}:`, 
199
                result.markdown?.substring(0, 500) + '...');
200
  }
201
}
202
```
203

204
### News Search with Date Filtering
205

206
```typescript
207
// Search recent news with time-based filtering
208
const results = await app.search('cybersecurity breaches', {
209
  sources: ['news'],
210
  tbs: 'qdr:m', // Past month
211
  limit: 30,
212
  scrapeOptions: {
213
    formats: ['markdown', {
214
      type: 'json',
215
      schema: {
216
        type: 'object',
217
        properties: {
218
          headline: { type: 'string' },
219
          summary: { type: 'string' },
220
          source: { type: 'string' },
221
          publishDate: { type: 'string' },
222
          impact: { type: 'string' },
223
          affectedCompanies: { 
224
            type: 'array', 
225
            items: { type: 'string' } 
226
          }
227
        }
228
      }
229
    }]
230
  }
231
});
232

233
console.log('Recent cybersecurity news:', results.news);
234
```
235

236
### Location-Based Search
237

238
```typescript
239
// Search with geographic targeting
240
const results = await app.search('local tech meetups', {
241
  sources: ['web'],
242
  location: 'San Francisco, CA',
243
  limit: 15,
244
  scrapeOptions: {
245
    formats: ['markdown'],
246
    location: {
247
      country: 'US',
248
      languages: ['en']
249
    }
250
  }
251
});
252
```
253

254
### Image Search
255

256
```typescript
257
// Search for images with metadata
258
const results = await app.search('sustainable architecture designs', {
259
  sources: ['images'],
260
  limit: 50
261
});
262

263
// Process image results
264
for (const image of results.images || []) {
265
  console.log({
266
    title: image.title,
267
    imageUrl: image.imageUrl,
268
    dimensions: `${image.imageWidth}x${image.imageHeight}`,
269
    sourceUrl: image.url
270
  });
271
}
272
```
273

274
### Advanced Search Configuration
275

276
```typescript
277
const results = await app.search('enterprise software security', {
278
  sources: [
279
    { type: 'web' },
280
    { type: 'news' }
281
  ],
282
  categories: ['research'],
283
  limit: 40,
284
  tbs: 'qdr:y', // Past year
285
  location: 'United States',
286
  timeout: 60000, // 60 seconds
287
  ignoreInvalidURLs: true,
288
  scrapeOptions: {
289
    formats: ['markdown', 'links'],
290
    headers: {
291
      'User-Agent': 'Research Bot 1.0'
292
    },
293
    onlyMainContent: true,
294
    blockAds: true,
295
    timeout: 30000
296
  }
297
});
298
```
299

300
### Error Handling
301

302
```typescript
303
try {
304
  const results = await app.search('complex search query', {
305
    sources: ['web', 'news'],
306
    limit: 100,
307
    scrapeOptions: {
308
      formats: ['markdown']
309
    },
310
    timeout: 30000
311
  });
312
  
313
  // Check for any failed scrapes in results
314
  for (const result of results.web || []) {
315
    if ('metadata' in result && result.metadata?.error) {
316
      console.log(`Failed to scrape ${result.metadata.sourceURL}: ${result.metadata.error}`);
317
    }
318
  }
319
  
320
} catch (error) {
321
  console.error('Search failed:', error);
322
}
323
```
324

325
### Combining Search Sources
326

327
```typescript
328
// Search across all sources and combine results
329
const webResults = await app.search('renewable energy innovation', {
330
  sources: ['web'],
331
  limit: 20,
332
  scrapeOptions: { formats: ['markdown'] }
333
});
334

335
const newsResults = await app.search('renewable energy innovation', {
336
  sources: ['news'],
337
  limit: 15,
338
  tbs: 'qdr:m' // Recent news only
339
});
340

341
const imageResults = await app.search('renewable energy innovation', {
342
  sources: ['images'],
343
  limit: 10
344
});
345

346
// Process combined results
347
console.log('Comprehensive search results:', {
348
  webPages: webResults.web?.length || 0,
349
  newsArticles: newsResults.news?.length || 0,
350
  images: imageResults.images?.length || 0
351
});
352
```
353

354
### Search Result Processing
355

356
```typescript
357
const results = await app.search('artificial intelligence ethics', {
358
  sources: ['web', 'news'],
359
  limit: 30,
360
  scrapeOptions: {
361
    formats: ['markdown', 'links']
362
  }
363
});
364

365
// Process and analyze results
366
const processedResults = {
367
  webSites: new Set(),
368
  totalLinks: 0,
369
  contentLength: 0
370
};
371

372
for (const result of [...(results.web || []), ...(results.news || [])]) {
373
  if ('metadata' in result && result.metadata?.sourceURL) {
374
    const domain = new URL(result.metadata.sourceURL).hostname;
375
    processedResults.webSites.add(domain);
376
  }
377
  
378
  if ('links' in result && result.links) {
379
    processedResults.totalLinks += result.links.length;
380
  }
381
  
382
  if ('markdown' in result && result.markdown) {
383
    processedResults.contentLength += result.markdown.length;
384
  }
385
}
386

387
console.log('Analysis:', {
388
  uniqueDomains: processedResults.webSites.size,
389
  totalLinks: processedResults.totalLinks,
390
  totalContentLength: processedResults.contentLength
391
});
392
```