---
title: "Suggest Competitors"
method: GET
path: "/api/v1/brand-library/suggest-competitors"
tags: ["Brand Library (Tech Spike)"]
---

# Suggest Competitors

`GET /api/v1/brand-library/suggest-competitors`

## Request

- Base URL: `https://geo.sig.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://geo.sig.ai/api/v1/brand-library/suggest-competitors`
- Auth: HTTP bearer

Get competitor suggestions from brand library for a given vertical.

**Tech Spike Endpoint (Day 1 + Option C Enhancement)**

This endpoint queries the pre-bootstrapped brand_library table (529+ brands, 36 verticals)
and groups related products under their parent brands.

**Grouping Logic (Option C):**
- Parent brands are shown with their product lines grouped together
- Example: "OpenAI" groups "OpenAI Platform" as a child product
- "Salesforce" groups "Salesforce Marketing Cloud", "Sales Cloud", etc.
- Provides cleaner UX while maintaining product-level detail

**Filtering Logic:**
- Filters by vertical (exact match, case-sensitive)
- Excludes brands with "Low" confidence
- Sorts by tier (Leader → Challenger → Emerging) then by rank
- Groups child products under parent brands
- Limits to parent brand count (children don't count toward limit)

**Example Request:**
```
GET /api/v1/brand-library/suggest-competitors?vertical=AI%2FML%20Platforms&limit=10
```

**Example Response:**
```json
{
  "vertical": "AI/ML Platforms",
  "count": 2,
  "total_brands": 3,
  "suggestions": [
    {
      "id": "...",
      "brand": "OpenAI",
      "tier": "Leader",
      "rank": 1,
      "is_parent": true,
      "products": [
        {
          "product_name": "Platform",
          "full_name": "OpenAI Platform",
          "subcategory": "LLM APIs",
          "tier": "Leader",
          "rank": 1
        }
      ]
    },
    ...
  ]
}
```

**Args:**
- `vertical`: Vertical name (e.g., "AI/ML Platforms", "Marketing Tech")
- `limit`: Maximum parent brands to return (0-50, default 15)

**Returns:**
- List of grouped brand suggestions with nested products

**Status Codes:**
- 200: Success (may return empty list if no brands found)
- 400: Invalid parameters (e.g., negative limit)

## Query parameters

- `vertical` string, required: Vertical/industry to get competitor suggestions for
- `limit` integer: Maximum number of parent brands to return

## Cookies

- `access_token` string, nullable

## Response `200`

Successful Response

- CompetitorSuggestionsResponse: Response model for competitor suggestions endpoint.
  - `vertical` string, required
  - `count` integer, required
  - `total_brands` integer, required
  - `suggestions` GroupedBrandSuggestion[], required
    - `id` string, uuid, required
    - `brand` string, required
    - `website` string, required
    - `vertical` string, required
    - `subcategory` string, required
    - `tier` string, required
    - `rank` integer, nullable, required
    - `confidence` string, required
    - `signal` string, nullable, required
    - `is_parent` boolean
    - `products` BrandProduct[]
      - `id` string, uuid, required
      - `product_name` string, required
      - `full_name` string, required
      - `website` string, required
      - `subcategory` string, required
      - `tier` string, required
      - `rank` integer, nullable, required
      - `confidence` string, required
      - `signal` string, nullable, required

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/sig/apis/ai-visibility-intelligence-api.md) · [All operations](https://skmtc.dev/sig/apis/ai-visibility-intelligence-api/llms.txt) · [OpenAPI document](https://skmtc.dev/sig/apis/ai-visibility-intelligence-api/revisions/3ec39f9be9e0?raw)