Pereiti prie turinio
ShopentlyLearn

Gauti · Paieškos užklausos — Paieškos analitika ir taisyklės

Skaitykite „Paieškos analitika ir taisyklės“ duomenis. Rezultatas priklauso nuo šio veiksmo parametrų.

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

Tapatybės patvirtinimas
Bearer
Prieinama nuo plano
STANDARD
Būtinos teisės
search.analytics:read

Kodo pavyzdžiai

Užklausos pavyzdys

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))

Atsakymo pavyzdys 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"
  }
}

Kaip tai veikia

  • GET /api/v1/search/overview ir /api/v1/search/queries pateikia bendrą statistiką bei sugrupuotas užklausas.
  • Užklausos pasikartojimus gaukite naudodami jos query_hash.
  • Ataskaitų laikotarpiai yra 7, 30 arba 90 dienų, taikant kiekvieno prieigos taško išvardytus filtrus.
  • Paieškos taisyklės susieja frazes su pasirinktais produktais ir kategorijomis; jas galima kurti, skaityti, keisti ir šalinti.
  • Taisyklėms ir analitikai suteikiamos atskiros teisės; teisė skaityti paieškos statistiką nesuteikia prieigos prie konfigūracijos.

Parametrai

Kelio parametrai

query_hashEilutėPrivalomas

Stabilus sugrupuotos paieškos frazės identifikatorius.

Apribojimai
pattern
"^[a-f0-9]{64}$"
Pavyzdys: "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"

Užklausos parametrai

limitSveikasis skaičiusNeprivalomas

Didžiausias įrašų skaičius šiame puslapyje.

minimum: 1maximum: 100
Numatytoji reikšmė: 50Pavyzdys: 20
cursorEilutė nullNeprivalomas

Ankstesnio puslapio grąžinta tęsimo reikšmė; jos vidinės struktūros neinterpretuokite.

Eilutė:minLength: 1maxLength: 1024
daysSveikasis skaičiusNeprivalomas

Ataskaitos laikotarpis dienomis.

Apribojimai
enum
[7, 30, 90]
Numatytoji reikšmė: 30
localeEilutė nullNeprivalomas

Šiai užklausai pasirinkta kalba.

Eilutė:minLength: 2maxLength: 20
Apribojimai · Eilutė 1
pattern
"^[a-z]{2,3}(?:-[A-Za-z0-9]{2,8})*$"
sourceEilutė nullNeprivalomas

Užregistruotos veiklos šaltinis.

Apribojimai · Eilutė 1
enum
["results", "autocomplete"]
market_idEilutė nullNeprivalomas

Konteksto prieigos taško grąžintas rinkos identifikatorius.

Apribojimai · Eilutė 1
pattern
"^[a-z0-9][a-z0-9_-]{0,62}$"

Ši operacija nepriima JSON turinio.

Atsakymai

Atsakymas 200

dataMasyvas <OccurrenceData > Privalomas

Sėkmingo atsakymo duomenys.

Laukai · data

OccurrenceData

category_idEilutė nullPrivalomas

Kategorijos identifikatorius.

category_result_countSveikasis skaičiusPrivalomas

Kategorijų rezultatų skaičius.

currency_codeEilutėPrivalomas

Valiutos kodas.

is_zero_resultsLoginė reikšmėPrivalomas

Ar paieška negrąžino rezultatų.

locale_codeEilutėPrivalomas

Kalbos kodas.

market_idEilutėPrivalomas

Konteksto prieigos taško grąžintas rinkos identifikatorius.

max_priceEilutė nullPrivalomas

Didžiausia nurodyto intervalo kaina.

min_priceEilutė nullPrivalomas

Mažiausia nurodyto intervalo kaina.

occurred_atEilutėPrivalomas

Įvykio data ir laikas.

format: "date-time"
pageSveikasis skaičiusPrivalomas

CMS puslapio informacija.

product_result_countSveikasis skaičiusPrivalomas

Produktų paieškos rezultatų skaičius.

query_displayEilutėPrivalomas

Administratoriui rodoma paieškos frazė.

request_idEilutėPrivalomas

Prašymo identifikatorius; atsakymo metaduomenyse nurodo HTTP užklausą.

resultsMasyvas <ResultSnapshotData > nullPrivalomas

Užregistruoti paieškos rezultatai.

sort_keyEilutėPrivalomas

Rikiavimo raktas.

sourceEilutėPrivalomas

Užregistruotos veiklos šaltinis.

Apribojimai
enum
["results", "autocomplete"]
metaAnalyticsPageMeta AnalyticsMeta Privalomas

Atsakymo metaduomenys.

Laukai · meta

AnalyticsPageMeta

paginationPagination Privalomas

Skaidymo į puslapius pagal žymeklį metaduomenys.

periodAnalyticsPeriodData Privalomas

Ataskaitos laikotarpis ir jo ribos.

request_idEilutėPrivalomas

Prašymo identifikatorius; atsakymo metaduomenyse nurodo HTTP užklausą.

minLength: 1maxLength: 100

AnalyticsMeta

periodAnalyticsPeriodData Privalomas

Ataskaitos laikotarpis ir jo ribos.

request_idEilutėPrivalomas

Prašymo identifikatorius; atsakymo metaduomenyse nurodo HTTP užklausą.

minLength: 1maxLength: 100
Atsakymo pavyzdys

HTTP būsena

200
Sėkmingas atsakymas Schema
400
Netinkama užklausa
401
Būtinas tapatybės patvirtinimas
403
Prieiga uždrausta
404
Išteklius nerastas
409
Versijų konfliktas
422
Tikrinimo klaida
429
Viršytas užklausų limitas
Kitos HTTP būsenos (7)
405
Metodas neleidžiamas
413
Užklausa per didelė
415
Nepalaikomas formatas
500
Serverio klaida
502
API tinklų sietuvo klaida
503
Paslauga nepasiekiama
504
Baigėsi laukimo laikas

Klaidų katalogas: ErrorResponse

Antraštės

401

WWW-AuthenticateEilutėNeprivalomas

Serverio reikalaujama tapatybės patvirtinimo schema.

405

AllowEilutėNeprivalomas

Šio ištekliaus palaikomi HTTP metodai.

429, 503

Retry-AfterSveikasis skaičiusNeprivalomas

Mažiausias laukimo laikas prieš kartojant, sekundėmis.

minimum: 0