SERP API

POST

Google arama sonuçlarını yapılandırılmış JSON veya ham HTML formatında alın. Çok sayfalı sorgular, mobil/masaüstü sonuçları ve dil ve ülkeye göre yerelleştirilmiş aramaları destekler.

POST https://data.semust.com/v1/serp

Kimlik Doğrulama

Tüm istekler başlık tabanlı kimlik doğrulama gerektirir. Her istekte API kimlik bilgilerinizi ekleyin.

BaşlıkTürAçıklama
SEMUST-API-USERstringAPI kullanıcı adınız
SEMUST-API-PASSWORDstringAPI şifreniz

API kimlik bilgilerini API Erişim sayfasında doğrulayabilirsiniz.

İstek Başlıkları
SEMUST-API-USER: your_username
SEMUST-API-PASSWORD: your_password

İstek Parametreleri

Aşağıdaki parametrelerle bir application/json gövdesi gönderin:

keyword
string
gerekli

Google'da aranacak arama sorgusu.

language
stringvarsayılan: "en"

Dil kodu (ISO 639-1). Arama sonuçlarının dilini kontrol eder. Örnekler: "en", "tr", "de", "fr", "es".

country
stringvarsayılan: "US"

Ülke kodu (ISO 3166-1 alpha-2). Arama sonuçlarını belirli bir ülkeye hedefler. Örnekler: "US", "TR", "DE", "GB".

format
stringvarsayılan: "json"

Yanıt formatı. "json" ayrıştırılmış yapılandırılmış veri döndürür. "raw" arama sonuçları sayfasının tam HTML'ini döndürür.

mobile
booleanvarsayılan: false

true olduğunda, masaüstü yerine mobil arama sonuçları döndürür.

start_page
integervarsayılan: 1

Alınacak ilk sonuç sayfası. 1 ile 10 arasında olmalıdır.

end_page
integervarsayılan: 1

Alınacak son sonuç sayfası. 1 ile 10 arasında ve >= start_page olmalıdır.

Sayfalama: Hem start_page hem de end_page 1 ile 10 arasında olmalıdır. end_page, start_page'den >= olmalıdır. Çok sayfalı istekler bir dizi döndürür.

İstek Gövdesi
{
  "keyword": "best seo tools",
  "language": "en",
  "country": "US",
  "format": "json",
  "mobile": false,
  "start_page": 1,
  "end_page": 1
}

Kod Örnekleri

Farklı dillerde SERP API'yi nasıl çağıracağınızı gösteren eksiksiz örnekler.

cURL
curl -X POST https://data.semust.com/v1/serp \
  -H "Content-Type: application/json" \
  -H "SEMUST-API-USER: your_username" \
  -H "SEMUST-API-PASSWORD: your_password" \
  -d '{
    "keyword": "best seo tools",
    "language": "en",
    "country": "US",
    "format": "json"
  }'

Çok Sayfalı İstekler

Birden fazla arama sonucu sayfası almak için start_page ve end_page.

ayarlayın. Yanıt, sayfa başına bir tane olmak üzere bir sonuç nesneleri dizisi olacaktır. Her nesne, tek sayfalı bir yanıtla aynı alanları içerir (organic, knowledge_graph, etc.).

Krediler Sayfalanmış bir istekteki her sayfa, temel maliyet üzerinden ücretlendirilir. Örneğin, 3 sayfa talep etmek (start_page: 1, end_page: 3) temel kredi maliyetinin 3 katını tüketir.

Multi-Page (Python)
import requests

response = requests.post(
    "https://data.semust.com/v1/serp",
    headers={
        "SEMUST-API-USER": "your_username",
        "SEMUST-API-PASSWORD": "your_password",
    },
    json={
        "keyword": "best seo tools",
        "format": "json",
        "start_page": 1,
        "end_page": 3,
    },
)

pages = response.json()
for i, page in enumerate(pages, start=1):
    print(f"--- Page {i} ---")
    for result in page.get("organic", []):
        print(f"  {result['rank']}. {result['title']}")
        print(f"     URL: {result['link']}")
        print(f"     Source: {result.get('source', 'N/A')}")

Yanıt

JSON Formatı format: "json"

Ayrıştırılmış arama sonucu verilerini döndürür. Tek sayfalı istekler bir nesne, çok sayfalı istekler bir dizi döndürür.

İç meta veri alanları (general, url, pagination, input) otomatik olarak kaldırılır.

Ham Format format: "raw"

Arama sonuçları sayfasının ham HTML içeriğini text/html olarak döndürür.

Tek Sayfa Yanıtı
{
  "organic": [
    {
      "rank": 1,
      "global_rank": 1,
      "title": "10 Best SEO Tools in 2025",
      "description": "Discover the top SEO tools for improving your website rankings...",
      "link": "https://example.com/best-seo-tools",
      "display_link": "https://example.com › best-seo-tools",
      "source": "Example.com",
      "extensions": [
        {
          "type": "site_link",
          "text": "Free Tools",
          "link": "https://example.com/free-tools",
          "rank": 1
        }
      ]
    },
    {
      "rank": 2,
      "global_rank": 6,
      "title": "SEO Software & Tools",
      "description": "Get more search traffic with our comprehensive SEO toolkit...",
      "link": "https://www.example.com",
      "display_link": "https://www.example.com",
      "source": "Example"
    }
  ],
  "knowledge": {
    "name": "SEO",
    "subtitle": "Search engine optimization",
    "description": "Search engine optimization is the process of...",
    "description_source": "Wikipedia",
    "facts": [{ "key": "Full name", "value": [{ "text": "Search Engine Optimization" }] }]
  },
  "people_also_ask": [
    {
      "rank": 1,
      "global_rank": 2,
      "question": "What is SEO?",
      "answer_source": "Wikipedia",
      "answers": [{ "rank": 1, "type": "answer", "value": { "text": "SEO is..." } }]
    }
  ],
  "related": [
    { "rank": 1, "global_rank": 10, "text": "SEO tools free", "link": "https://..." }
  ],
  "navigation": [{ "title": "Images", "href": "https://..." }],
  "perspectives": [{ "title": "SEO Tips", "author": "Expert", "source": "YouTube" }],
  "ai_overview": { "references": [...], "texts": [...] },
  "images": [{ "rank": 1, "title": "SEO Diagram", "link": "https://...", "image": "https://..." }],
  "top_ads": [{ "rank": 1, "title": "SEO Tool", "link": "https://...", "referral_link": "https://..." }],
  "bottom_ads": [...]
}
Çok Sayfalı Yanıt
[
  {
    "organic": [
      { "rank": 1, "global_rank": 1, "title": "Result 1", "link": "https://...", "source": "..." }
    ],
    "knowledge": { "name": "...", "description": "..." },
    "people_also_ask": [{ "rank": 1, "question": "...", "answers": [...] }],
    "navigation": [{ "title": "Images", "href": "https://..." }]
  },
  {
    "organic": [
      { "rank": 1, "global_rank": 11, "title": "Page 2 Result", "link": "https://...", "source": "..." }
    ],
    "related": [{ "rank": 1, "text": "Related search", "link": "https://..." }]
  }
]

Yanıt Alanları Referansı

Kök Seviye Alanları

Yanıt birden fazla SERP öğesi içerir. Her yanıtta tüm alanlar bulunmayabilir.

AlanTürAçıklama
organicarrayAna organik arama sonuçları
knowledgeobjectBilgi paneli bilgileri (Wikipedia benzeri veriler)
people_also_askarray"İnsanlar ayrıca soruyor" soruları ve yanıtları
relatedarraySERP'in altındaki ilgili aramalar
navigationarrayArama türü sekmeleri (Görseller, Videolar, Haberler, vb.)
perspectivesarraySosyal medya ve forum perspektifleri
ai_overviewobjectYapay zeka tarafından oluşturulan genel bakış (Google AI Overviews)
imagesarrayGörsel karusel sonuçları
top_adsarraySayfanın üstündeki sponsorlu sonuçlar
bottom_adsarraySayfanın altındaki sponsorlu sonuçlar
overviewobjectBilgi grafiği meta verileri (kgmid, başlık)

Organik Sonuç Alanları

AlanTürAçıklama
rankintegerOrganik sonuçlar içindeki konum (1'den başlar)
global_rankintegerTüm SERP öğeleri arasındaki konum
titlestringSonuç başlığı
descriptionstringSonuç açıklaması/snippet
linkstringHedef URL
display_linkstringSERP'te görüntülenen biçimlendirilmiş URL
sourcestringWeb sitesi veya kaynak adı
extensionsarraySite bağlantıları, tarihler ve diğer uzantılar
imagestringKüçük resim URL'si (video sonuçları için)
durationstringVideo süresi (ör. "19:10")
duration_secintegerSaniye cinsinden video süresi

Hata Kodları

Tüm hatalar, insan tarafından okunabilir bir mesaj ve bir hata kodu içeren bir JSON nesnesi döndürür.

DurumKodAçıklama
400
INVALID_REQUESTİstek gövdesi hatalı biçimlendirilmiş veya gerekli alanlar eksik
400
KEYWORD_REQUIREDAnahtar kelime alanı boş veya eksik
400
INVALID_FORMATFormat alanı "json" veya "raw" değil
401
INVALID_API_KEYKimlik doğrulama başarısız — geçersiz kullanıcı adı veya şifre
402
INSUFFICIENT_CREDITSHesabınızda yeterli kredi yok
429
RATE_LIMIT_EXCEEDEDÇok fazla istek — hız sınırı aşıldı
500
INTERNAL_ERRORBir iç sunucu hatası oluştu
502
SERP_FAILEDArama sonuçları alınamadı
504
TIMEOUTİstek zaman aşımına uğradı (maks 10 dakika)
Hata Yanıtı
{
  "error": "Your account does not have enough credits",
  "code": "INSUFFICIENT_CREDITS"
}

Krediler & Hız Sınırları

Krediler

Her istek, bakiyenizden kredi tüketir. Maliyet, mobile parametresine göre değişebilir. Bakiyeniz yetersizse, API HTTP 402 döndürür.

Hız Sınırları

İstekler, planınıza göre dakika başına ve gün başına sınırlara tabidir. Sınırların aşılması HTTP 429 döndürür.