Treci la conținut
ShopentlyLearn

Listează · Interogări — Analize și reguli de căutare

Citiți datele din „Analize și reguli de căutare”. Rezultatul depinde de parametrii acestei operațiuni.

GET/api/v1/search/queries

Autentificare
Bearer
Disponibil începând cu
STANDARD
Permisiuni necesare
search.analytics:read

Exemple de cod

Exemplu de cerere

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

Exemplu de răspuns 200

JSON
{
  "data": [
    {
      "clicks": 1,
      "last_seen_at": "2026-01-01T12:00:00Z",
      "query_display": "example",
      "query_hash": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
      "searches": 1,
      "zero_results": 1
    }
  ],
  "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"
  }
}

Cum funcționează

  • GET /api/v1/search/overview și /api/v1/search/queries expun statistici de sinteză și interogări grupate.
  • Obțineți aparițiile unei interogări folosind query_hash.
  • Perioadele de raportare acceptă 7, 30 sau 90 de zile, cu filtrele prezentate pentru fiecare endpoint.
  • Regulile de căutare leagă expresii de produse și categorii selectate și pot fi create, citite, actualizate sau șterse.
  • Regulile și analizele au permisiuni separate; citirea statisticilor nu acordă acces la configurare.

Parametri

Parametri de interogare

limitNumăr întregOpțional

Numărul maxim de înregistrări pe această pagină.

minimum: 1maximum: 100
Valoare implicită: 50Exemplu: 20
cursorȘir de caractere nullOpțional

Valoare opacă de continuare returnată de pagina anterioară.

Șir de caractere:minLength: 1maxLength: 1024
daysNumăr întregOpțional

Perioada de raportare în zile.

Restricții
enum
[7, 30, 90]
Valoare implicită: 30
localeȘir de caractere nullOpțional

Limba selectată pentru această cerere.

Șir de caractere:minLength: 2maxLength: 20
Restricții · Șir de caractere 1
pattern
"^[a-z]{2,3}(?:-[A-Za-z0-9]{2,8})*$"
sourceȘir de caractere nullOpțional

Sursa activității înregistrate.

Restricții · Șir de caractere 1
enum
["results", "autocomplete"]
market_idȘir de caractere nullOpțional

Identificatorul pieței returnat de endpointul de context.

Restricții · Șir de caractere 1
pattern
"^[a-z0-9][a-z0-9_-]{0,62}$"
queryȘir de caractereOpțional

Textul căutării sau un filtru pentru acesta.

maxLength: 255
Valoare implicită: ""
searches_minNumăr întreg nullOpțional

Filtru pentru numărul minim de căutări.

Număr întreg:minimum: 0maximum: 9223372036854775807
searches_maxNumăr întreg nullOpțional

Filtru pentru numărul maxim de căutări.

Număr întreg:minimum: 0maximum: 9223372036854775807
clicks_minNumăr întreg nullOpțional

Filtru pentru numărul minim de clicuri.

Număr întreg:minimum: 0maximum: 9223372036854775807
clicks_maxNumăr întreg nullOpțional

Filtru pentru numărul maxim de clicuri.

Număr întreg:minimum: 0maximum: 9223372036854775807
zero_results_minNumăr întreg nullOpțional

Filtru pentru numărul minim de căutări fără rezultate.

Număr întreg:minimum: 0maximum: 9223372036854775807
zero_results_maxNumăr întreg nullOpțional

Filtru pentru numărul maxim de căutări fără rezultate.

Număr întreg:minimum: 0maximum: 9223372036854775807
zero_result_scopeZeroResultScope Opțional

Filtru pentru selectarea căutărilor cu sau fără apariții fără rezultate.

Valoare implicită: "all"
sortQueryMetricSort Opțional

Ordinea de sortare selectată pentru rezultate.

Valoare implicită: "last_seen_desc"

Această operație nu acceptă un corp JSON.

Răspunsuri

Răspuns 200

dataTablou <MetricData > Obligatoriu

Datele unui răspuns reușit.

Câmpuri · data

MetricData

clicksNumăr întregObligatoriu

Numărul de clicuri.

last_seen_atȘir de caractereObligatoriu

Momentul celei mai recente apariții.

format: "date-time"
query_displayȘir de caractereObligatoriu

Expresia de căutare afișată administratorului.

query_hashȘir de caractereObligatoriu

Identificatorul stabil al expresiei de căutare grupate.

searchesNumăr întregObligatoriu

Numărul căutărilor.

zero_resultsNumăr întregObligatoriu

Numărul căutărilor fără rezultate.

metaAnalyticsPageMeta AnalyticsMeta Obligatoriu

Metadatele răspunsului.

Câmpuri · meta

AnalyticsPageMeta

paginationPagination Obligatoriu

Metadatele paginării prin cursor.

periodAnalyticsPeriodData Obligatoriu

Perioada de raportare și limitele acesteia.

request_idȘir de caractereObligatoriu

Identificatorul solicitării; în metadatele răspunsului identifică cererea HTTP.

minLength: 1maxLength: 100

AnalyticsMeta

periodAnalyticsPeriodData Obligatoriu

Perioada de raportare și limitele acesteia.

request_idȘir de caractereObligatoriu

Identificatorul solicitării; în metadatele răspunsului identifică cererea HTTP.

minLength: 1maxLength: 100
Exemplu de răspuns

Stare HTTP

200
Răspuns reușit Schemă
400
Cerere nevalidă
401
Autentificare necesară
403
Acces refuzat
404
Resursa nu a fost găsită
409
Conflict de versiune
422
Validare eșuată
429
Limită de cereri depășită
Alte stări HTTP (7)
405
Metodă nepermisă
413
Cerere prea mare
415
Format neacceptat
500
Eroare de server
502
Eroare de gateway API
503
Serviciu indisponibil
504
Timp de așteptare depășit

Catalog de erori: ErrorResponse

Antete

401

WWW-AuthenticateȘir de caractereOpțional

Schema de autentificare cerută de server.

405

AllowȘir de caractereOpțional

Metodele HTTP acceptate de această resursă.

429, 503

Retry-AfterNumăr întregOpțional

Întârzierea minimă înainte de reîncercare, în secunde.

minimum: 0