SERP API
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/serpKimlik Doğrulama
Tüm istekler başlık tabanlı kimlik doğrulama gerektirir. Her istekte API kimlik bilgilerinizi ekleyin.
| Başlık | Tür | Açıklama |
|---|---|---|
SEMUST-API-USER | string | API kullanıcı adınız |
SEMUST-API-PASSWORD | string | API şifreniz |
API kimlik bilgilerini API Erişim sayfasında doğrulayabilirsiniz.
SEMUST-API-USER: your_username
SEMUST-API-PASSWORD: your_passwordİstek Parametreleri
Aşağıdaki parametrelerle bir application/json gövdesi gönderin:
keywordGoogle'da aranacak arama sorgusu.
language"en"Dil kodu (ISO 639-1). Arama sonuçlarının dilini kontrol eder. Örnekler: "en", "tr", "de", "fr", "es".
country"US"Ülke kodu (ISO 3166-1 alpha-2). Arama sonuçlarını belirli bir ülkeye hedefler. Örnekler: "US", "TR", "DE", "GB".
format"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.
mobilefalsetrue olduğunda, masaüstü yerine mobil arama sonuçları döndürür.
start_page1Alınacak ilk sonuç sayfası. 1 ile 10 arasında olmalıdır.
end_page1Alı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.
{
"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 -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.
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.
{
"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": [...]
}[
{
"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.
| Alan | Tür | Açıklama |
|---|---|---|
organic | array | Ana organik arama sonuçları |
knowledge | object | Bilgi paneli bilgileri (Wikipedia benzeri veriler) |
people_also_ask | array | "İnsanlar ayrıca soruyor" soruları ve yanıtları |
related | array | SERP'in altındaki ilgili aramalar |
navigation | array | Arama türü sekmeleri (Görseller, Videolar, Haberler, vb.) |
perspectives | array | Sosyal medya ve forum perspektifleri |
ai_overview | object | Yapay zeka tarafından oluşturulan genel bakış (Google AI Overviews) |
images | array | Görsel karusel sonuçları |
top_ads | array | Sayfanın üstündeki sponsorlu sonuçlar |
bottom_ads | array | Sayfanın altındaki sponsorlu sonuçlar |
overview | object | Bilgi grafiği meta verileri (kgmid, başlık) |
Organik Sonuç Alanları
| Alan | Tür | Açıklama |
|---|---|---|
rank | integer | Organik sonuçlar içindeki konum (1'den başlar) |
global_rank | integer | Tüm SERP öğeleri arasındaki konum |
title | string | Sonuç başlığı |
description | string | Sonuç açıklaması/snippet |
link | string | Hedef URL |
display_link | string | SERP'te görüntülenen biçimlendirilmiş URL |
source | string | Web sitesi veya kaynak adı |
extensions | array | Site bağlantıları, tarihler ve diğer uzantılar |
image | string | Küçük resim URL'si (video sonuçları için) |
duration | string | Video süresi (ör. "19:10") |
duration_sec | integer | Saniye 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.
| Durum | Kod | Açıklama |
|---|---|---|
400 | INVALID_REQUEST | İstek gövdesi hatalı biçimlendirilmiş veya gerekli alanlar eksik |
400 | KEYWORD_REQUIRED | Anahtar kelime alanı boş veya eksik |
400 | INVALID_FORMAT | Format alanı "json" veya "raw" değil |
401 | INVALID_API_KEY | Kimlik doğrulama başarısız — geçersiz kullanıcı adı veya şifre |
402 | INSUFFICIENT_CREDITS | Hesabınızda yeterli kredi yok |
429 | RATE_LIMIT_EXCEEDED | Çok fazla istek — hız sınırı aşıldı |
500 | INTERNAL_ERROR | Bir iç sunucu hatası oluştu |
502 | SERP_FAILED | Arama sonuçları alınamadı |
504 | TIMEOUT | İstek zaman aşımına uğradı (maks 10 dakika) |
{
"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.
