Preskoči na sadržaj
ShopentlyLearn

Dohvati · Upiti za pretraživanje — Analitika i pravila pretraživanja

Pročitajte podatke iz „Analitika i pravila pretraživanja“. Rezultat ovisi o parametrima ove radnje.

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

Autentifikacija
Bearer
Dostupno od
STANDARD
Potrebne ovlasti
search.analytics:read

Primjeri koda

Primjer zahtjeva

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

Primjer odgovora 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"
  }
}

Kako funkcionira

  • GET /api/v1/search/overview i /api/v1/search/queries izlažu sažetke statistika i grupirane upite.
  • Pojavljivanja upita dohvatite pomoću njegova query_hash.
  • Podržana su razdoblja od 7, 30 ili 90 dana uz filtre navedene za svaku krajnju točku.
  • Pravila pretraživanja povezuju fraze s odabranim proizvodima i kategorijama te se mogu izrađivati, čitati, ažurirati ili brisati.
  • Pravila i analitika imaju zasebne ovlasti; čitanje statistika ne daje pristup konfiguraciji.

Parametri

Parametri putanje

query_hashNiz znakovaObvezno

Stabilan identifikator grupiranog izraza pretraživanja.

Ograničenja
pattern
"^[a-f0-9]{64}$"
Primjer: "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"

Parametri upita

limitCijeli brojNeobavezno

Najveći broj zapisa na ovoj stranici.

minimum: 1maximum: 100
Zadano: 50Primjer: 20
cursorNiz znakova nullNeobavezno

Neprozirna vrijednost za nastavak koju je vratila prethodna stranica.

Niz znakova:minLength: 1maxLength: 1024
daysCijeli brojNeobavezno

Razdoblje izvješća u danima.

Ograničenja
enum
[7, 30, 90]
Zadano: 30
localeNiz znakova nullNeobavezno

Jezik odabran za ovaj zahtjev.

Niz znakova:minLength: 2maxLength: 20
Ograničenja · Niz znakova 1
pattern
"^[a-z]{2,3}(?:-[A-Za-z0-9]{2,8})*$"
sourceNiz znakova nullNeobavezno

Izvor zabilježene aktivnosti.

Ograničenja · Niz znakova 1
enum
["results", "autocomplete"]
market_idNiz znakova nullNeobavezno

Identifikator tržišta vraćen s krajnje točke konteksta.

Ograničenja · Niz znakova 1
pattern
"^[a-z0-9][a-z0-9_-]{0,62}$"

Ova operacija ne prihvaća JSON tijelo.

Odgovori

Odgovor 200

dataPolje vrijednosti <OccurrenceData > Obvezno

Podaci uspješnog odgovora.

Polja · data

OccurrenceData

category_idNiz znakova nullObvezno

Identifikator kategorije.

category_result_countCijeli brojObvezno

Broj rezultata kategorija.

currency_codeNiz znakovaObvezno

Kod valute.

is_zero_resultsLogička vrijednostObvezno

Je li pretraživanje završilo bez rezultata.

locale_codeNiz znakovaObvezno

Kod jezika.

market_idNiz znakovaObvezno

Identifikator tržišta vraćen s krajnje točke konteksta.

max_priceNiz znakova nullObvezno

Najviša cijena u navedenom rasponu.

min_priceNiz znakova nullObvezno

Najniža cijena u navedenom rasponu.

occurred_atNiz znakovaObvezno

Datum i vrijeme događaja.

format: "date-time"
pageCijeli brojObvezno

Podaci CMS stranice.

product_result_countCijeli brojObvezno

Broj rezultata pretraživanja proizvoda.

query_displayNiz znakovaObvezno

Izraz pretraživanja prikazan administratoru.

request_idNiz znakovaObvezno

Identifikator zahtjeva; u metapodacima odgovora označava HTTP zahtjev.

resultsPolje vrijednosti <ResultSnapshotData > nullObvezno

Zabilježeni rezultati pretraživanja.

sort_keyNiz znakovaObvezno

Ključ poretka.

sourceNiz znakovaObvezno

Izvor zabilježene aktivnosti.

Ograničenja
enum
["results", "autocomplete"]
metaAnalyticsPageMeta AnalyticsMeta Obvezno

Metapodaci odgovora.

Polja · meta

AnalyticsPageMeta

paginationPagination Obvezno

Metapodaci straničenja pomoću kursora.

periodAnalyticsPeriodData Obvezno

Razdoblje izvješća i njegove granice.

request_idNiz znakovaObvezno

Identifikator zahtjeva; u metapodacima odgovora označava HTTP zahtjev.

minLength: 1maxLength: 100

AnalyticsMeta

periodAnalyticsPeriodData Obvezno

Razdoblje izvješća i njegove granice.

request_idNiz znakovaObvezno

Identifikator zahtjeva; u metapodacima odgovora označava HTTP zahtjev.

minLength: 1maxLength: 100
Primjer odgovora

HTTP status

200
Uspješan odgovor Shema
400
Nevaljan zahtjev
401
Potrebna je autentikacija
403
Pristup odbijen
404
Resurs nije pronađen
409
Sukob verzija
422
Provjera nije uspjela
429
Prekoračeno ograničenje zahtjeva
Ostali HTTP statusi (7)
405
Metoda nije dopuštena
413
Zahtjev je prevelik
415
Nepodržan format
500
Pogreška poslužitelja
502
Pogreška API pristupnika
503
Usluga nije dostupna
504
Istek vremena

Katalog pogrešaka: ErrorResponse

Zaglavlja

401

WWW-AuthenticateNiz znakovaNeobavezno

Shema autentifikacije koju zahtijeva poslužitelj.

405

AllowNiz znakovaNeobavezno

HTTP metode koje ovaj resurs podržava.

429, 503

Retry-AfterCijeli brojNeobavezno

Najkraće čekanje prije ponavljanja, u sekundama.

minimum: 0