API Platformu

Trends API

En fazla beş anahtar kelime için Google Trends verisi — zamana göre ilgi, bölgeler, ilgili aramalar — ve yaş ile cinsiyet demografisi, istek başına sabit ücretle.

En fazla beş anahtar kelimeye olan arama ilgisinin zamanla nasıl değiştiğini, nereden geldiğini, yanında neler arandığını ve kimlerin aradığını öğrenin. Tek bir endpoint, type parametresiyle seçilen dört rapor sunar. İlgi, bölgeler ve ilgili aramalar Google Trends verisidir; demografi ise Google Trends'te bulunmadığı için tıklama akışı (clickstream) verisine dayalı bir tahmindir.

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

60 saniyeden uzun süren istekler

Bu endpoint istekleri task olarak çalıştırır. 60 saniyeden uzun süren istekler task_id içeren bir 202 döndürür; sonucu GET /v1/tasks/{task_id} ile alırsınız. Normal 200 dahil her response, task id'yi X-Task-Id header'ında taşır. İsteğin ne kadar bekleyeceğini ?wait= ile değiştirebilir, Idempotency-Key header'ıyla güvenle tekrar deneyebilirsiniz.

Kimlik Doğrulama

Header	Tip	Açıklama
`SEMUST-API-USER`	string	API kullanıcınızın kullanıcı adı
`SEMUST-API-PASSWORD`	string	API kullanıcınızın şifresi
`Accept-Language`	string	İsteğe bağlı. Hata mesajlarını Türkçe almak için `tr` gönderin

API kimlik bilgilerinizi API Erişimi sayfasından oluşturun.

SEMUST-API-USER: kullanici_adiniz
SEMUST-API-PASSWORD: sifreniz
Content-Type: application/json
Accept-Language: tr

Rapor Tipleri

`type`	Döndürdüğü	Anahtar kelime	Ücret
`interest` (varsayılan)	Zamana göre ilgi: her aralık için bir nokta ve her kelimenin ortalaması	1–5	$0.0121
`regions`	Bölgelere göre ilgi (Türkiye için iller) ve kelimelerin her bölgedeki payı	1–5	$0.0121
`related`	En çok aranan ve yükselen ilgili aramalar ile ilgili konular	1	$0.0121
`demographics`	Yaş grubuna ve cinsiyete göre ilgi	1–5	$0.00264

Ücret istek başınadır: beş kelimeyi karşılaştırmak, dönem ya da arama türü ne olursa olsun, tek kelimeyle aynı ücreti öder.

{
  "keywords": ["iphone 17", "samsung s26"],
  "period": "past_12_months"
}

{
  "type": "related",
  "keywords": ["iphone 17"]
}

İstek Parametreleri

Seçilen type için geçerli olmayan bir parametre yok sayılmaz, reddedilir; yanlış yazılmış bir parametre ise hatada adıyla ve bir öneriyle bildirilir. JSON null değeri "gönderilmedi" sayılır.

Body

typestringdefault: interest

interest, regions, related veya demographics.

keywordsstring[]

Zorunlu. Karşılaştırılacak 1–5 anahtar kelime (related için tam olarak bir). Her biri en fazla 100 karakter olmalı ve virgül içermemelidir. Yalnızca büyük/küçük harfle ayrılan tekrarlar atılır, ilk yazım korunur.

countrystringdefault: TR

İki harfli ülke kodu. Pazarlar için aşağıya bakın.

languagestring

demographics için kullanılamaz. Bölge adlarının ve ilgili konuların dili. TR için varsayılan tr, diğer ülkelerde en. Hangi aramaların sayıldığını değiştirmez.

periodstringdefault: past_12_months

past_day, past_7_days, past_30_days, past_90_days, past_12_months veya past_5_years.

search_typestringdefault: web

demographics için kullanılamaz. Aramaların sayıldığı yer: web, news, images, youtube veya shopping.

idempotency_keystring

İsteğe bağlı, en fazla 128 karakter. Aynı anahtarla tekrarlanan istek aynı task'ı döndürür: task çalışırken 202'sini, bittiğinde saklanan sonucunu. Task bir kez ücretlendirilir. Anahtar, task bittikten sonra 72 saat boyunca ayrılmış kalır. Idempotency-Key header'ıyla aynı işi görür; ikisi birden gönderilirse bu alan geçerli olur.

Query

waitintegerdefault: 60

Sonucun bekleneceği saniye, 0–80. İstek bu sürenin sonunda hâlâ çalışıyorsa response bir task_id ile 202 olur. 0 hemen 202 döndürür.

Headers

Idempotency-Keystring

İsteğe bağlı. Yukarıdaki idempotency_key gibi çalışır; ikisi birden gönderilirse body alanı geçerli olur.

GET /v1/trends/markets desteklenen tüm ülkeleri ve dilleri listeler. Ücretsizdir.

60 saniye sonunda hâlâ çalışan bir istek 202 döner. Task'lar ve Uzun Süren İstekler sayfasındaki call() yardımcısı sonuç hazır olana kadar sorgular.

curl -X POST https://data.semust.com/v1/trends \
  -H "SEMUST-API-USER: kullanici_adiniz" \
  -H "SEMUST-API-PASSWORD: sifreniz" \
  -H "Content-Type: application/json" \
  -H "Accept-Language: tr" \
  -d '{"keywords": ["iphone 17", "samsung s26"], "period": "past_90_days"}'

import requests

response = requests.post(
    "https://data.semust.com/v1/trends",
    headers={
        "SEMUST-API-USER": "kullanici_adiniz",
        "SEMUST-API-PASSWORD": "sifreniz",
        "Accept-Language": "tr",
    },
    json={"keywords": ["iphone 17", "samsung s26"]},
    timeout=90,  # ?wait= süresinden uzun olmalı (varsayılan 60 saniye)
)

data = response.json()
if response.status_code == 202:
    # Hâlâ çalışıyor. Sonucu daha sonra data["poll_url"] adresinden alın
    # ya da Task'lar sayfasındaki call() yardımcısını kullanın.
    raise SystemExit(f"Task {data['task_id']} hâlâ çalışıyor")
if response.status_code != 200:
    raise SystemExit(f"{data['code']}: {data['error']} {data.get('hint', '')}")

# values, data["keywords"] ile aynı sıradadır
for point in data["items"]:
    print(point["time"], dict(zip(data["keywords"], point["values"])))

Response

interest, regions ve demographics satırları items içinde döndürür; related tek bir data nesnesi döndürür. Kelime başına her liste (values, averages, interest, share) zarftaki keywords ile aynı sıradadır; konuma göre okuyabilirsiniz.

İlgi bir arama sayısı değil, görelidir. interest raporunda 100, dönem içinde herhangi bir kelimenin ulaştığı en yüksek noktadır; bu sayede kelimeler doğrudan karşılaştırılabilir. regions raporunda interest her kelimeyi kendi ölçeğine koyar (100, o kelimenin en güçlü olduğu bölgedir); share ise bir bölgedeki aramaların kelimeler arasında nasıl bölündüğünü yüzde olarak verir. Demografi değerleri, kelimenin en büyük grubuna göre 0–100 arasıdır.

Verisi olmayan bir kelime geçerli bir yanıttır: items boş, değerler null döner. Diğer istekler gibi ücretlendirilir.

Aşağıdaki örnekler gerçek yanıtlardır.

{
  "success": true,
  "type": "interest",
  "keywords": ["iphone 17", "samsung s26"],
  "country": "TR",
  "language": "tr",
  "period": "past_12_months",
  "search_type": "web",
  "averages": [56, 7],
  "count": 53,
  "items": [
    { "time": "2025-11-02T00:00:00Z", "values": [57, 2], "partial": false },
    { "time": "2025-11-09T00:00:00Z", "values": [60, 2], "partial": false },
    { "time": "2026-11-01T00:00:00Z", "values": [46, 9], "partial": true }
  ],
  "cost": 0.0121,
  "cached": false,
  "request_id": "0b7e6f1a-3c2d-4e5f-9a8b-1c2d3e4f5a6b"
}

{
  "success": true,
  "type": "regions",
  "keywords": ["iphone 17", "samsung s26"],
  "country": "TR",
  "language": "tr",
  "period": "past_12_months",
  "search_type": "web",
  "count": 81,
  "items": [
    { "region": "Tunceli", "region_code": "TR-62", "interest": [100, 100], "share": [87, 13] },
    { "region": "Kırıkkale", "region_code": "TR-71", "interest": [96, 65], "share": [91, 9] },
    { "region": "Kocaeli", "region_code": "TR-41", "interest": [94, 65], "share": [90, 10] }
  ],
  "cost": 0.0121,
  "cached": false,
  "request_id": "5d4c3b2a-1f0e-4d9c-8b7a-6f5e4d3c2b1a"
}

{
  "success": true,
  "type": "related",
  "keywords": ["iphone 17"],
  "country": "TR",
  "language": "tr",
  "period": "past_12_months",
  "search_type": "web",
  "data": {
    "top_queries": [
      { "query": "iphone 17 pro", "value": 100 },
      { "query": "17 pro", "value": 94 }
    ],
    "rising_queries": [
      { "query": "iphone 17e", "value": 1650 }
    ],
    "top_topics": [
      { "topic": "iPhone", "category": "Cep telefonu", "value": 100 },
      { "topic": "iPhone 17", "category": "Cep telefonu", "value": 69 }
    ],
    "rising_topics": [
      { "topic": "Apple iPhone 17 Pro Max", "category": "Cep telefonu", "value": 223050 }
    ]
  },
  "cost": 0.0121,
  "cached": false,
  "request_id": "9a8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d"
}

{
  "success": true,
  "type": "demographics",
  "keywords": ["iphone 17"],
  "country": "TR",
  "period": "past_12_months",
  "count": 1,
  "items": [
    {
      "keyword": "iphone 17",
      "age": [
        { "group": "18-24", "value": 37 },
        { "group": "25-34", "value": 97 },
        { "group": "35-44", "value": 100 },
        { "group": "45-54", "value": 41 }
      ],
      "gender": [
        { "group": "female", "value": 89 },
        { "group": "male", "value": 100 }
      ]
    }
  ],
  "cost": 0.00264,
  "cached": false,
  "request_id": "1e2d3c4b-5a6f-4e7d-8c9b-0a1f2e3d4c5b"
}

Yanıt Alanları Referansı

Zarf

Alan	Tip	Açıklama
`keywords`	string[]	Tekrarlar atıldıktan sonra çalıştırılan kelimeler. Kelime başına her liste bu sırayı izler
`averages`	(integer \| null)[]	Yalnızca `interest`. Her kelimenin dönem ortalaması
`count`	integer	`items` içindeki satır sayısı

`interest` satırı

Alan	Tip	Açıklama
`time`	string	Aralığın başlangıcı, UTC olarak ISO 8601. Aralık döneme göre değişir: `past_day` için dakikalar, `past_7_days` için saatler, daha uzun dönemler için günler ya da haftalar (`past_12_months` için haftalar)
`values`	(integer \| null)[]	Kelime başına ilgi, 0–100
`partial`	boolean	Hâlâ devam eden aralık için `true`; değeri değişecektir

`regions` satırı

Alan	Tip	Açıklama
`region`, `region_code`	string, string \| null	`language` dilinde bölge adı ve ISO 3166-2 kodu (`TR-34`)
`interest`	(integer \| null)[]	Her kelimenin bu bölgedeki ilgisi, kendi ölçeğinde 0–100
`share`	(integer \| null)[] \| null	Bu bölgedeki aramaların kelimeler arasındaki yüzde payı. Tek kelimede `null`

Satırlar ilk kelimenin ilgisine göre, en yüksekten başlayarak sıralanır.

`related` → `data`

top_queries ve rising_queries {query, value}, top_topics ve rising_topics ise {topic, category, value} biçimindedir; category, konunun türüdür ve language dilindedir. En çok arananlar listelerinde value 0–100 arası göreli ilgidir. Yükselenler listelerinde önceki döneme göre yüzde artıştır.

`demographics` satırı

keyword, age ve gender; her biri {group, value} listesidir. Verisi olmayan kelimede listeler boştur.

Hatalar

Her hata sabit bir code, okunabilir bir error ve retryable içerir; faydalı olduğunda ayrıca field, hint ve allowed. Türkçe mesajlar için Accept-Language: tr gönderin. Bir hata için asla ücret alınmaz. Diğer API'lerle ortak tam liste Hata Kodları sayfasındadır. Bu endpoint'e özgü olanlar:

Durum	Kod	Anlamı	Ne yapmalı
202	—	Hata değil: istek `wait` saniye sonunda hâlâ çalışıyor	`GET /v1/tasks/{task_id}` ile sorgulayın; bkz. Task'lar
400	`KEYWORDS_REQUIRED`	`keywords` yok ya da liste boş	1–5 anahtar kelime gönderin
400	`TOO_MANY_KEYWORDS`	5'ten fazla kelime ya da `related` için birden fazla kelime	İsteği bölün
400	`INVALID_PARAMETER`	ör. 100 karakterden uzun ya da virgül içeren bir kelime veya bilinmeyen bir `period`; `field` hangisi olduğunu söyler, `allowed` geçerli değerleri listeler	Alanı düzeltin
400	`UNSUPPORTED_MARKET`	Bilinmeyen ülke ya da dil	`GET /v1/trends/markets`

{
  "error": "type=related en fazla 1 anahtar kelime kabul eder",
  "code": "TOO_MANY_KEYWORDS",
  "field": "keywords",
  "hint": "interest, regions ve demographics en fazla 5 kelimeyi karşılaştırır; related her istekte tek kelime alır",
  "retryable": false
}

{
  "error": "'language' parametresi type=demographics ile kullanılamaz",
  "code": "PARAMETER_NOT_ALLOWED",
  "field": "language",
  "hint": "Bu parametreyi kabul eden tipler: interest, regions, related",
  "retryable": false
}

Krediler ve Sınırlar

İstek	Ücret
`interest`, `regions` veya `related`	$0.0121
`demographics`	$0.00264

Ücret kelime sayısına, döneme ya da arama türüne bağlı değildir. Verisi olmayan bir yanıt da aynı ücretle faturalanır.

Sonuçlar önbellekte tutulur: past_day için 1 saat, past_7_days için 6 saat, daha uzun dönemler için 24 saat. Önbellekten dönen yanıt "cached": true ile işaretlenir ve canlı yanıtla aynı ücreti öder.

Dakikalık ve günlük sınırlar hesabınızda tanımlıdır (429 RATE_LIMIT_EXCEEDED). API kullanıcısı başına aynı anda en fazla 5 istek çalışır; fazlası Retry-After ile 429 TOO_MANY_CONCURRENT_REQUESTS alır. 202 dönmüş bir istek, task'ı bitene kadar yerini korur. API kullanıcısı başına aynı anda en fazla 100 task bitmemiş durumda olabilir (429 TOO_MANY_PENDING_TASKS). Sorgulamanın kendi limiti vardır ve bunların hiçbirine sayılmaz; bkz. Task'lar.

Son güncelleme: 2026-11-07