構造化データとIntelligence Token

TLDR

Surmado（スルマド）のレポートにはすべて、プログラムから使える構造化JSONが付いています。AI Visibilityのトークンには、可視性の指標と競合のデータが入っています。Site Auditのトークンには、パフォーマンススコアと技術的な問題が入っています。Strategyのトークンには、戦略上の推奨事項と財務モデリングが入っています。Notion、Airtable、Google Sheets、Zapier、独自のツールと連携できます。指標を時系列で追跡し、レポートを自動化し、ダッシュボードを作り、可視性が下がったときにアラートを出せます。

---

REST APIをお探しですか？ プログラムからレポートを作成し、ブランドを管理し、webhookを受信する方法は、API連携ガイドをご覧ください。

Surmadoのレポートにはすべて、プログラムから使える構造化JSONが付いています。

Intelligence Tokenとは？

Intelligence Tokenは、完了したレポートごとの固有の識別子です（例：SIG-2025-11-A7K3Q）。トークンはレポートの完了時にREST APIのレスポンスで返されます。AI VisibilityとSite Auditのレポートでは、トークンによって構造化されたpublic_intelligenceのJSONペイロードが使えるようになり、次のようなものと連携できます。

• ダッシュボード（Notion、Airtable、Retool、独自のReactアプリ）
• 自動化ワークフロー（Zapier、Make、n8n）
• 社内ツール（CRM、プロジェクト管理、BIプラットフォーム）
• 独自のエージェント（AIアシスタント、監視ボット、Slack連携）

入手場所：レポートがcompletedになったら、GET /v1/reports/{report_id}を呼び出してください。AI VisibilityとSite Auditのレスポンスには、厳選した機械可読のフィールドを含むpublic_intelligenceオブジェクトが入っています。Strategyのレポートは、完了時にトークンを返しますが、現在はpublic_intelligenceを公開していません。Strategyの成果物には、生成されたPDFをご利用ください。認証とエンドポイントの詳細は、API連携ガイドをご覧ください。

形式：標準のJSONです。フィールドは今後追加される場合があります。既存のフィールドは安定して保つよう努めます。

AI VisibilityのIntelligence Token

トークンのプレフィックス：SIG-*（APIパスでの製品スラッグ：signal） 目的：AI上の可視性の指標、競合上の位置づけ、Ghost Influenceの測定。

スキーマの構造（AI Visibility）

{
  "token": "SIG-2025-11-A7K3Q",
  "schema_type": "signal",
  "generated_at": "2025-11-08T23:45:12.456789+00:00",
  "summary": {
    "business_name": "Acme Coffee Roasters",
    "industry": "Food & Beverage",
    "location": "Portland, OR",
    "presence_score": 34.2,
    "authority_score": 42.7,
    "competitive_rank": 4,
    "total_competitors": 12,
    "top_competitor": "Blue Bottle",
    "insights_summary": [
      "Presence score: 34.2 (↑5.5 from last report)",
      "Ghost influence: 48.3% of relevant mentions don't name you",
      "Competitive rank: #4 of 12 in category"
    ]
  },
  "data": {
    "entity_context": {
      "entity_name": "Acme Coffee Roasters",
      "category": "Food & Beverage",
      "location": "Portland, OR",
      "value_proposition": "Single-origin, small-batch specialty coffee",
      "competitive_set": ["Starbucks", "Blue Bottle", "Intelligentsia"]
    },
    "visibility_metrics": {
      "presence_score": 34.2,
      "ghost_influence_percentage": 48.3,
      "attributed_mentions": 12,
      "unattributed_mentions": 17,
      "category_share": 8.1
    },
    "competitive_position": {
      "rank": 4,
      "total_competitors": 12,
      "tier": "challenger",
      "top_competitor": "Blue Bottle"
    },
    "platform_variance": {
      "chatgpt": {
        "presence_score": 42.1,
        "attributed_mentions": 5,
        "unattributed_mentions": 7,
        "sample_responses": ["..."]
      },
      "claude": {
        "presence_score": 38.5,
        "attributed_mentions": 3,
        "unattributed_mentions": 4
      },
      "gemini": { "...": "..." },
      "deepseek": { "...": "..." },
      "meta_ai": { "...": "..." },
      "grok": { "...": "..." }
    },
    "perception_analysis": {
      "primary_associations": ["specialty coffee", "local roasting", "sustainable sourcing"],
      "sentiment_distribution": {
        "positive": 67.4,
        "neutral": 28.3,
        "negative": 4.3
      },
      "strength_signals": ["ethical sourcing", "small batch quality"],
      "weakness_signals": ["limited retail presence", "higher price point"]
    },
    "strategic_signals": {
      "visibility_opportunities": [
        {
          "platform": "chatgpt",
          "gap": "Location-based queries underrepresented",
          "recommendation": "Optimize Google Business Profile with neighborhood keywords",
          "estimated_impact": "high"
        }
      ],
      "competitive_threats": [
        {
          "competitor": "Blue Bottle",
          "platform": "claude",
          "advantage": "Brand recognition in 'premium coffee' queries",
          "mitigation": "Emphasize direct trade relationships and roast-date freshness"
        }
      ]
    },
    "evidence_samples": [
      {
        "platform": "chatgpt",
        "query": "best specialty coffee roasters in Portland",
        "response_excerpt": "...",
        "attribution_type": "named",
        "rank": 3
      }
    ],
    "market_context": {
      "industry_trends": ["direct trade transparency", "micro-lot offerings"],
      "seasonal_factors": "Testing conducted during peak holiday gifting season",
      "competitive_intensity": "high",
      "total_competitors_found": 12
    },
    "baseline_metrics": {
      "previous_presence_score": 28.7,
      "change_since_last_report": "+5.5",
      "trend": "improving",
      "authority_score": 42.7
    },
    "preview_content": {
      "tldr_bullets_list": [
        "Presence score: 34.2 (↑5.5 from last report)",
        "Ghost influence: 48.3% of relevant mentions don't name you",
        "Competitive rank: #4 of 12 in category",
        "Strongest platform: ChatGPT (42.1 presence)",
        "Top opportunity: Location-based query optimization"
      ]
    }
  }
}

上部の厳選されたsummaryオブジェクトは、すばやく参照できるようAPIが設定します。より詳しい指標はdata.*にあります。persona_detailsやtest_queriesなどの内部フィールドはブラックリストに入っており、public_intelligenceには表示されません。

主なフィールドの解説（AI Visibility）

summary.presence_score（および data.visibility_metrics.presence_score）：関連するクエリへのAIの回答に、御社のビジネスがどのくらいの頻度で登場するかを示す、0〜100のスコアです。高いほど、よく見えています。

data.visibility_metrics.ghost_influence_percentage：AIが御社の価値提案や特長を、御社の名前を出さずに説明している関連言及の割合です。Ghost Influenceが高い場合、御社が市場に価値を伝えているのに、その評価は競合に取られています。

summary.competitive_rank（および data.competitive_position.rank）：同じカテゴリの競合と比べた順位です。1位が最も多く言及されています。

data.platform_variance：AIプラットフォーム別（ChatGPT、Claude、Geminiなど）の内訳で、どこが最も強く、どこが最も弱いかがわかります。

data.strategic_signals.visibility_opportunities：想定される影響度の順に並べた、実行できる推奨事項です。

よくある使い方（AI Visibility）

ダッシュボード連携：summary.presence_score、data.visibility_metrics.ghost_influence_percentage、summary.competitive_rankを取得して、AI上の可視性を時系列で追跡します。

アラート：data.baseline_metrics.trendを監視し、presence scoreが10ポイントを超えて下がったらアラートを出します。

競合分析：御社のdata.platform_varianceを競合のAI Visibilityレポートと比べて、プラットフォームごとのギャップを見つけます。

コンテンツ戦略：data.perception_analysis.weakness_signalsを、コンテンツ作成とFAQの最適化の指針にします。

---

Site AuditのIntelligence Token

トークンのプレフィックス：SCN-*（APIパスでの製品スラッグ：scan） 目的：技術的なSEO監査データ、パフォーマンス指標、アクセシビリティのスコア、優先順位を付けた対応項目。

スキーマの構造（Site Audit）

{
  "schema_type": "scan",
  "scan_schema_types_count": 3,
  "scan_critical_issues_count": 8,
  "summary": {
    "seo_score": 95,
    "performance_score": 87,
    "accessibility_score": 92,
    "total_pages": 48,
    "schema_types_count": 3,
    "critical_issues_count": 8,
    "content_coverage_percentage": 87,
    "page_analysis_summary": "Homepage LCP is 2.8s (above target). Three pages have thin content.",
    "link_analysis_summary": "Internal link distribution uneven. Two orphaned pages detected.",
    "schema_strategy_summary": "FAQPage and LocalBusiness schemas missing on key pages.",
    "content_gaps_summary": "Competitors rank for brewing method and single-origin guides you don't cover.",
    "quick_wins": {
      "link_analysis": "Add internal links from homepage to two orphaned product pages.",
      "schema_strategy": "Add FAQPage schema to the top 5 traffic pages.",
      "content_gaps": "Publish a brewing-methods comparison guide."
    }
  },
  "data": {
    "metadata": {
      "url": "https://www.example.com",
      "run_id": "scan-20251108-143022",
      "product": "scan",
      "version": "1.0",
      "created_at": "2025-11-08T14:30:22.445Z"
    },
    "audit_data": {
      "site_metrics": {
      "total_pages": 48,
      "crawled_pages": 48,
      "avg_word_count": 1247,
      "pages_with_schema": 42,
      "missing_titles": 0,
      "duplicate_titles": 3,
      "images_without_alt": 15,
      "broken_links": 2,
      "redirect_chains": 1
    },
    "lighthouse": {
      "performance_score": 87,
      "seo_score": 95,
      "accessibility_score": 92,
      "best_practices_score": 88,
      "first_contentful_paint": 1.2,
      "largest_contentful_paint": 2.1,
      "cumulative_layout_shift": 0.05,
      "total_blocking_time": 150
    },
    "accessibility": {
      "pa11y_errors": 8,
      "pa11y_warnings": 23,
      "combined_score": 86,
      "critical_issues": [
        {
          "code": "WCAG2AA.Principle1.Guideline1_3.1_3_1.H49.I",
          "message": "<i> element used for icon, should use aria-label",
          "selector": ".nav-icon",
          "impact": "moderate"
        }
      ]
    },
    "enrichment": {
      "page_analysis": {
        "high_priority_pages": [
          {
            "url": "/",
            "title": "Homepage",
            "recommendations": [
              "Add FAQ schema to address common queries",
              "Optimize hero image LCP (currently 2.8s)"
            ]
          }
        ]
      },
      "link_analysis": {
        "internal_link_distribution": "uneven",
        "orphaned_pages": 2,
        "deep_pages_low_authority": 5
      },
      "schema_strategist": {
        "schemas_found": ["Organization", "WebSite", "BreadcrumbList"],
        "schemas_missing": ["FAQPage", "LocalBusiness"],
        "validation_errors": [
          {
            "type": "Organization",
            "field": "logo",
            "error": "Invalid URL format"
          }
        ]
      },
      "content_inventory": {
        "thin_content_pages": 3,
        "keyword_cannibalization": [
          {
            "keyword": "best coffee beans",
            "competing_pages": ["/shop/beans", "/blog/coffee-guide"],
            "recommendation": "Consolidate or differentiate targeting"
          }
        ]
      },
      "competitor_analysis": {
        "competitors_analyzed": ["bluebottle.com", "intelligentsia.com"],
        "your_advantages": ["Faster load times", "Better mobile UX"],
        "their_advantages": ["more thorough with 150+ checks schema", "Higher blog frequency"]
      },
      "upstream_research": {
        "industry_benchmarks": {
          "avg_performance_score": 72,
          "avg_accessibility_score": 78,
          "your_vs_average": {
            "performance": "+15",
            "accessibility": "+14"
          }
        }
      },
      "content_gap_analysis": {
        "suggested_topics": [
          "Coffee brewing methods comparison",
          "Single-origin vs blend guide",
          "Roast profile differences explained"
        ],
        "rationale": "Competitors rank for these queries but you have no content"
      }
    },
    "pages": [
      {
        "url": "https://www.example.com/",
        "title": "Homepage",
        "status_code": 200,
        "word_count": 1850,
        "meta_description": "...",
        "h1_tags": ["Acme Coffee Roasters"],
        "schema_types": ["Organization", "WebSite"],
        "performance": {
          "lcp": 2.1,
          "cls": 0.05
        },
        "issues": [
          {
            "severity": "medium",
            "type": "image_optimization",
            "message": "Hero image not lazy-loaded",
            "recommendation": "Add loading='lazy' attribute"
          }
        ]
      }
    ]
    }
  }
}

summaryは、お客様が自動化に使う厳選されたまとめです。より詳しいデータはdata.audit_data.*にあります。audit_data.pages[]の配列全体はpublic_intelligenceのレスポンスに含まれますが、長くなります。優先度の高い推奨事項はsummary.quick_winsで取得してください。

主なフィールドの解説（Site Audit）

summary.seo_score（および data.audit_data.site_metrics.seo_score）：技術面とページ内の要素をまとめた、0〜100のSEOスコアです。

summary.performance_score（および data.audit_data.lighthouse.performance_score）：Lighthouseの、0〜100のパフォーマンススコアです。業界平均は、ECサイトで65〜75です。

data.audit_data.site_metrics.images_without_alt：altテキストのない画像の数です（SEOとアクセシビリティの両方の問題です）。

data.audit_data.enrichment.schema_strategist：構造化データのSchema.org検証と推奨事項です。

data.audit_data.enrichment.content_gap_analysis：競合は上位表示されているのに、御社が扱っていないトピックです。SEO上の機会になる領域です。

data.audit_data.pages[].issues：ページごとの詳細な問題で、重大度と実行できる推奨事項が付いています。

summary.quick_wins：分野（link_analysis、schema_strategy、content_gaps）ごとにまとめた、優先順位付きのわかりやすい推奨事項です。

よくある使い方（Site Audit）

CI/CD連携：デプロイのパイプラインでSite Auditを実行し、summary.performance_score < 80ならビルドを失敗させます。

モニタリング：summary.seo_score、summary.performance_score、summary.accessibility_scoreを、時系列データベースで継続的に追跡します。

課題管理：data.audit_data.pages[].issuesを解析し、開発チーム向けのJiraやLinearのチケットを自動で作成します。

レポート作成：summaryオブジェクトを取得して、SEOの健全性を示す経営層向けのダッシュボードに使います。

---

StrategyのIntelligence Token

トークンのプレフィックス：SOL-*（APIパスでの製品スラッグ：solutions） 目的：戦略立案の成果物、優先順位を付けた対応項目、敵対的ディベートの統合結果、意思決定のフレームワーク。

Strategyのレポートは、現在REST API経由ではpublic_intelligenceオブジェクトを公開していません。以下の構造は、生成されるPDFに含まれる内容で、参考として掲載しています。プログラムから利用する場合は、ステータスのエンドポイントが返すPDFのダウンロードURLをご利用ください。

スキーマの構造（Strategy）

{
  "token": "SOL-2025-11-A7K3Q",
  "generated_at": "2025-11-08T23:45:12.456789+00:00",
  "business_name": "Acme Coffee Roasters",
  "decision": "Should we expand from local farmers markets to e-commerce?",
  "todo_list": [
    {
      "priority": 1,
      "action": "Validate e-commerce demand with 2-week pre-order test",
      "rationale": "CFO AI flagged cash flow risk of inventory investment. Test market demand before committing capital.",
      "estimated_effort": "1-3 days",
      "impact": "high",
      "owner_role": "Marketing",
      "dependencies": [],
      "success_criteria": "Achieve 50+ pre-orders to justify inventory investment"
    },
    {
      "priority": 2,
      "action": "Calculate true unit economics including shipping costs",
      "rationale": "Market Realist AI noted competitors use free shipping thresholds. Need to model margin impact.",
      "estimated_effort": "1 day",
      "impact": "high",
      "owner_role": "Finance",
      "dependencies": [],
      "success_criteria": "Confirm >30% margin after shipping at $35+ order value"
    },
    {
      "priority": 3,
      "action": "Research coffee subscription platform integrations (Trade, Driftaway)",
      "rationale": "Game Theorist AI suggested partnering vs competing. Explore white-label options.",
      "estimated_effort": "2-3 days",
      "impact": "medium",
      "owner_role": "Partnerships",
      "dependencies": [],
      "success_criteria": "Identify 2-3 viable platform partnerships with <15% commission"
    },
    {
      "priority": 4,
      "action": "Audit fulfillment capacity: Can we ship 100 orders/week?",
      "rationale": "COO AI raised operational risk of overwhelming current team during peak season.",
      "estimated_effort": "1 day",
      "impact": "high",
      "owner_role": "Operations",
      "dependencies": [],
      "success_criteria": "Document current capacity + identify bottlenecks"
    },
    {
      "priority": 5,
      "action": "Create content strategy for 'coffee education' blog",
      "rationale": "Upstream research showed competitors win on educational content. Build SEO moat.",
      "estimated_effort": "1 week",
      "impact": "medium",
      "owner_role": "Marketing",
      "dependencies": [1],
      "success_criteria": "Publish 3 comprehensive guides (brewing methods, origins, roast profiles)"
    },
    {
      "priority": 6,
      "action": "Build Minimum Viable Storefront (Shopify or WooCommerce)",
      "rationale": "After validating demand (Priority 1), launch simple store. Avoid custom dev.",
      "estimated_effort": "2 weeks",
      "impact": "high",
      "owner_role": "Engineering",
      "dependencies": [1, 2],
      "success_criteria": "Live storefront with 5 SKUs, payment processing, shipping integration"
    },
    {
      "priority": 7,
      "action": "Model customer acquisition cost (CAC) for paid ads",
      "rationale": "CFO AI noted farmers market CAC is $0 (foot traffic). Need to budget for online ads.",
      "estimated_effort": "2-3 days",
      "impact": "medium",
      "owner_role": "Marketing",
      "dependencies": [2],
      "success_criteria": "Target CAC <$25 with LTV >$75 (3x ratio)"
    },
    {
      "priority": 8,
      "action": "Set decision checkpoint: Launch vs pivot based on pre-order results",
      "rationale": "Chief Strategist AI synthesis: Use Priority 1 results to decide go/no-go.",
      "estimated_effort": "1 day",
      "impact": "critical",
      "owner_role": "Leadership",
      "dependencies": [1, 2, 4],
      "success_criteria": "Decision made by [specific date] based on pre-order data"
    }
  ],
  "summary": {
    "total_actions": 8,
    "high_priority": 4,
    "medium_priority": 3,
    "critical_priority": 1,
    "has_financial_analysis": true,
    "has_risk_mitigation": true,
    "estimated_total_effort": "4-6 weeks",
    "decision_framework": "Staged validation approach with clear go/no-go gates"
  },
  "adversarial_debate_summary": {
    "cfo_concerns": [
      "Inventory cash flow risk without demand validation",
      "Shipping costs erode margins below 30% threshold",
      "Customer acquisition cost unknown for paid channels"
    ],
    "coo_concerns": [
      "Current team capacity maxed at 100 orders/week",
      "Peak season overlap with farmers market commitments",
      "Fulfillment process not documented or systemized"
    ],
    "market_realist_concerns": [
      "Competitors offer free shipping (you can't at current scale)",
      "Educational content gap vs established brands",
      "Price positioning unclear (premium vs accessible)"
    ],
    "game_theorist_insights": [
      "Partnering with existing platforms reduces upfront investment",
      "Competitors may respond with farmers market presence if you succeed online",
      "First-mover advantage in 'local + online' hybrid model"
    ],
    "chief_strategist_synthesis": "Launch is feasible but only after validating demand and unit economics. Staged approach reduces risk: (1) Pre-order test, (2) MVP storefront, (3) Scale based on results. Avoid premature inventory investment."
  },
  "monte_carlo_scenarios": {
    "methodology": "10,000 simulations varying demand, CAC, and margin assumptions",
    "outcomes": {
      "success_rate": 62,
      "breakeven_12mo": 62,
      "breakeven_18mo": 28,
      "failure_24mo": 10
    },
    "key_risk_factors": [
      "Customer acquisition cost variance (if CAC >$40, failure risk jumps to 35%)",
      "Shipping cost assumptions (free shipping threshold impacts margin by 12-18%)",
      "Fulfillment bottleneck (unable to scale beyond 100 orders/week without hiring)"
    ],
    "recommendation": "Secure 18-month runway, not 12-month. Model includes 28% of scenarios requiring extended breakeven timeline."
  },
  "evidence_citations": [
    {
      "claim": "Competitors use free shipping thresholds",
      "source": "Analysis of Blue Bottle, Intelligentsia, and Stumptown pricing",
      "data": "Free shipping at $40+, $35+, and $50+ respectively"
    },
    {
      "claim": "Educational content drives SEO for coffee brands",
      "source": "SEMrush analysis of top 10 specialty coffee sites",
      "data": "Average 12 educational blog posts ranking for 'how to brew' queries"
    }
  ]
}

主なフィールドの解説（Strategy）

todo_list[].priority：1が最優先です。順序は、論理的な順番と依存関係を表します。

todo_list[].dependencies：そのアクションが依存する、優先度の番号の配列です。プロジェクト管理での順序づけに使います。

adversarial_debate_summary：各AIの視点（CFO、COO、Market Realist、Game Theorist）が挙げた懸念と、最終的な統合結果を要約したものです。

monte_carlo_scenarios：前提が変わった場合の成功と失敗の確率を示す、確率的ストレステストの結果です。

evidence_citations：主な主張と推奨事項の裏付けとなる出典です。推論の過程を確認できます。

よくある使い方（Strategy）

Strategyのpublic_intelligenceは、現在REST API経由では公開されていません。以下のフィールドはPDFの出力について説明したものです。プログラムから利用する場合は、PDFから抽出するか、元になったAI VisibilityまたはSite Auditのレポートを再実行して、そのpublic_intelligenceを使ってください。

プロジェクト管理：todo_listをLinear、Asana、Notionに取り込めば、優先度と依存関係があらかじめ設定された状態になります。

意思決定の記録：Strategyのトークンを自社の戦略リポジトリに保存して、決定の理由を記録します。

取締役会向けのレポート：summaryとmonte_carlo_scenariosを取得して、戦略がどのようにストレステストされたかを経営陣に示します。

ナレッジ管理：evidence_citationsをインデックス化して、戦略リサーチの知見を組織に蓄積します。

---

Intelligence Tokenの入手方法

REST API経由

主な方法です。レポートのステータスがcompletedになったら、GET /v1/reports/{report_id}を呼び出します。レスポンスにはtokenフィールドが含まれ、AI VisibilityとSite Auditのレポートでは、構造化された指標を持つpublic_intelligenceオブジェクトも含まれます。認証、webhook、エンドポイントの詳細は、API連携ガイドをご覧ください。

メール経由

レポートの準備ができると、PDFを表示するマジックリンクのボタンが付いたメールが届きます。リンクの有効期間は約30日間です。

Surmadoアプリ経由

Reportsを開き、対象のレポートを選ぶと、レポートの詳細画面にトークンとダウンロードリンクが表示されます。

---

Intelligence Tokenのスキーマ

AI VisibilityとSite Auditのpublic_intelligenceペイロードのスキーマは、上記に記載しています。Strategyの成果物はPDFで提供されます。Strategyのレポートでは、構造化されたpublic_intelligenceペイロードは現在REST API経由で公開されていません。

---

連携の例

以下の例ではすべて、GET /v1/reports/{report_id}を使ってREST APIからpublic_intelligenceを取得しています（API連携ガイドをご覧ください）。

Notionのダッシュボード

// Fetch a completed AI Visibility report and create a Notion database entry
const res = await fetch(`https://api.surmado.com/v1/reports/${reportId}`, {
  headers: { 'Authorization': `Bearer ${process.env.SURMADO_API_KEY}` }
});
const report = await res.json();
const signalData = report.public_intelligence;

await notion.pages.create({
  parent: { database_id: 'YOUR_DATABASE_ID' },
  properties: {
    'Business Name': { title: [{ text: { content: signalData.summary.business_name } }] },
    'Presence Score': { number: signalData.summary.presence_score },
    'Competitive Rank': { number: signalData.summary.competitive_rank },
    'Report Date': { date: { start: report.completed_at } },
    'Token': { rich_text: [{ text: { content: report.token } }] }
  }
});

Zapier webhook

// Trigger Zapier workflow when presence score drops
const currentScore = signalData.summary.presence_score;
const previousScore = signalData.data?.baseline_metrics?.previous_presence_score;

if (previousScore && currentScore < previousScore - 10) {
  await fetch('https://hooks.zapier.com/hooks/catch/YOUR_WEBHOOK/', {
    method: 'POST',
    body: JSON.stringify({
      alert: 'Presence score dropped significantly',
      business: signalData.summary.business_name,
      current_score: currentScore,
      previous_score: previousScore,
      drop: previousScore - currentScore
    })
  });
}

Linearの課題作成（Site Audit）

// Fetch a completed Site Audit report and auto-create Linear issues from quick wins
const res = await fetch(`https://api.surmado.com/v1/reports/${reportId}`, {
  headers: { 'Authorization': `Bearer ${process.env.SURMADO_API_KEY}` }
});
const report = await res.json();
const scanData = report.public_intelligence;

for (const [area, recommendation] of Object.entries(scanData.summary.quick_wins ?? {})) {
  await linearClient.createIssue({
    teamId: 'YOUR_TEAM_ID',
    title: `[SEO] ${area}: ${recommendation.slice(0, 60)}`,
    description: recommendation,
    priority: 1,
    labels: ['seo', 'technical-debt']
  });
}

Google Sheetsでの時系列トラッキング

// Append AI Visibility scores to Google Sheets for time-series tracking
const { GoogleSpreadsheet } = require('google-spreadsheet');
const doc = new GoogleSpreadsheet('YOUR_SHEET_ID');

await doc.useServiceAccountAuth(credentials);
await doc.loadInfo();

const sheet = doc.sheetsByIndex[0];
await sheet.addRow({
  'Date': report.completed_at,
  'Business': signalData.summary.business_name,
  'Presence Score': signalData.summary.presence_score,
  'Authority Score': signalData.summary.authority_score,
  'Rank': signalData.summary.competitive_rank,
  'ChatGPT Score': signalData.data?.platform_variance?.chatgpt?.presence_score,
  'Claude Score': signalData.data?.platform_variance?.claude?.presence_score
});

---

よくある質問

Intelligence Tokenとは？

Intelligence Token = 完了したレポートの固有の識別子です（形式：SIG-2025-11-XXXXX、SCN-2025-11-XXXXX、SOL-2025-11-XXXXX）。トークンはAPIのステータスのレスポンスで返され、レポートを連鎖させるとき（例：既存のAI VisibilityレポートからStrategyのレポートを作るとき）に渡すキーになります。

なぜ役に立つのか：

• プログラムからのアクセス：public_intelligenceを解析して、ご利用のツール（Notion、Linear、Google Sheets）に取り込めます
• 自動化：新しいレポートをきっかけに動くワークフローを作れます
• 時系列の追跡：過去のデータを保存して、傾向を分析できます
• レポートの連鎖：Strategyのレポートを作成するとき、signal_tokenまたはscan_tokenとして渡せます

入手場所：完了時にGET /v1/reports/{report_id}が返します。完了webhookにも含まれ、Surmadoアプリのレポート詳細ページにも表示されます。

---

Intelligence Tokenはどうやって入手しますか？

トークンを入手する3つの方法：

1. REST API：レポートがcompletedになったらGET /v1/reports/{report_id}を呼び出します。tokenフィールドに値が入っています。

2. Webhook：レポート作成時にwebhook_urlを指定すると、完了時のペイロードのreport.tokenにトークンが入っています。

3. PDFレポート：1ページ目にトークンが印刷されています（形式：Token: SIG-2025-11-A7K3Q）。

Intelligence Tokenは、完了したレポートの安定した識別子で、有効期限はありません。完了メールに記載されるPDFのマジックリンクURLの有効期間は約30日間です。それを過ぎたら、ステータスのエンドポイントから、署名付きの新しいダウンロードURLをいつでも取得し直せます。

---

Intelligence TokenをZapierで使えますか？

はい。 Surmadoの完了webhookを使ったZapierのワークフロー例です。

トリガー：Surmadoのwebhook（report.completedイベント）。レポート作成時にwebhook_urlを設定します アクション1：APIキーを付けてGET /v1/reports/{report.id}を呼び出し、public_intelligenceを取得します アクション2：public_intelligence.summary.presence_scoreを解析します アクション3：スコアを入れたNotionのデータベースエントリを作成します アクション4：presence_score < 10ならSlackに通知を送ります

よくある連携先：

• Notion：マーケティングのダッシュボードを自動で更新
• Linear：スコアの低い問題のタスクを作成
• Google Sheets：時系列での追跡
• Slack：可視性の変化をチームに通知

手順はZapier連携ガイド、または下のGoogle Sheetsの時系列の例をご覧ください。

---

Intelligence Tokenに有効期限はありますか？

ありません。 トークンは完了したレポートの安定した識別子で、過去の参照用として有効なままです。

時間とともに変わるものは次のとおりです。

• メールで届くマジックリンクのPDF URLの有効期間は約30日間です。それを過ぎたら、GET /v1/reports/{report_id}から署名付きのダウンロードURLを取得し直してください。
• ステータスのエンドポイントが返す署名付きダウンロードURLは、約15分で期限が切れます。長期間使うファイルは、ダウンロードして手元に保存してください。
• スコアは変動します。AIプラットフォームや競合の位置づけが変わるためです。新しいデータを得るため、定期的にレポートを再実行してください（四半期ごとが一般的です）。

---

SIG、SCN、SOLのトークンはどう違いますか？

製品ごとにスキーマが異なります。

SIG-*（AI Visibilityのトークン）：

• スキーマ：可視性の指標（presence_score、ghost_influence、platform_variance）
• 用途：AIからの見つけられやすさを継続的に追跡
• 例：SIG-2025-11-A7K3Q

SCN-*（Site Auditのトークン）：

• スキーマ：技術的なSEOの指標（lighthouse、schema_validation、accessibility）
• 用途：サイトの健全性を監視し、Core Web Vitalsを追跡
• 例：SCN-2025-11-A7K9P

SOL-*（Strategyのトークン）：

• スキーマ：戦略上の推奨事項（todo_list、priority、rationale）。PDFで提供され、public_intelligenceとしては公開されません
• 用途：戦略上の意思決定の記録、プロジェクト管理ツールへの連鎖
• 例：SOL-2025-11-A7K3Q

すべてのトークン：レポートの完了時に返される、安定した識別子です。

スキーマのドキュメントを見る →

---

SurmadoにはREST APIがありますか？

はい。 SurmadoのREST APIでは、次のことができます。

• AI Visibility、Site Audit、Strategyのレポートをプログラムから作成する
• 冪等なPOST /v1/brands/ensureでブランドを管理する
• レポートのステータスを確認し、PDFやPPTXをダウンロードする
• レポートの完了時にwebhookで通知を受け取る

APIキー（sur_live_...）で、BearerトークンまたはX-API-Keyヘッダーを使って認証します。レポート1件につき1ジョブです。

API連携ガイドを見る →

---

AI Visibilityのレポートを自動化できますか？

はい。 REST APIを使うと、AI Visibilityのレポートをプログラムから作成できます。

POST /v1/reports/signal

webhookと組み合わせれば、完全に自動化したワークフローになります。レポートを作成し、完了したらwebhookを受け取り、結果を解析します。必須フィールドと例は、API連携ガイドをご覧ください。

Zapier、Make、n8nなどのノーコードツールからAPI経由でレポート作成を実行することもできます。手順はZapier連携ガイドをご覧ください。

---

お困りですか？

スキーマのフィールドについてのご質問は、FAQをご覧いただくか、support@surmado.comまでメールでお問い合わせください。

連携を作っていますか？ ぜひお聞かせください。ユースケースをhi@surmado.comまでお寄せください。

はじめましょう：Surmadoを試す | Scout（スカウト）に依頼する

→ 関連：API連携ガイド | Zapier連携ガイド | Make連携ガイド | n8n連携ガイド