---
title: "見出し抽出取得"
method: POST
path: "/v1/headline"
tags: ["見出し抽出"]
---

# 見出し抽出取得

`POST /v1/headline`

見出し抽出。指定キーワードのGoogle検索上位ページの見出し（h1〜h6）を抽出する。

そのキーワードでSEO上位表示するために必要な情報を分析したいときや、
競合上位ページがどのようなオリジナルコンテンツを記事に含めているのかを把握するのに役立つ。
SEO記事のタイトル/見出し/本文を作成する前に使うべき機能。

ページごと・上位ページ平均の文字数・見出し数なども返す。

Googleは、そのキーワードで検索するユーザーの悩みを解決できる可能性の高い記事を上位表示する。
このため上位ページ中で共通して出現する見出し/トピックは、そのキーワードを調べるユーザーにとって必要な情報である可能性が高い。

上位ページの頻出単語（共起語）も欲しい場合はPOST /v1/co-occurrenceを併用する。

1リクエストあたり3クレジットを消費。

## Request body

- HeadlineDto
  - `keyword` string, required — 見出し抽出を行う検索キーワード。1文字以上の文字列を指定する。
  - `lessHeadlines` boolean — 見出し5件未満のページを除外するかどうか。true で除外する。省略時は false。
  - `lessCharacters` boolean — 文字数1,000未満のページを除外するかどうか。true で除外する。省略時は false。
  - `h1` boolean — h1タグの見出しを含めるかどうか。省略時は true。
  - `h2` boolean — h2タグの見出しを含めるかどうか。省略時は true。
  - `h3` boolean — h3タグの見出しを含めるかどうか。省略時は true。
  - `h4` boolean — h4タグの見出しを含めるかどうか。省略時は true。
  - `h5` boolean — h5タグの見出しを含めるかどうか。省略時は false。
  - `h6` boolean — h6タグの見出しを含めるかどうか。省略時は false。
  - `sortBy` 'position' | 'title' | 'headlineCount' | 'wordCount' — ソート項目。position / title / headlineCount / wordCount。省略時は position。
  - `orderBy` 'asc' | 'desc' — ソート順。asc: 昇順 / desc: 降順。省略時は asc。
  - `limit` integer — 取得件数。1〜20 の整数を指定する。省略時は 20。

## Response `200`

検索成功

- HeadlineResponseDto
  - `result` boolean, required — API 呼び出しの成否。正常時は true、エラー時は false。
  - `meta` object, required — リクエストに関するメタ情報（課金・消費リソースなど）
    - `consumedCredit` number, required — このリクエストで消費されたクレジット数。
  - `data` object, required — 見出し抽出の検索結果データ
    - `query` object, required — リクエストで指定された検索クエリ情報
      - `keyword` string, required — 見出し抽出の元になった検索キーワード
    - `summary` object, required — 件数・文字数・見出し数のサマリー情報
      - `totalCount` number, required — 取得対象全体の件数
      - `returnedCount` number, required — このレスポンスに含まれている件数
      - `averageHeadlineCount` number, required — 1ページあたりの平均見出し数
      - `averageWordCount` number, required — 1ページあたりの平均文字数
      - `minWordCount` number, required — ページ文字数の最小値
      - `maxWordCount` number, required — ページ文字数の最大値
    - `items` object[], required — 見出し抽出アイテムのリスト。各アイテムにページ情報・指標・見出し一覧を含む。
      - `page` object, required — 検索結果ページの基本情報（URL・タイトル・ディスクリプション）
        - `url` string, required — 検索結果ページの URL
        - `title` string, required — 検索結果ページのタイトル
        - `description` string, required — 検索結果ページのディスクリプション
      - `metrics` object, required — ページの各種指標（検索順位・見出し数・文字数）
        - `position` number, required — 検索順位
        - `headlineCount` number, required — このページに含まれる見出し数
        - `wordCount` number, required — このページの文字数
      - `headlines` object[], required — ページ内の見出し一覧。指定した見出しレベル（h1–h6）に応じてフィルタされる。
        - `level` string, required — 見出しレベル（h1, h2, h3, h4 など）
        - `text` string, required — 見出しテキスト
  - `errors` string[], required — エラーメッセージの配列。正常時は空配列。

## Other responses

- `400` — バリデーションエラー
- `402` — クレジット不足
- `403` — 認証エラー
- `429` — レート制限超過
- `500` — Internal Server Error
- `503` — Service Unavailable - データベース接続エラーなど

---

[API](https://skmtc.dev/rakkokeyword/apis/api.md) · [All operations](https://skmtc.dev/rakkokeyword/apis/api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/rakkokeyword/api/revisions/23e921f5f25c/schema)