SERP API (Rank Finder)

{
  "success": true,
  "url": "example.com",
  "keyword": "seo aracı",
  "engine": "google",
  "source": "google",
  "location": "tr",
  "found": true,
  "position": 3,
  "page": 1,
  "results": [
    {
      "position": 1,
      "page": 1,
      "title": "En İyi SEO Araçları",
      "url": "https://competitor.com/seo-araclari",
      "description": "…",
      "is_target": false
    },
    {
      "position": 3,
      "page": 1,
      "title": "Example — SEO Aracı",
      "url": "https://example.com/",
      "description": "…",
      "is_target": true
    }
  ],
  "message": "Siteniz 3. sırada (1. sayfa).",
  "attribution": {
    "text": "Powered by Spindora",
    "url": "https://www.spindorai.com",
    "required": true
  }
}

{
  "success": true,
  "url": "example.com",
  "keyword": "çok nadir kelime",
  "engine": "google",
  "location": "tr",
  "found": false,
  "position": null,
  "page": null,
  "results": [],
  "message": "İlk 5 sayfada bulunamadı.",
  "attribution": {
    "text": "Powered by Spindora",
    "url": "https://www.spindorai.com",
    "required": true
  }
}

<a href="https://www.spindorai.com" target="_blank" rel="noopener noreferrer">
  Powered by Spindora
</a>

const API = 'https://www.spindorai.com/api/public-rank-finder';
const KEY = 'sp_serp_YOUR_KEY_HERE';

async function checkRank(url, keyword) {
  const res = await fetch(`${API}/check`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-Spindora-Key': KEY,
    },
    body: JSON.stringify({
      url,
      keyword,
      engine: 'google',
      location: 'tr',
      locale: 'tr',
      max_pages: 5,
    }),
  });

  if (!res.ok) {
    const err = await res.json().catch(() => ({}));
    throw new Error(err.detail?.message || err.detail || res.statusText);
  }

  const data = await res.json();
  // data.found, data.position, data.page, data.results
  return data;
}

import requests

API = "https://www.spindorai.com/api/public-rank-finder"
KEY = "sp_serp_YOUR_KEY_HERE"
HEADERS = {"X-Spindora-Key": KEY, "Content-Type": "application/json"}

def check_rank(url: str, keyword: str) -> dict:
    r = requests.post(
        f"{API}/check",
        headers=HEADERS,
        json={
            "url": url,
            "keyword": keyword,
            "engine": "google",
            "location": "tr",
            "locale": "tr",
            "max_pages": 5,
        },
        timeout=60,
    )
    r.raise_for_status()
    return r.json()

# result["found"], result["position"], result["results"]

const API = 'https://www.spindorai.com/api/public-rank-finder';
const KEY = 'sp_serp_YOUR_KEY_HERE';

async function checkRank(url, keyword) {
  const res = await fetch(`${API}/check`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-Spindora-Key': KEY,
    },
    body: JSON.stringify({
      url,
      keyword,
      engine: 'google',
      location: 'tr',
      locale: 'tr',
      max_pages: 5,
    }),
  });

  if (!res.ok) {
    const err = await res.json().catch(() => ({}));
    throw new Error(err.detail?.message || err.detail || res.statusText);
  }

  const data = await res.json();
  // data.found, data.position, data.page, data.results
  return data;
}

<?php
$api = 'https://www.spindorai.com/api/public-rank-finder';
$key = 'sp_serp_YOUR_KEY_HERE';

function checkRank(string $url, string $keyword): array {
    global $api, $key;

    $ch = curl_init("$api/check");
    curl_setopt_array($ch, [
        CURLOPT_POST => true,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => [
            'Content-Type: application/json',
            "X-Spindora-Key: $key",
        ],
        CURLOPT_POSTFIELDS => json_encode([
            'url' => $url,
            'keyword' => $keyword,
            'engine' => 'google',
            'location' => 'tr',
            'locale' => 'tr',
            'max_pages' => 5,
        ]),
        CURLOPT_TIMEOUT => 60,
    ]);
    $body = curl_exec($ch);
    $code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    if ($code !== 200) {
        throw new RuntimeException($body ?: "HTTP $code");
    }
    return json_decode($body, true);
}

# Spindora SERP API — Integration Brief

Base URL: https://www.spindorai.com/api/public-rank-finder
Documentation: https://www.spindorai.com/developers/serp-api
OpenAPI JSON: https://www.spindorai.com/developers/serp-api.openapi.json
API Key: Register → log in → https://www.spindorai.com/api-keys → create key under SERP API tab (sp_serp_*)

## Authentication
Header: X-Spindora-Key: sp_serp_YOUR_KEY
Alternative: Authorization: Bearer sp_serp_YOUR_KEY

## Flow (synchronous — no polling)
POST /check
Body: {"url":"example.com","keyword":"seo tool","engine":"google","location":"tr","locale":"en","max_pages":5}
→ HTTP 200 returns position, page, results[]

## Quota
Monthly, user-level (shared across all SERP keys):
Free 50 | Starter 100 | Pro 200 | Pro+ 400 | Enterprise 800 / month
Remaining quota: GET https://www.spindorai.com/api/api-hub/status (Spindora session JWT)

## Requirements
- API key required for external integrations
- Show attribution in UI: Powered by Spindora → https://www.spindorai.com

## Error codes
401 invalid key | 403 plan expired | 429 monthly quota exceeded | 400 missing keyword | 500 temporary SERP error