Léim ar ábhar
ShopentlyLearn

Liostaigh · Iarratais chuardaigh — Anailísíocht agus rialacha cuardaigh

Léigh sonraí ó “Anailísíocht agus rialacha cuardaigh”. Braitheann an toradh ar pharaiméadair na hoibríochta seo.

GET/api/v1/search/queries

Fíordheimhniú
Bearer
Ar fáil ó
STANDARD
Ceadanna riachtanacha
search.analytics:read

Samplaí cóid

Sampla iarratais

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

Sampla freagra 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"
  }
}

Conas a oibríonn sé

  • Soláthraíonn GET /api/v1/search/overview agus /api/v1/search/queries staitisticí achoimre agus fiosrúcháin ghrúpáilte.
  • Faigh na teagmhais aonair le query_hash.
  • Tacaítear le tréimhsí 7, 30 nó 90 lá agus na scagairí a liostaítear do gach críochphointe.
  • Ceanglaíonn rialacha frásaí le táirgí agus catagóirí roghnaithe; is féidir iad a chruthú, a léamh, a nuashonrú nó a scriosadh.
  • Tá ceadanna ar leith ag rialacha agus anailísíocht; ní thugann léamh staitisticí cead cumraíochta.

Paraiméadair

Paraiméadair fhiosrúcháin

limitSlánuimhirRoghnach

Uaslíon taifead ar an leathanach seo.

minimum: 1maximum: 100
Réamhshocrú: 50Sampla: 20
cursorTeaghrán nullRoghnach

Luach leanúna neamhléirmhínithe a tháinig ón leathanach roimhe.

Teaghrán:minLength: 1maxLength: 1024
daysSlánuimhirRoghnach

Tréimhse tuairiscithe i laethanta.

Srianta
enum
[7, 30, 90]
Réamhshocrú: 30
localeTeaghrán nullRoghnach

Teanga roghnaithe don iarratas seo.

Teaghrán:minLength: 2maxLength: 20
Srianta · Teaghrán 1
pattern
"^[a-z]{2,3}(?:-[A-Za-z0-9]{2,8})*$"
sourceTeaghrán nullRoghnach

Foinse na gníomhaíochta taifeadta.

Srianta · Teaghrán 1
enum
["results", "autocomplete"]
market_idTeaghrán nullRoghnach

Aitheantóir margaidh a thugann an críochphointe comhthéacs.

Srianta · Teaghrán 1
pattern
"^[a-z0-9][a-z0-9_-]{0,62}$"
queryTeaghránRoghnach

Téacs cuardaigh nó scagaire téacs cuardaigh.

maxLength: 255
Réamhshocrú: ""
searches_minSlánuimhir nullRoghnach

Scagaire don íoslíon cuardach.

Slánuimhir:minimum: 0maximum: 9223372036854775807
searches_maxSlánuimhir nullRoghnach

Scagaire don uaslíon cuardach.

Slánuimhir:minimum: 0maximum: 9223372036854775807
clicks_minSlánuimhir nullRoghnach

Scagaire don íoslíon cliceálacha.

Slánuimhir:minimum: 0maximum: 9223372036854775807
clicks_maxSlánuimhir nullRoghnach

Scagaire don uaslíon cliceálacha.

Slánuimhir:minimum: 0maximum: 9223372036854775807
zero_results_minSlánuimhir nullRoghnach

Scagaire don íoslíon cuardach gan toradh.

Slánuimhir:minimum: 0maximum: 9223372036854775807
zero_results_maxSlánuimhir nullRoghnach

Scagaire don uaslíon cuardach gan toradh.

Slánuimhir:minimum: 0maximum: 9223372036854775807
zero_result_scopeZeroResultScope Roghnach

Scagaire a roghnaíonn cuardaigh le teagmhais gan toradh nó gan iad.

Réamhshocrú: "all"
sortQueryMetricSort Roghnach

Ord sórtála roghnaithe do na torthaí.

Réamhshocrú: "last_seen_desc"

Ní ghlacann an oibríocht seo le corp JSON.

Freagraí

Freagra 200

dataEagar <MetricData > Riachtanach

Sonraí freagra rathúil.

Réimsí · data

MetricData

clicksSlánuimhirRiachtanach

Líon na gcliceálacha.

last_seen_atTeaghránRiachtanach

Am an teagmhais is déanaí.

format: "date-time"
query_displayTeaghránRiachtanach

Frása cuardaigh a thaispeántar don riarthóir.

query_hashTeaghránRiachtanach

Aitheantóir cobhsaí an fhrása cuardaigh ghrúpáilte.

searchesSlánuimhirRiachtanach

Líon cuardach.

zero_resultsSlánuimhirRiachtanach

Líon cuardach gan toradh.

metaAnalyticsPageMeta AnalyticsMeta Riachtanach

Meiteashonraí an fhreagra.

Réimsí · meta

AnalyticsPageMeta

paginationPagination Riachtanach

Meiteashonraí leathanaithe le cúrsóir.

periodAnalyticsPeriodData Riachtanach

Tréimhse tuairiscithe agus a teorainneacha.

request_idTeaghránRiachtanach

Aitheantóir iarratais; i meiteashonraí freagra aithníonn sé an t-iarratas HTTP.

minLength: 1maxLength: 100

AnalyticsMeta

periodAnalyticsPeriodData Riachtanach

Tréimhse tuairiscithe agus a teorainneacha.

request_idTeaghránRiachtanach

Aitheantóir iarratais; i meiteashonraí freagra aithníonn sé an t-iarratas HTTP.

minLength: 1maxLength: 100
Sampla freagra

Stádas HTTP

200
Freagra rathúil Scéim
400
Iarratas neamhbhailí
401
Fíordheimhniú riachtanach
403
Cead diúltaithe
404
Acmhainn gan aimsiú
409
Coinbhleacht leagain
422
Theip ar bhailíochtú
429
Teorainn iarratas sáraithe
Stádais HTTP eile (7)
405
Modh neamhcheadaithe
413
Iarratas rómhór
415
Formáid gan tacaíocht
500
Earráid freastalaí
502
Earráid gheata API
503
Seirbhís gan fáil
504
Teorainn ama sáraithe

Catalóg earráidí: ErrorResponse

Ceanntásca

401

WWW-AuthenticateTeaghránRoghnach

An scéim fíordheimhnithe a éilíonn an freastalaí.

405

AllowTeaghránRoghnach

Modhanna HTTP a thacaíonn an acmhainn seo leo.

429, 503

Retry-AfterSlánuimhirRoghnach

An mhoill íosta roimh atriail, i soicindí.

minimum: 0