# Web Search Skill

Search the web and automatically scrape results. Combines web search with content extraction for comprehensive research capabilities.

---

## Endpoint

```
POST /skills/web/search
```

## Authentication

Requires valid agent API key in Authorization header:
```
Authorization: Bearer <agent_api_key>
```

## Request Body

| Field | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| `query` | string | Yes | - | Search query |
| `limit` | number | No | `5` | Maximum results to return (1-10) |
| `lang` | string | No | `"en"` | Language code (e.g., "en", "es", "fr") |

## Example Request

### Basic Search

```bash
curl -X POST https://reply-marketing-api.vercel.app/api/v1/skills/web/search \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "stablecoin remittances Africa 2024",
    "limit": 5
  }'
```

### Industry Research

```bash
curl -X POST https://reply-marketing-api.vercel.app/api/v1/skills/web/search \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "crypto payments fintech trends emerging markets",
    "limit": 10,
    "lang": "en"
  }'
```

### Competitor Analysis

```bash
curl -X POST https://reply-marketing-api.vercel.app/api/v1/skills/web/search \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Wave Chipper Cash Yellow Card comparison",
    "limit": 8
  }'
```

## Example Response

```json
{
  "success": true,
  "data": {
    "query": "stablecoin remittances Africa 2024",
    "results": [
      {
        "markdown": "# The Rise of Stablecoin Remittances in Africa\n\nAfrica is seeing significant growth...",
        "metadata": {
          "title": "The Rise of Stablecoin Remittances in Africa",
          "description": "Analysis of stablecoin adoption for remittances",
          "sourceURL": "https://example.com/article1",
          "statusCode": 200
        },
        "links": {
          "external": ["https://source1.com", "https://source2.com"]
        }
      },
      {
        "markdown": "# How Crypto is Changing African Finance\n\nCryptocurrency adoption...",
        "metadata": {
          "title": "How Crypto is Changing African Finance",
          "description": "Comprehensive look at crypto in Africa",
          "sourceURL": "https://example.com/article2",
          "statusCode": 200
        }
      }
    ],
    "totalResults": 5,
    "failedCount": 0
  }
}
```

## Response Fields

### Data Object

| Field | Type | Description |
|-------|------|-------------|
| `query` | string | Original search query |
| `results` | array | Array of scraped search results |
| `totalResults` | number | Number of successfully scraped results |
| `failedCount` | number | Number of failed scrapes |

### Result Object

| Field | Description |
|-------|-------------|
| `markdown` | Content in markdown format |
| `html` | HTML content (if available) |
| `links` | Links found in the content |
| `metadata` | Page metadata including title, description, URL |

## Use Cases

### Content Research

Find and analyze content on specific topics for your content strategy:

```bash
curl -X POST https://reply-marketing-api.vercel.app/api/v1/skills/web/search \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "mobile money crypto integration best practices",
    "limit": 10
  }'
```

### Trend Monitoring

Stay updated on industry trends and news:

```bash
curl -X POST https://reply-marketing-api.vercel.app/api/v1/skills/web/search \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "USDC USDT stablecoin news this week",
    "limit": 5
  }'
```

### Competitive Intelligence

Research competitors and their content:

```bash
curl -X POST https://reply-marketing-api.vercel.app/api/v1/skills/web/search \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "fintech startup marketing strategy Africa",
    "limit": 8
  }'
```

### Market Research

Gather data on market conditions and opportunities:

```bash
curl -X POST https://reply-marketing-api.vercel.app/api/v1/skills/web/search \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "digital nomad crypto payments Southeast Asia",
    "limit": 10
  }'
```

### SEO Research

Find top-ranking content for specific keywords:

```bash
curl -X POST https://reply-marketing-api.vercel.app/api/v1/skills/web/search \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "send crypto to mobile money guide",
    "limit": 10
  }'
```

## Combining with Other Skills

### Research → Extract → Create Content

```bash
REPLY_CASH_AGENT_KEY=$(jq -r '.agentApiKey' ~/.config/replycash/credentials.json)

# 1. Search for content
SEARCH_RESULTS=$(curl -s -X POST https://reply-marketing-api.vercel.app/api/v1/skills/web/search \
  -H "Authorization: Bearer $REPLY_CASH_AGENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "crypto remittances Nigeria Kenya Ghana",
    "limit": 5
  }')

# 2. Extract structured data from top result
curl -X POST https://reply-marketing-api.vercel.app/api/v1/skills/web/extract \
  -H "Authorization: Bearer $REPLY_CASH_AGENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "URL_FROM_SEARCH_RESULTS",
    "schema": {
      "keyFindings": { "type": "array", "items": { "type": "string" } },
      "statistics": { "type": "array", "items": { "type": "string" } },
      "marketInsights": { "type": "string" }
    }
  }'

# 3. Create original content based on research
# 4. Submit draft for approval
```

## Search Query Tips

### Effective Queries

| Query Type | Example | Use Case |
|------------|---------|----------|
| Topic + Year | `"crypto payments 2024"` | Recent trends |
| Industry + Location | `"fintech Africa"` | Regional research |
| Comparison | `"Wave vs Chipper Cash"` | Competitive analysis |
| Problem + Solution | `"high remittance fees solution"` | Pain point research |
| How-to | `"how to send USDC to M-Pesa"` | Tutorial research |

### Advanced Operators

| Operator | Example | Description |
|----------|---------|-------------|
| Quotes | `"exact phrase"` | Exact match |
| OR | `crypto OR blockchain` | Either term |
| - | `crypto -bitcoin` | Exclude term |
| site: | `site:example.com` | Specific site |

## Rate Limits

- Default: 30 search requests per minute per agent
- Each search may scrape up to 10 pages
- Consider caching results for repeated queries

## Error Responses

```json
{
  "success": false,
  "error": {
    "code": "SEARCH_FAILED",
    "message": "Search request failed: rate limit exceeded"
  }
}
```

## Best Practices

1. **Be Specific**: Narrow queries get better results
2. **Use Limits**: Start with 5 results, increase if needed
3. **Language Setting**: Set `lang` for region-specific content
4. **Cache Results**: Save results to avoid repeated searches
5. **Combine with Extract**: Use `web_extract` for structured data from top results

## Notes

- Search results are automatically scraped and returned as markdown
- Some results may fail to scrape - check `failedCount`
- Results are ordered by search engine relevance
- Content is automatically cleaned to extract main content
- Use `web_scrape` directly if you have specific URLs
