> ## 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.

# Get Ranking Score

> Get or create a pre-payment AI ranking score for a website

Public endpoint used on the marketing website to show visitors their initial AI ranking score. If the URL hasn't been checked before, a new score is generated and saved.

<Note>
  This is a **public endpoint** - no authentication required. Used on the
  searchcompany.ai landing page.
</Note>

## Query Parameters

<ParamField query="url" type="string" required>
  Website URL to get/create score for
</ParamField>

## Response

<ResponseField name="score" type="integer">
  The AI ranking score (32-49 for new URLs)
</ResponseField>

<ResponseField name="competitor_scores" type="array">
  Array of 4 competitor scores (always higher than user score, sorted descending)
</ResponseField>

<ResponseField name="platform_statuses" type="array">
  Array of AI platform visibility statuses

  <Expandable title="Platform Status Object">
    <ResponseField name="platform" type="string">
      Name of the AI platform (e.g., "ChatGPT", "Gemini", "Claude")
    </ResponseField>

    <ResponseField name="status" type="string">
      Visibility status: "LOW" or "MEDIUM"
    </ResponseField>
  </Expandable>
</ResponseField>

## How It Works

1. **Check Database** - Looks for existing score in `pre_payment_rankings` table
2. **Return Existing** - If found, returns the stored score
3. **Generate New** - If new URL, generates score between 32-49 and saves it
4. **Generate Competitor Scores** - Creates 4 competitor scores higher than the user's score
5. **Generate Platform Statuses** - Randomly assigns LOW (70%) or MEDIUM (30%) status to each AI platform

This ensures the same URL always gets the same score, creating consistency across page refreshes.

<RequestExample>
  ```bash cURL theme={null}
  curl "https://searchcompany-main.up.railway.app/api/ranking-score?url=https://example.com"
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "score": 38,
    "competitor_scores": [72, 65, 58, 42],
    "platform_statuses": [
      { "platform": "ChatGPT", "status": "LOW" },
      { "platform": "Gemini", "status": "MEDIUM" },
      { "platform": "Grok", "status": "LOW" },
      { "platform": "Perplexity", "status": "LOW" },
      { "platform": "DeepSeek", "status": "LOW" },
      { "platform": "Claude", "status": "MEDIUM" },
      { "platform": "Google AI", "status": "LOW" },
      { "platform": "Copilot", "status": "LOW" }
    ]
  }
  ```
</ResponseExample>

## Usage on Landing Page

```javascript theme={null}
const response = await fetch(
  `https://searchcompany-main.up.railway.app/api/ranking-score?url=${encodeURIComponent(
    userUrl
  )}`
);
const { score, competitor_scores, platform_statuses } = await response.json();
// Display: "Your AI Visibility Score: 38"
// Show competitor rankings and platform breakdown
```