コンテンツにスキップ
ShopentlyLearn

取得 · 検索クエリ — 検索分析とルール

「検索分析とルール」のデータを取得します。結果はこの操作のパラメーターによって決まります。

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

認証
Bearer
利用可能な最低プラン
STANDARD
必要な権限
search.analytics:read

コード例

リクエスト例

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

レスポンス例 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"
  }
}

仕組み

  • GET /api/v1/search/overview と /api/v1/search/queries は集計統計とグループ化された検索語を返します。
  • 個別の発生記録には query_hash を使います。
  • 集計期間は7、30、90日に対応し、フィルターは各エンドポイントに記載しています。
  • 検索ルールは語句を選択した商品やカテゴリーに関連付け、作成、取得、更新、削除できます。
  • ルールと分析の権限は別です。
  • 検索統計の閲覧権限だけでは設定を変更できません。

パラメーター

パスパラメーター

query_hash文字列必須

グループ化された検索語句の安定した識別子。

制約
pattern
"^[a-f0-9]{64}$"
例: "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"

クエリパラメーター

limit整数任意

このページの最大レコード数。

minimum: 1maximum: 100
既定値: 50例: 20
cursor文字列 null任意

前のページが返した、内部を解釈しない継続値。

文字列:minLength: 1maxLength: 1024
days整数任意

集計期間の日数。

制約
enum
[7, 30, 90]
既定値: 30
locale文字列 null任意

このリクエストで選択した言語。

文字列:minLength: 2maxLength: 20
制約 · 文字列 1
pattern
"^[a-z]{2,3}(?:-[A-Za-z0-9]{2,8})*$"
source文字列 null任意

記録された活動の発生元。

制約 · 文字列 1
enum
["results", "autocomplete"]
market_id文字列 null任意

コンテキストエンドポイントが返した市場識別子。

制約 · 文字列 1
pattern
"^[a-z0-9][a-z0-9_-]{0,62}$"

この操作は JSON 本文を受け付けません。

レスポンス

レスポンス 200

data配列 <OccurrenceData > 必須

成功レスポンスのデータ。

フィールド · data

OccurrenceData

category_id文字列 null必須

カテゴリー識別子。

category_result_count整数必須

カテゴリーの結果数。

currency_code文字列必須

通貨コード。

is_zero_results真偽値必須

検索結果が0件だったかどうか。

locale_code文字列必須

言語コード。

market_id文字列必須

コンテキストエンドポイントが返した市場識別子。

max_price文字列 null必須

報告範囲の最高価格。

min_price文字列 null必須

報告範囲の最低価格。

occurred_at文字列必須

イベントの発生日時。

format: "date-time"
page整数必須

CMS ページ情報。

product_result_count整数必須

商品の検索結果数。

query_display文字列必須

管理者に表示する検索語句。

request_id文字列必須

申請識別子。レスポンスのメタデータでは HTTP リクエストを識別します。

results配列 <ResultSnapshotData > null必須

記録された検索結果。

sort_key文字列必須

並べ替えキー。

source文字列必須

記録された活動の発生元。

制約
enum
["results", "autocomplete"]
metaAnalyticsPageMeta AnalyticsMeta 必須

レスポンスのメタデータ。

フィールド · meta

AnalyticsPageMeta

paginationPagination 必須

カーソルによるページ分割のメタデータ。

periodAnalyticsPeriodData 必須

集計期間とその開始・終了。

request_id文字列必須

申請識別子。レスポンスのメタデータでは HTTP リクエストを識別します。

minLength: 1maxLength: 100

AnalyticsMeta

periodAnalyticsPeriodData 必須

集計期間とその開始・終了。

request_id文字列必須

申請識別子。レスポンスのメタデータでは HTTP リクエストを識別します。

minLength: 1maxLength: 100
レスポンス例

HTTP ステータス

200
成功 スキーマ
400
無効なリクエスト
401
認証が必要です
403
権限がありません
404
リソースが見つかりません
409
バージョンの競合
422
検証エラー
429
リクエスト上限を超過
その他の HTTP ステータス (7)
405
許可されていないメソッド
413
リクエストが大きすぎます
415
未対応の形式
500
サーバーエラー
502
API ゲートウェイエラー
503
サービスを利用できません
504
タイムアウト

エラー一覧: ErrorResponse

ヘッダー

401

WWW-Authenticate文字列任意

サーバーが要求する認証方式。

405

Allow文字列任意

このリソースが対応する HTTP メソッド。

429, 503

Retry-After整数任意

再試行までに最低限待つ秒数。

minimum: 0