İçeriğe atla
ShopentlyLearn

Getir · Arama sorguları — Arama analitiği ve kuralları

“Arama analitiği ve kuralları” verilerini okuyun. Sonuç, bu işlemin parametrelerine bağlıdır.

GET/api/v1/search/queries/{query_hash}

Kimlik doğrulama
Bearer
En düşük plan
STANDARD
Gerekli izinler
search.analytics:read

Kod örnekleri

İstek örneği

cURL

: "${SHOPENTLY_SHOP_URL:?}"

curl --disable --globoff --fail-with-body --silent --show-error \
  --proto '=https' --connect-timeout 5 --max-time 30 \
  --request GET \
  --header "Authorization: Bearer ${SHOPENTLY_ACCESS_TOKEN:?}" \
  --url "${SHOPENTLY_SHOP_URL%/}"'/api/v1/search/queries/aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa?limit=20'

PHP

<?php
declare(strict_types=1);

$baseUrl = rtrim(getenv('SHOPENTLY_SHOP_URL') ?: '', '/');
$origin = parse_url($baseUrl);
if (!$origin || ($origin['scheme'] ?? '') !== 'https' || empty($origin['host']) ||
    isset($origin['user'], $origin['pass']) || isset($origin['user']) || isset($origin['path']) ||
    isset($origin['query']) || isset($origin['fragment'])) {
    throw new RuntimeException('SHOPENTLY_SHOP_URL must be an HTTPS origin');
}
$credential = getenv('SHOPENTLY_ACCESS_TOKEN') ?: '';
if ($credential === '' || strpbrk($credential, "\r\n") !== false) {
    throw new RuntimeException('Invalid credential');
}
$headers = [];
$headers[] = 'Authorization: Bearer ' . $credential;
$responseHeaders = [];
$handle = curl_init($baseUrl . '/api/v1/search/queries/aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa?limit=20');
curl_setopt_array($handle, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_HTTPHEADER => $headers,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_FOLLOWLOCATION => false,
    CURLOPT_PROTOCOLS => CURLPROTO_HTTPS,
    CURLOPT_SSL_VERIFYPEER => true,
    CURLOPT_SSL_VERIFYHOST => 2,
    CURLOPT_CONNECTTIMEOUT => 5,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HEADERFUNCTION => static function ($handle, string $line) use (&$responseHeaders): int {
        if (str_contains($line, ':')) {
            [$name, $value] = explode(':', $line, 2);
            $responseHeaders[strtolower(trim($name))] = trim($value);
        }
        return strlen($line);
    },
]);
$raw = curl_exec($handle);
$status = curl_getinfo($handle, CURLINFO_RESPONSE_CODE);
$error = curl_error($handle);
curl_close($handle);
if ($raw === false) {
    throw new RuntimeException('Transport error: ' . $error);
}
if ($status < 200 || $status >= 300) {
    throw new RuntimeException('HTTP ' . $status . '; request_id=' .
        ($responseHeaders['x-request-id'] ?? '') . '; retry_after=' . ($responseHeaders['retry-after'] ?? ''));
}
$result = $raw === '' ? null : json_decode($raw, true, 512, JSON_THROW_ON_ERROR | JSON_BIGINT_AS_STRING);
echo json_encode($result, JSON_THROW_ON_ERROR | JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE), PHP_EOL;

Python

from contextlib import ExitStack
import json
import os
from urllib.parse import urlsplit

import requests  # python -m pip install requests

base_url = os.environ["SHOPENTLY_SHOP_URL"].rstrip("/")
origin = urlsplit(base_url)
if origin.scheme != "https" or not origin.hostname or origin.username or origin.password or origin.path or origin.query or origin.fragment:
    raise ValueError("SHOPENTLY_SHOP_URL must be an HTTPS origin")
credential = os.environ['SHOPENTLY_ACCESS_TOKEN']
if not credential or "\r" in credential or "\n" in credential:
    raise ValueError("Invalid credential")
headers = {}
headers["Authorization"] = 'Bearer' + " " + credential
body = None
if body is not None:
    headers["Content-Type"] = "application/json"

with ExitStack() as stack:
    session = stack.enter_context(requests.Session())
    files = None
    if False:
        image = stack.enter_context(open(os.environ["SHOPENTLY_IMAGE_FILE"], "rb"))
        if os.fstat(image.fileno()).st_size > 5242880:
            raise ValueError("Image exceeds 5 MiB")
        files = {"file": ("article.png", image, "image/png")}
    response = session.request(
        'GET', base_url + '/api/v1/search/queries/aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa?limit=20', headers=headers,
        data=body.encode("utf-8") if body is not None else None, files=files,
        timeout=(5, 30), allow_redirects=False,
    )
    if not 200 <= response.status_code < 300:
        raise RuntimeError(f"HTTP {response.status_code}; request_id={response.headers.get('X-Request-ID', '')}; retry_after={response.headers.get('Retry-After', '')}")
    if False:
        if response.headers.get("Content-Type") != "image/webp" or len(response.content) > 5242880:
            raise ValueError("Unexpected image response")
        with open(os.environ["SHOPENTLY_OUTPUT_FILE"], "xb") as output:
            output.write(response.content)
    else:
        result = response.json() if response.content else None
        print(json.dumps(result, ensure_ascii=False, indent=2))

Yanıt örneği 200

JSON
{
  "data": [
    {
      "category_id": "example",
      "category_result_count": 1,
      "currency_code": "PLN",
      "is_zero_results": false,
      "locale_code": "en",
      "market_id": "example",
      "max_price": "0.00",
      "min_price": "0.00",
      "occurred_at": "2026-01-01T12:00:00Z",
      "page": 1,
      "product_result_count": 1,
      "query_display": "example",
      "request_id": "example",
      "results": [
        {
          "clicked": false,
          "entity_id": "example",
          "entity_type": "product",
          "image_url": "https://example.invalid/product.jpg",
          "number": "example",
          "placement_source": "organic",
          "position": 1,
          "sku": "example",
          "slug": "example",
          "title": "example"
        }
      ],
      "sort_key": "example",
      "source": "results"
    }
  ],
  "meta": {
    "pagination": {
      "has_more": false,
      "limit": 20,
      "next_cursor": null
    },
    "period": {
      "as_of": "2026-01-02T00:00:00Z",
      "days": 1,
      "started_at": "2026-01-01T00:00:00Z"
    },
    "request_id": "example"
  }
}

Nasıl çalışır

  • GET /api/v1/search/overview ve /api/v1/search/queries, özet istatistikleri ve gruplanmış sorguları sunar.
  • Bir sorgunun gerçekleşme kayıtlarını query_hash ile alın.
  • Raporlama dönemleri 7, 30 veya 90 günü destekler; filtreler her uç noktanın açıklamasında listelenir.
  • Arama kuralları ifadeleri seçilen ürünlere ve kategorilere bağlar; oluşturulabilir, okunabilir, güncellenebilir veya silinebilir.
  • Kurallar ve analitik ayrı izinlere sahiptir; arama istatistiklerini okumak yapılandırma erişimi vermez.

Parametreler

Yol parametreleri

query_hashDizeZorunlu

Gruplanmış arama ifadesinin sabit tanımlayıcısı.

Kısıtlamalar
pattern
"^[a-f0-9]{64}$"
Örnek: "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"

Sorgu parametreleri

limitTam sayıİsteğe bağlı

Bu sayfadaki en yüksek kayıt sayısı.

minimum: 1maximum: 100
Varsayılan: 50Örnek: 20
cursorDize nullİsteğe bağlı

Önceki sayfanın döndürdüğü, iç yapısı yorumlanmaması gereken devam değeri.

Dize:minLength: 1maxLength: 1024
daysTam sayıİsteğe bağlı

Gün cinsinden raporlama dönemi.

Kısıtlamalar
enum
[7, 30, 90]
Varsayılan: 30
localeDize nullİsteğe bağlı

Bu istek için seçilen dil.

Dize:minLength: 2maxLength: 20
Kısıtlamalar · Dize 1
pattern
"^[a-z]{2,3}(?:-[A-Za-z0-9]{2,8})*$"
sourceDize nullİsteğe bağlı

Kaydedilen etkinliğin kaynağı.

Kısıtlamalar · Dize 1
enum
["results", "autocomplete"]
market_idDize nullİsteğe bağlı

Bağlam uç noktasının döndürdüğü pazar tanımlayıcısı.

Kısıtlamalar · Dize 1
pattern
"^[a-z0-9][a-z0-9_-]{0,62}$"

Bu işlem JSON gövdesi kabul etmez.

Yanıtlar

Yanıt 200

dataDizi <OccurrenceData > Zorunlu

Başarılı yanıtın verileri.

Alanlar · data

OccurrenceData

category_idDize nullZorunlu

Kategori tanımlayıcısı.

category_result_countTam sayıZorunlu

Kategori sonuçlarının sayısı.

currency_codeDizeZorunlu

Para birimi kodu.

is_zero_resultsMantıksal değerZorunlu

Aramanın sonuçsuz kalıp kalmadığı.

locale_codeDizeZorunlu

Dil kodu.

market_idDizeZorunlu

Bağlam uç noktasının döndürdüğü pazar tanımlayıcısı.

max_priceDize nullZorunlu

Bildirilen aralıktaki en yüksek fiyat.

min_priceDize nullZorunlu

Bildirilen aralıktaki en düşük fiyat.

occurred_atDizeZorunlu

Olay tarihi ve saati.

format: "date-time"
pageTam sayıZorunlu

CMS sayfası bilgileri.

product_result_countTam sayıZorunlu

Ürün arama sonuçlarının sayısı.

query_displayDizeZorunlu

Yöneticiye gösterilen arama ifadesi.

request_idDizeZorunlu

Talep tanımlayıcısı; yanıt üst verilerinde HTTP isteğini tanımlar.

resultsDizi <ResultSnapshotData > nullZorunlu

Kaydedilen arama sonuçları.

sort_keyDizeZorunlu

Sıralama anahtarı.

sourceDizeZorunlu

Kaydedilen etkinliğin kaynağı.

Kısıtlamalar
enum
["results", "autocomplete"]
metaAnalyticsPageMeta AnalyticsMeta Zorunlu

Yanıt üst verileri.

Alanlar · meta

AnalyticsPageMeta

paginationPagination Zorunlu

İmleç tabanlı sayfalamanın üst verileri.

periodAnalyticsPeriodData Zorunlu

Raporlama dönemi ve sınırları.

request_idDizeZorunlu

Talep tanımlayıcısı; yanıt üst verilerinde HTTP isteğini tanımlar.

minLength: 1maxLength: 100

AnalyticsMeta

periodAnalyticsPeriodData Zorunlu

Raporlama dönemi ve sınırları.

request_idDizeZorunlu

Talep tanımlayıcısı; yanıt üst verilerinde HTTP isteğini tanımlar.

minLength: 1maxLength: 100
Yanıt örneği

HTTP durumu

200
Başarılı yanıt Şema
400
Geçersiz istek
401
Kimlik doğrulaması gerekli
403
İzin reddedildi
404
Kaynak bulunamadı
409
Sürüm çakışması
422
Doğrulama başarısız
429
İstek sınırı aşıldı
Diğer HTTP durumları (7)
405
Yönteme izin verilmiyor
413
İstek çok büyük
415
Desteklenmeyen biçim
500
Sunucu hatası
502
API ağ geçidi hatası
503
Hizmet kullanılamıyor
504
Zaman aşımı

Hata kataloğu: ErrorResponse

Başlıklar

401

WWW-AuthenticateDizeİsteğe bağlı

Sunucunun gerektirdiği kimlik doğrulama şeması.

405

AllowDizeİsteğe bağlı

Bu kaynağın desteklediği HTTP yöntemleri.

429, 503

Retry-AfterTam sayıİsteğe bağlı

Yeniden denemeden önce saniye cinsinden en kısa bekleme süresi.

minimum: 0