Pāriet uz saturu
ShopentlyLearn

Saraksts · Meklēšanas vaicājumi — Meklēšanas analītika un noteikumi

Nolasiet datus no “Meklēšanas analītika un noteikumi”. Rezultāts ir atkarīgs no šīs darbības parametriem.

GET/api/v1/search/queries

Autentifikācija
Bearer
Pieejams no
STANDARD
Nepieciešamās atļaujas
search.analytics:read

Koda piemēri

Pieprasījuma piemērs

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

Atbildes piemērs 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"
  }
}

Kā tas darbojas

  • GET /api/v1/search/overview un /api/v1/search/queries sniedz kopsavilkuma statistiku un grupētus vaicājumus.
  • Vaicājuma atsevišķās reizes iegūstiet pēc query_hash.
  • Pārskata periods var būt 7, 30 vai 90 dienas; katrs galapunkts norāda pieejamos filtrus.
  • Meklēšanas noteikumi saista frāzes ar izvēlētiem produktiem un kategorijām; tos var izveidot, lasīt, atjaunināt vai dzēst.
  • Noteikumiem un analītikai ir atsevišķas atļaujas; statistikas lasīšana nedod piekļuvi konfigurācijai.

Parametri

Vaicājuma parametri

limitVesels skaitlisNeobligāts

Maksimālais ierakstu skaits šajā lapā.

minimum: 1maximum: 100
Noklusējums: 50Piemērs: 20
cursorVirkne nullNeobligāts

Iepriekšējās lapas atgriezta neinterpretējama turpinājuma vērtība.

Virkne:minLength: 1maxLength: 1024
daysVesels skaitlisNeobligāts

Pārskata periods dienās.

Ierobežojumi
enum
[7, 30, 90]
Noklusējums: 30
localeVirkne nullNeobligāts

Šim pieprasījumam izvēlētā valoda.

Virkne:minLength: 2maxLength: 20
Ierobežojumi · Virkne 1
pattern
"^[a-z]{2,3}(?:-[A-Za-z0-9]{2,8})*$"
sourceVirkne nullNeobligāts

Reģistrētās aktivitātes avots.

Ierobežojumi · Virkne 1
enum
["results", "autocomplete"]
market_idVirkne nullNeobligāts

Konteksta galapunkta atgrieztais tirgus identifikators.

Ierobežojumi · Virkne 1
pattern
"^[a-z0-9][a-z0-9_-]{0,62}$"
queryVirkneNeobligāts

Meklēšanas teksts vai meklēšanas teksta filtrs.

maxLength: 255
Noklusējums: ""
searches_minVesels skaitlis nullNeobligāts

Minimālā meklējumu skaita filtrs.

Vesels skaitlis:minimum: 0maximum: 9223372036854775807
searches_maxVesels skaitlis nullNeobligāts

Maksimālā meklējumu skaita filtrs.

Vesels skaitlis:minimum: 0maximum: 9223372036854775807
clicks_minVesels skaitlis nullNeobligāts

Minimālā klikšķu skaita filtrs.

Vesels skaitlis:minimum: 0maximum: 9223372036854775807
clicks_maxVesels skaitlis nullNeobligāts

Maksimālā klikšķu skaita filtrs.

Vesels skaitlis:minimum: 0maximum: 9223372036854775807
zero_results_minVesels skaitlis nullNeobligāts

Minimālā bezrezultātu meklējumu skaita filtrs.

Vesels skaitlis:minimum: 0maximum: 9223372036854775807
zero_results_maxVesels skaitlis nullNeobligāts

Maksimālā bezrezultātu meklējumu skaita filtrs.

Vesels skaitlis:minimum: 0maximum: 9223372036854775807
zero_result_scopeZeroResultScope Neobligāts

Filtrs meklējumiem ar vai bez rezultātus neatgriezušām reizēm.

Noklusējums: "all"
sortQueryMetricSort Neobligāts

Rezultātiem izvēlētā kārtošanas secība.

Noklusējums: "last_seen_desc"

Šī darbība nepieņem JSON saturu.

Atbildes

Atbilde 200

dataMasīvs <MetricData > Obligāts

Veiksmīgas atbildes dati.

Lauki · data

MetricData

clicksVesels skaitlisObligāts

Klikšķu skaits.

last_seen_atVirkneObligāts

Pēdējās reizes laiks.

format: "date-time"
query_displayVirkneObligāts

Administratoram parādītā meklēšanas frāze.

query_hashVirkneObligāts

Grupētās meklēšanas frāzes stabils identifikators.

searchesVesels skaitlisObligāts

Meklējumu skaits.

zero_resultsVesels skaitlisObligāts

Meklējumu bez rezultātiem skaits.

metaAnalyticsPageMeta AnalyticsMeta Obligāts

Atbildes metadati.

Lauki · meta

AnalyticsPageMeta

paginationPagination Obligāts

Kursora lapošanas metadati.

periodAnalyticsPeriodData Obligāts

Pārskata periods un tā robežas.

request_idVirkneObligāts

Pieteikuma identifikators; atbildes metadatos tas identificē HTTP pieprasījumu.

minLength: 1maxLength: 100

AnalyticsMeta

periodAnalyticsPeriodData Obligāts

Pārskata periods un tā robežas.

request_idVirkneObligāts

Pieteikuma identifikators; atbildes metadatos tas identificē HTTP pieprasījumu.

minLength: 1maxLength: 100
Atbildes piemērs

HTTP statuss

200
Veiksmīga atbilde Shēma
400
Nederīgs pieprasījums
401
Nepieciešama autentifikācija
403
Piekļuve liegta
404
Resurss nav atrasts
409
Versiju konflikts
422
Validācijas kļūda
429
Pārsniegts pieprasījumu limits
Citi HTTP statusi (7)
405
Metode nav atļauta
413
Pieprasījums ir pārāk liels
415
Neatbalstīts formāts
500
Servera kļūda
502
API vārtejas kļūda
503
Pakalpojums nav pieejams
504
Noildze

Kļūdu katalogs: ErrorResponse

Galvenes

401

WWW-AuthenticateVirkneNeobligāts

Servera pieprasītā autentifikācijas shēma.

405

AllowVirkneNeobligāts

Šī resursa atbalstītās HTTP metodes.

429, 503

Retry-AfterVesels skaitlisNeobligāts

Minimālā aizkave pirms atkārtošanas sekundēs.

minimum: 0