audience-snapshot

オーディエンスの概要

目的

オーディエンスセグメントの分析ビューを提供します。このセグメントに含まれる人々の特徴を確認できます。フィールド値の分布、カバレッジ率、数値統計を表示し、注目すべきパターンを明らかにします。読み取り専用の操作です。

環境

認証済みの API アクセスが必要です。認証情報の解決方法については、../references/auth.md を参照してください。

入力

• セグメント名または ID（必須）
• 分析する特定のフィールド（任意。デフォルトではすべてのフィールド）
• テーブル（任意。デフォルトでは user）

API エンドポイント

ID によるセグメントフィールド情報

重要：このエンドポイントには、スラッグ名ではなくセグメントの id ハッシュ（例：a1b2c3d4e5f6）が必要です。スラッグを使用すると HTTP 500 が返されます。必ず先に GET /v2/segment でセグメント ID を解決してください。

curl -s "${LYTICS_API_URL:-https://api.lytics.io}/api/segment/${SEGMENT_ID}/fieldinfo?limit=20&table=user" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

複数のセグメントのフィールド情報

curl -s "${LYTICS_API_URL:-https://api.lytics.io}/api/segment/fieldinfo?ids=${ID1},${ID2}&limit=20&table=user" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

クエリパラメーター

パラメーター	デフォルト	最大値	説明
fields	all	-	返す特定のフィールドをカンマ区切りで指定
limit	20	1000	フィールドごとの用語値の数
table	user	-	エンティティテーブル名
cached	true	-	キャッシュ済みの結果を使用します。最新のデータを取得するには false を設定します

レスポンス形式

レスポンスには標準の API エンベロープが使用されます。fieldinfo データは data.segments 内にあります。

{
  "data": {
    "segments": [
      {
        "id": "segment_id",
        "fields": [
          {
            "field": "country",
            "terms_counts": {"US": 5000, "CA": 2000, "UK": 1500},
            "more_terms": false,
            "ents_present": 8500,
            "ents_absent": 1500,
            "approx_cardinality": 45,
            "last_updated": "2026-03-18T12:00:00Z"
          },
          {
            "field": "visit_count",
            "terms_counts": null,
            "ents_present": 9800,
            "ents_absent": 200,
            "approx_cardinality": 350,
            "stats": {"mean": 12.5, "sd": 8.3, "min": 1.0, "max": 150.0, "n": 9800},
            "histograms": [{"data": {"0-10": 4500, "10-20": 3200, "20-50": 1800, "50+": 300}}],
            "last_updated": "2026-03-18T12:00:00Z"
          }
        ]
      }
    ]
  },
  "message": "success",
  "status": 200
}

フィールドを順に処理するには、jq '.data.segments[].fields[]' で解析します。

フィールドごとのレスポンスキー：

キー	型	説明
field	string	フィールド名
terms_counts	object	上位の値と件数（カテゴリーフィールド）
more_terms	bool	制限を超える値が存在するかどうか
ents_present	int	このフィールドに値が設定されているプロファイル数
ents_absent	int	このフィールドが欠落しているプロファイル数
approx_cardinality	int	値の推定ユニーク数
stats	object or null	数値フィールドのみ：平均、標準偏差、最小値、最大値、件数
histograms	array or null	数値／日付フィールド：バケット化された分布
last_updated	timestamp	フィールド情報の最終計算日時

動作

ステップ 1：セグメント ID を解決する

fieldinfo エンドポイントにはセグメントの id ハッシュが必要です。スラッグ名を指定すると HTTP 500 が返されます。必ず先に解決してください。

curl -s "${LYTICS_API_URL:-https://api.lytics.io}/v2/segment?table=user&sizes=true" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

名前または slug_name で一致するセグメントを見つけ、その id フィールド（16 進数のハッシュ）と現在のサイズを取得します。

ステップ 2：フィールド情報を取得する

curl -s "${LYTICS_API_URL:-https://api.lytics.io}/api/segment/${SEGMENT_ID}/fieldinfo?limit=20&table=user" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

ユーザーが特定のフィールドを指定した場合は、&fields=field1,field2,field3 を追加します。 特定のフィールドをさらに詳しく分析するには、制限値を増やします：&limit=100。

ステップ 3：オーディエンスの概要を提示する

結果を読みやすい要約にまとめます。

## Audience Snapshot: High Value Customers
**Size**: 10,000 profiles

### Top Demographics
**country** (98% coverage, 45 distinct values)
  US: 5,000 (50%)
  CA: 2,000 (20%)
  UK: 1,500 (15%)
  DE: 800 (8%)
  Other: 700 (7%)

**city** (85% coverage, 1,200 distinct values)
  New York: 800 (8%)
  Toronto: 600 (6%)
  London: 500 (5%)
  ...

### Engagement Metrics
**visit_count** (98% coverage)
  Mean: 12.5 | Std Dev: 8.3
  Min: 1 | Max: 150
  Distribution: 0-10: 46%, 10-20: 33%, 20-50: 18%, 50+: 3%

### Field Coverage
| Field | Coverage | Distinct Values |
|-------|----------|----------------|
| email | 92% | 9,800 |
| country | 98% | 45 |
| city | 85% | 1,200 |
| visit_count | 98% | 350 |
| products_purchased | 67% | 890 |

ステップ 4：注目すべきパターンを明らかにする

興味深い分析結果を示します。

• 優勢な値：「このオーディエンスの 87% は米国にいます」
• カバレッジの高低：「電話番号があるのはわずか 34% です」
• 数値の外れ値：「訪問回数は 1～150 回ですが、79% は 20 回未満です」
• 比較：複数のセグメントを分析する場合は、主な違いを示します

ステップ 5：次のアクションを提案する

概要を提示した後、次のステップを提案します。

• 「特定のフィールドを詳しく掘り下げますか？」
• 「このオーディエンスを別のセグメントと比較しますか？」
• 「確認した内容に基づいて、このオーディエンスをさらに絞り込みますか？」

セグメントの比較

2 つ以上のセグメントを比較する場合は、それぞれの fieldinfo を取得し、並べて提示します。

curl -s "${LYTICS_API_URL:-https://api.lytics.io}/api/segment/fieldinfo?ids=${ID1},${ID2}&limit=20" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

違いを提示します。

### Comparison: High Value vs All Users
| Field | High Value | All Users |
|-------|-----------|-----------|
| Avg visit_count | 12.5 | 4.2 |
| US % | 50% | 35% |
| Email coverage | 92% | 68% |

エラー処理

• セグメントが見つからない：利用可能なセグメントを一覧表示し、名前を確認するよう提案します
• フィールド情報がない：セグメントが新しすぎるか空である可能性があります。まずセグメントのサイズを確認してください
• データが古い：last_updated が古い場合は、cached=false を指定して再取得するよう提案します

依存関係

• 使用するもの：../references/auth.md、../references/api-client.md
• 関連項目：セグメントの検索には segment-manager skill、セグメントの作成には audience-builder skill