> ## Documentation Index
> Fetch the complete documentation index at: https://docs.searchcompany.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Architecture and internal services for the Competitor Research endpoint

## Purpose

Finds 5 competitors for a business URL using Exa's AI-powered search. Used on the marketing website to show visitors their competitive landscape.

## Architecture

```mermaid theme={null}
flowchart TD
    Request["POST /api/competitor-research?url=..."]
    
    subgraph services [Internal Services]
        FetchContent["fetch_website_content()"]
        FetchCompetitors["fetch_competitors_from_exa()"]
        ParseJSON["parse_json_from_answer()"]
        ParseText["parse_competitors_from_text()"]
        Fallback["fallback_from_citations()"]
        AddFavicons["add_favicon_urls_to_competitors()"]
    end
    
    subgraph external [External APIs]
        ExaContents["Exa /contents API"]
        ExaAnswer["Exa /answer API"]
        GoogleFav["Google Favicon Service"]
    end
    
    Request --> FetchContent
    FetchContent --> ExaContents
    ExaContents --> FetchCompetitors
    FetchCompetitors --> ExaAnswer
    ExaAnswer --> ParseJSON
    ParseJSON -->|"Success"| AddFavicons
    ParseJSON -->|"Failed"| ParseText
    ParseText -->|"< 5 competitors"| Fallback
    ParseText -->|">= 5 competitors"| AddFavicons
    Fallback --> AddFavicons
    AddFavicons --> GoogleFav
    GoogleFav --> Response["Return 5 competitors"]
```

## Two-Step Approach

1. **Fetch Content** - Get the business website content via Exa `/contents`
2. **Find Competitors** - Ask Exa `/answer` to identify competitors based on the content

This ensures accurate competitor identification by understanding what the business does first.

## Internal Services

| Service                                                       | Purpose                             |
| ------------------------------------------------------------- | ----------------------------------- |
| [fetch\_website\_content](fetch-website-content)              | Gets website content via Exa        |
| [fetch\_competitors\_from\_exa](fetch-competitors-from-exa)   | Uses Exa Answer to find competitors |
| [parse\_json\_from\_answer](parse-json-from-answer)           | Extracts JSON from Exa response     |
| [parse\_competitors\_from\_text](parse-competitors-from-text) | Fallback text parsing               |
| [fallback\_from\_citations](fallback-from-citations)          | Uses citations if parsing fails     |
| [add\_favicon\_urls\_to\_competitors](add-favicon-urls)       | Adds favicon URLs                   |

## Code Location

```
src/website/competitor_research/
├── routes.py    # HTTP endpoint
└── service.py   # All business logic
```

## Rate Limiting

* **10 requests per minute** per IP address

## Automatic Retry

The service automatically retries once on failure (timeout, API error, or insufficient results).