# Search Tool Usage Examples

Source: https://docs.evomi.com/scraping-products-instructions/scraper-api/tools/search/usage-examples/

Practical examples for using the Search API.

## Basic Search

Find domains related to a topic:

```bash
curl -X POST "https://scrape.evomi.com/api/v1/scraper/search" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "best CRM software",
    "max_urls": 10
  }'
```

## Multiple Queries

Search multiple topics in one request:

```bash
curl -X POST "https://scrape.evomi.com/api/v1/scraper/search" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": ["CRM software", "sales automation tools", "customer management platforms"],
    "max_urls": 30
  }'
```

**Response includes which query matched each result:**

```json
{
  "success": true,
  "queries": ["CRM software", "sales automation tools", "customer management platforms"],
  "discovered_count": 30,
  "results": [
    {
      "domain": "www.salesforce.com",
      "url": "https://www.salesforce.com/crm/",
      "title": "What is CRM? CRM Defined - Salesforce.com",
      "query": "CRM software"
    },
    {
      "domain": "www.hubspot.com",
      "url": "https://www.hubspot.com/products/crm",
      "title": "Free CRM Software - HubSpot CRM",
      "query": "CRM software"
    }
  ],
  "credits_used": 3.0,
  "credits_remaining": 9997.0
}
```

## Region-Specific Search

Get results from a specific region. The region also determines the proxy location:

```bash
curl -X POST "https://scrape.evomi.com/api/v1/scraper/search" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "job boards",
    "max_urls": 15,
    "region": "de-de"
  }'
```

### Available Regions

| Region Code | Description |
|-------------|-------------|
| `us-en` | United States (English) |
| `uk-en` | United Kingdom (English) |
| `de-de` | Germany (German) |
| `fr-fr` | France (French) |
| `es-es` | Spain (Spanish) |
| `it-it` | Italy (Italian) |
| `jp-jp` | Japan (Japanese) |
| `au-en` | Australia (English) |

## Async Mode

For large searches, process in the background:

```bash
curl -X POST "https://scrape.evomi.com/api/v1/scraper/search" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "cloud computing providers",
    "max_urls": 100,
    "async": true
  }'
```

**Check task status:**

```bash
curl "https://scrape.evomi.com/api/v1/scraper/search/tasks/YOUR_TASK_ID" \
  -H "x-api-key: YOUR_API_KEY"
```

## Python Example

```python
import requests

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://scrape.evomi.com/api/v1/scraper/search"

def search_domains(query, max_urls=20, region="us-en"):
    """Search for domains related to a query."""

    headers = {
        "x-api-key": API_KEY,
        "Content-Type": "application/json"
    }

    payload = {
        "query": query,
        "max_urls": max_urls,
        "region": region
    }

    response = requests.post(BASE_URL, json=payload, headers=headers)
    return response.json()

# Example usage
result = search_domains("e-commerce platforms", max_urls=10)

for item in result.get("results", []):
    print(f"{item['domain']}: {item['title']}")
```

## Python with Multiple Queries

```python
import requests

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://scrape.evomi.com/api/v1/scraper/search"

def search_multiple(queries, max_urls=50):
    """Search for multiple queries at once."""

    headers = {
        "x-api-key": API_KEY,
        "Content-Type": "application/json"
    }

    payload = {
        "query": queries,  # Pass list of queries
        "max_urls": max_urls
    }

    response = requests.post(BASE_URL, json=payload, headers=headers)
    return response.json()

# Search for multiple competitors
queries = [
    "email marketing tools",
    "marketing automation software",
    "newsletter platforms"
]

result = search_multiple(queries, max_urls=30)

print(f"Found {result['discovered_count']} domains")
for item in result.get("results", []):
    print(f"  {item['domain']} (from: {item['query']})")
```

## Python Async Handling

```python
import requests
import time

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://scrape.evomi.com/api/v1/scraper/search"

def search_async(query, max_urls=100):
    """Start async search and poll for results."""

    headers = {
        "x-api-key": API_KEY,
        "Content-Type": "application/json"
    }

    # Start async search
    payload = {
        "query": query,
        "max_urls": max_urls,
        "async": True
    }

    response = requests.post(BASE_URL, json=payload, headers=headers)
    task_id = response.json().get("task_id")

    if not task_id:
        return response.json()

    # Poll for results
    check_url = f"{BASE_URL}/tasks/{task_id}"

    while True:
        time.sleep(2)  # Wait 2 seconds between checks
        result = requests.get(check_url, headers=headers).json()

        if result.get("status") == "success":
            return result
        elif result.get("status") == "failure":
            raise Exception("Search failed")

# Usage
result = search_async("SaaS companies", max_urls=50)
print(f"Found {result['discovered_count']} domains")
```

## Combined with Scraper

Search for domains, then scrape them:

```python
import requests

API_KEY = "YOUR_API_KEY"
SEARCH_URL = "https://scrape.evomi.com/api/v1/scraper/search"
SCRAPER_URL = "https://scrape.evomi.com/api/v1/scraper/realtime"

headers = {
    "x-api-key": API_KEY,
    "Content-Type": "application/json"
}

# Step 1: Search for domains
search_payload = {
    "query": "productivity apps",
    "max_urls": 10
}

search_result = requests.post(SEARCH_URL, json=search_payload, headers=headers).json()

# Step 2: Scrape each discovered URL
for item in search_result.get("results", []):
    scrape_payload = {
        "url": item["url"],
        "mode": "request"
    }

    scrape_result = requests.post(SCRAPER_URL, json=scrape_payload, headers=headers).json()

    print(f"Scraped {item['domain']}:")
    print(f"  Title: {scrape_result.get('title', 'N/A')}")
    print()
```

## Common Use Cases

### Competitor Research

```bash
curl -X POST "https://scrape.evomi.com/api/v1/scraper/search" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": ["project management software", "task management tools"],
    "max_urls": 20
  }'
```

### Market Research

```bash
curl -X POST "https://scrape.evomi.com/api/v1/scraper/search" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "artificial intelligence startups",
    "max_urls": 50,
    "region": "us-en"
  }'
```

### Local Business Discovery

```bash
curl -X POST "https://scrape.evomi.com/api/v1/scraper/search" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "web design agencies",
    "max_urls": 30,
    "region": "uk-en"
  }'
```

## Tips

1. **Start small** — Test with low `max_urls` values to understand results before scaling.

2. **Use multiple queries** — Different search terms may find different domains.

3. **Choose the right region** — Use the appropriate region for locally relevant results.

4. **Combine with scraping** — Use discovered URLs with the Scraper API for complete data extraction.