ログイン 無料テスト
Deutsch English Español Français Italiano Português 日本語
無料テスト ログイン
  • はじめに
  • クイックスタート
  • インフォメーション
  • 通話制限
  • グーグル版
  • バージョン一覧
  • 検索結果
  • グーグル検索クエリ
  • グーグルマップクエリ
  • クエリーID
  • SERPの回復
  • コールバックURL
  • SERPの処理状況
  • リクエスト履歴
  • 請求
  • 残りのクレジット
  • 支払い方法

Semscraper API ドキュメント

クイックスタート

3つのステップで、最初のGoogle SERPをJSONで取得できます。

  1. アカウントを作成してください。1,000件のSERPが無料で、クレジットカードは不要です。次に、アカウントのAPIキーメニューからキーをコピーします。キーは各リクエストのAuthorization: Bearerヘッダーで送信します。 無料アカウントを作成
  2. POST /v1/serpでキーワードを送信します（1回のリクエストで最大1,000件）。レスポンスには各SERPのIDと料金が含まれます。課金されるのはこの時点だけです。
    キーワードを送信
    curl -X POST https://api.semscraper.com/v1/serp \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[{"search_engine": "google_search", "keyword": "パンケーキ レシピ", "device": "desktop", "location": "jp", "language": "ja", "depth": 1}]'
  3. 受け取ったIDを指定してGET /v1/serpで結果を取得します。SERP_IDは、前のステップで返されたdata[0].idフィールドの値に置き換えてください。収集は非同期で行われるため、ステータスがpendingまたはprocessingの間は、少し時間をおいて再度お試しください。結果の取得に料金はかかりません。
    SERPを取得
    curl "https://api.semscraper.com/v1/serp?ids=SERP_ID&output=json" \
  -H "Authorization: Bearer YOUR_API_KEY"

APIに問い合わせ続けずに通知を受け取るには、リクエストにcallback_urlを追加してください。数十万件のキーワードにはBulk SERP APIをご覧ください。

インフォメーション

通話制限

API呼び出し回数の制限
GET : 500 回/分
POST : 500 回/分

グーグル版

バージョン一覧

GoogleのSERPを取得するために必要な場所と言語パラメータを取得します。
get
https://api.semscraper.com/v1/serp/google/location
認可 : Bearer {api_key}
  • リクエスト
  • 対応に成功
Status: 200 OK
{
    "status": "success",
    "request_ms": 17,
    "count": 372,
    "data": [
        {
            "location": "us",
            "language": "en",
            "host": "google.com",
            "name": "United States"
        },
        {
            "location": "fr",
            "language": "fr",
            "host": "google.fr",
            "name": "France"
        }
}

SERPs

グーグル検索クエリ

Google検索SERPクエリの作成
データはJSON配列で送信されなければならない。各要素は以下のフィールドを含んでいなければならない。
制限
JSON配列は1000個の要素を含むことができるので、1回の呼び出しで1000個のSERPsスクレイプを作成することができる。
post
https://api.semscraper.com/v1/serp
認可 : Bearer {api_key}
パラメータ
search_engine
必須
string
検索エンジンの選択：
グーグル検索（値：google_search）
keyword
必須
string
検索エンジンで検索するキーワード
device
必須
string
デバイス：
コンピュータ（値：デスクトップ）
モバイル（値：モバイル）
depth
必須
integer
Page depth（ページ深度）：GoogleのSERPをページ分割して取得します。このパラメータは1(およそ10件)から10(およそ100件)の間でなければなりません。
location
必須
string
検索エンジンのロケーションコード
language
必須
string
検索エンジンの言語
geolocation
string
Google の SERP の位置を指定します。市区町村・地域・国をカンマ区切りで指定するか（例：Nice, Alpes-Maritimes, France）、10進数の「緯度,経度」で GPS 位置を指定します（例：43.7102,7.2620）。
priority
integer
リクエストの優先順位付けに使用され、優先順位の高い順に処理されます。1(低い)から10(高い)の間で設定します。
callback_url
string
キーワードが処理された後、その結果を送信するURLを指定できます。
結果ブロックの種類
Type フィールドが取りうる値です。ブロックは、指定したキーワードに対して Google が表示した場合にのみレスポンスに含まれます。
検索結果と広告
organic
自然検索結果
通常の自然検索結果です。
sitelinks
サイトリンク
自然検索結果に付属するサブリンクです。
paid_top
上部の広告
自然検索結果の上に表示される有料広告です。
paid_bottom
下部の広告
自然検索結果の下に表示される有料広告です。
リッチブロック
featured_snippet
強調スニペット
自然検索結果の上に強調表示される抜粋です。
knowledge_graph
ナレッジパネル
SERP の右側に表示されるパネルの要素です。
images
画像
画像ブロックのサムネイルです。
videos
動画
動画ブロックの動画です。
top_stories
トップニュース
トップニュースブロックの記事です。
shopping
ショッピング
Google Shopping カルーセルの商品です。
recipes
レシピ
レシピブロックのレシピです。
local_pack
ローカルパック
Google Maps から取得されるローカルパックの店舗です。
visual_digest
Visual digest
Google が生成する Visual digest の要素です。
関連の提案
people_also_ask
他の人はこちらも質問
「他の人はこちらも質問」ブロックの質問です。
related_searches
関連キーワード
ページ下部に表示される関連キーワードです。
find_results_on
Find results on
「Find results on」ブロックのリンクです。
location_sites
地域関連サイト
地域に関連するブロックに掲載されたサイトです。
AI Overview
ai_overview_citation
引用
AI が生成したテキスト内で引用されたブランドです。
ai_overview_citation_source
引用元
引用の参照元で、引用にカーソルを合わせると表示されます。
ai_overview_panel
ソースパネル
参照元のサイドパネルに掲載されたサイトです。
  • リクエスト
  • 対応に成功
  • エラー応答
Status: 200 OK
{
    "status": "success",
    "request_ms": 40,
    "count": 1,
    "currency": "EUR",
    "total_cost": 0.0003,
    "data": [
        {
            "id": "SERP_ID",
            "status": "pending",
            "keyword": "example keyword",
            "device": "mobile",
            "location": "fr",
            "language": "fr",
            "depth": 1,
            "geolocation": false,
            "priority": 1,
            "callback_url": null,
            "cost": 0.0003,
            "_links": {
                "json": {
                    "href": "/serp?ids=SERP_ID&output=json",
                    "method": "GET",
                    "type": "application/json"
                },
                "html": {
                    "href": "/serp?ids=SERP_ID&output=html",
                    "method": "GET",
                    "type": "application/json"
                }
            }
        }
    ]
}
Status: 400 Bad Request
{
    "error": "Bad Request",
    "message": "DESCRIPTION_OF_ERROR",
    "code": 400
}

グーグルマップクエリ

GoogleマップのSERPクエリを作成する
データはJSON配列で送信されなければならない。各要素は以下のフィールドを含んでいなければならない。
制限
JSON配列は1000個の要素を含むことができるので、1回の呼び出しで1000個のSERPsスクレイプを作成することができる。
post
https://api.semscraper.com/v1/serp
認可 : Bearer {api_key}
パラメータ
search_engine
必須
string
検索エンジンの選択：
グーグルマップ（値：google_maps）
keyword
必須
string
検索エンジンで検索するキーワード
depth
必須
integer
Page depth（ページ深度）：GoogleのSERPをページ分割して取得します。このパラメータは1(およそ10件)から10(およそ100件)の間でなければなりません。
location
必須
string
検索エンジンのロケーションコード
language
必須
string
検索エンジンの言語
geolocation
string
Google の SERP の位置を指定します。市区町村・地域・国をカンマ区切りで指定するか（例：Nice, Alpes-Maritimes, France）、10進数の「緯度,経度」で GPS 位置を指定します（例：43.7102,7.2620）。 GPS 位置には任意でズームレベルを追加できます（例：43.7102,7.2620,16z）。
priority
integer
リクエストの優先順位付けに使用され、優先順位の高い順に処理されます。1(低い)から10(高い)の間で設定します。
callback_url
string
キーワードが処理された後、その結果を送信するURLを指定できます。
  • リクエスト
  • 対応に成功
  • エラー応答
Status: 200 OK
{
    "status": "success",
    "request_ms": 40,
    "count": 1,
    "currency": "EUR",
    "total_cost": 0.0003,
    "data": [
        {
            "id": "SERP_ID",
            "status": "pending",
            "keyword": "example keyword",
            "device": "mobile",
            "location": "fr",
            "language": "fr",
            "depth": 1,
            "geolocation": false,
            "priority": 1,
            "callback_url": null,
            "cost": 0.0003,
            "_links": {
                "json": {
                    "href": "/serp?ids=SERP_ID&output=json",
                    "method": "GET",
                    "type": "application/json"
                },
                "html": {
                    "href": "/serp?ids=SERP_ID&output=html",
                    "method": "GET",
                    "type": "application/json"
                }
            }
        }
    ]
}
Status: 400 Bad Request
{
    "error": "Bad Request",
    "message": "DESCRIPTION_OF_ERROR",
    "code": 400
}

クエリーID

まだ取得していない完了したSERPの識別子（ID）のリスト。
このメソッドでは、すでに処理されたがまだ検索されていないすべてのSERPのIDを取得できる。そして、これらのIDを使ってSERP検索メソッドを呼び出すことができる。
get
https://api.semscraper.com/v1/serp
認可 : Bearer {api_key}
  • リクエスト
  • 対応に成功
Status: 200 OK
{
    "status": "success",
    "request_ms": 40,
    "count": 2,
    "data": [
        {
            "id": "SERP_ID",
            "status": "done",
            "keyword": "example keyword",
            "device": "desktop",
            "location": "fr",
            "language": "fr",
            "depth": 5,
            "geolocation": false,
            "callback_url": "",
            "cost": 0.0011,
            "_links": {
                "json": {
                    "href": "/serp?ids=SERP_ID&output=json",
                    "method": "GET",
                    "type": "application/json"
                },
                "html": {
                    "href": "/serp?ids=SERP_ID&output=html",
                    "method": "GET",
                    "type": "application/json"
                }
            }
        },
        {
            "id": "SERP_ID",
            "status": "done",
            "keyword": "example keyword",
            "device": "mobile",
            "location": "fr",
            "language": "fr",
            "depth": 5,
            "geolocation": false,
            "callback_url": "",
            "cost": 0.0011,
            "_links": {
                "json": {
                    "href": "/serp?ids=SERP_ID&output=json",
                    "method": "GET",
                    "type": "application/json"
                },
                "html": {
                    "href": "/serp?ids=SERP_ID&output=html",
                    "method": "GET",
                    "type": "application/json"
                }
            }
        }
    ]
}

SERPの回復

GoogleのSERPをIDで復元する
カンマで区切られた複数のIDを指定することで、1回の呼び出しで複数のSERPを取得する（JSONまたはHTML形式）。
制限
最大100のIDを指定できるので、1回の呼び出しで100のSERPを検索できる。
get
https://api.semscraper.com/v1/serp?ids=id1,id2&output=json
認可 : Bearer {api_key}
パラメータ
ids
必須
string
IDのカンマ区切りリスト。
output
必須
string
出力形式の選択：
JSON (値: json)
HTML (値: html)
結果の形式
  • Google Search
  • Google Maps
type
string
検索結果ブロックの種類（オーガニック、動画、画像、people_also_ask、local_packなど）
rank_type
integer
その要素が、自身のブロックタイプ内での位置（例：オーガニック検索結果の3番目＝3）
rank_serp
integer
SERP全体（すべてのブロックを含む）における絶対位置。ページ上の実際の垂直位置（ピクセル単位）に基づく。
page
integer
その要素が表示されるSERPのページ番号
pixel
integer
ページ上の要素の垂直位置（上端からのピクセル数）
domain
string
URLのドメイン
url
string
検索結果のURL
title
string
検索結果の表示タイトル
description
string
説明／検索結果の抜粋
brand
string
引用されたブランド、または Google が表示する参照元の名称です。ai_overview_citation、ai_overview_citation_source、ai_overview_panel のブロックにのみ含まれます。引用では URL が空のことが多く、その場合はブランドがその要素の唯一の情報になります。
visible
boolean
要素が AI Overview に最初から表示されているか（true）、展開後にのみ表示されるか（false）を示します。AI Overview のブロックにのみ含まれます。ai_overview_citation_source は引用にカーソルを合わせたときにだけ表示されるため、常に false です。
rating
float
Google が表示する平均評価です（例：4.1）。organic と local_pack のブロックにのみ含まれ、星が表示されていない場合は null です。
reviews
integer
評価の元になっている口コミの件数です。organic と local_pack のブロックにのみ含まれ、星が表示されていない場合は null です。
price_range
string
Google が表示する店舗の価格帯です（例：「20–30 €」）。local_pack のブロックにのみ含まれ、表示がない場合は null です。
details
array
店舗の下に表示される情報で、Google の表示順と言語のままです：価格、カテゴリ、住所、営業時間、サービスなど。local_pack のブロックにのみ含まれます。各情報の順序や有無は保証されません。
serp_info.ai_overview
object
SERP の AI Overview で、serp_info オブジェクトに含まれます（results ではありません）。type、text、complete を持ちます。
serp_info.ai_overview.type
string
AI Overview の表示方法です：sync（ページの読み込み時点でページ内にある）、async（ページの読み込み後に Google がその場で生成する）、none（AI Overview なし）。
serp_info.ai_overview.text
string
AI が生成したテキストで、書式やリンクを含まないプレーンテキストです。SERP に AI Overview がない場合、またはテキストを読み取れなかった場合は null です。
serp_info.ai_overview.complete
boolean
取得時点で AI Overview の生成が完了していた場合は true です。テキストがない場合、または不完全な可能性がある場合は false です。
rank_type
integer
その要素が、自身のブロックタイプ内での位置（例：オーガニック検索結果の3番目＝3）
rank_serp
integer
SERP全体（すべてのブロックを含む）における絶対位置。ページ上の実際の垂直位置（ピクセル単位）に基づく。
page
integer
その要素が表示されるSERPのページ番号
pixel
integer
ページ上の要素の垂直位置（上端からのピクセル数）
title
string
検索結果の表示タイトル
cid
string
施設情報のGoogle ID（CID）
reviews
integer
レビュー数
rating
float
5点満点の平均点
website
string
施設のウェブサイト
type
string
施設の種類（例：レストラン）
address
string
郵送先住所
status_label
string
営業状況（例：営業中、休業中）
status_detail
string
ステータスの詳細（例：勤務時間）
comment
string
コメント／表示されている抜粋
images
array
このページに掲載されている画像の一覧
  • リクエスト
  • 対応に成功
  • エラー応答
Status: 200 OK
{
    "status": "success",
    "request_ms": 41,
    "count": 1,
    "data": [
        {
            "id": "SERP_ID",
            "status": "done",
            "keyword": "example keyword",
            "device": "desktop",
            "location": "fr",
            "language": "fr",
            "depth": 1,
            "geolocation": false,
            "priority": 1,
            "callback_url": "",
            "cost": 0.0003,
            "created_at": "2025-09-10T12:32:56Z",
            "scraped_at": "2025-09-10T12:33:02Z",
            "duration_ms": 5403,
            "serp_info": {
                "result_count": 1500000000,
                "ai_overview": {
                    "type": "async",
                    "text": "A keyword is a word or phrase that users type into a search engine to find information...",
                    "complete": true
                }
            },
            "results": [
                {
                    "type": "people_also_ask",
                    "items": [
                        {
                            "rank_type": 1,
                            "rank_serp": 4,
                            "page": 1,
                            "pixel": 806,
                            "domain": "guides.lib.uh.edu",
                            "url": "https://guides.lib.uh.edu/c.php?g\\x3d1249281",
                            "title": "What is a keyword example?",
                            "description": ""
                        },
                        {
                            "rank_type": 2,
                            "rank_serp": 5,
                            "page": 1,
                            "pixel": 858,
                            "domain": "toolsqa.com",
                            "url": "https://toolsqa.com/cucumber/data-driven-testing-using-examples-keyword/",
                            "title": "What is the example keyword used for?",
                            "description": ""
                        },
                        {
                            "rank_type": 3,
                            "rank_serp": 6,
                            "page": 1,
                            "pixel": 911,
                            "domain": "www.editage.com",
                            "url": "https://www.editage.com/insights/how-to-create-keywords-for-a-research-paper",
                            "title": "How do you write keywords examples?",
                            "description": ""
                        },
                        {
                            "rank_type": 4,
                            "rank_serp": 7,
                            "page": 1,
                            "pixel": 964,
                            "domain": "libguides.lvc.edu",
                            "url": "https://libguides.lvc.edu/c.php?g\\x3d1152118\\x26ampp\\x3d8409030",
                            "title": "What is an example of a keyword search?",
                            "description": ""
                        }
                    ]
                },
                {
                    "type": "videos",
                    "items": [
                        {
                            "rank_type": 1,
                            "rank_serp": 1,
                            "page": 1,
                            "pixel": 223,
                            "domain": "www.youtube.com",
                            "url": "https://www.youtube.com/watch?v=H-B5oFJjL8I",
                            "title": "What are Keywords and How to Choose Them? 1.1. SEO ...",
                            "description": ""
                        },
                        {
                            "rank_type": 2,
                            "rank_serp": 2,
                            "page": 1,
                            "pixel": 374,
                            "domain": "www.youtube.com",
                            "url": "https://www.youtube.com/watch?v=TTlEVVB75wo&pp=2AEAkAIB",
                            "title": "What Are Keywords? Everything You Need To Know (and more)",
                            "description": ""
                        },
                        {
                            "rank_type": 3,
                            "rank_serp": 3,
                            "page": 1,
                            "pixel": 526,
                            "domain": "www.youtube.com",
                            "url": "https://www.youtube.com/watch?v=OMJQPqG2Uas",
                            "title": "Keyword Research Tutorial: From Start to Finish",
                            "description": ""
                        }
                    ]
                },
                {
                    "type": "organic",
                    "items": [
                        {
                            "rank_type": 1,
                            "rank_serp": 8,
                            "page": 1,
                            "pixel": 1077,
                            "domain": "www.seoquantum.com",
                            "url": "https://www.seoquantum.com/en/blog/6-types-keywords-organic-seo",
                            "title": "The 6 Types of Keywords in Organic SEO",
                            "description": "2 mars 2024 — I will introduce you to 6 types of keywords that you absolutely need to know. We will start with the most common ones such as long-tail keywords and then move ...",
                            "rating": null,
                            "reviews": null
                        },
                        {
                            "rank_type": 2,
                            "rank_serp": 9,
                            "page": 1,
                            "pixel": 1223,
                            "domain": "storychief.io",
                            "url": "https://storychief.io/blog/seo-keyword-research-examples",
                            "title": "10 Clever SEO Keyword Research Examples",
                            "description": "Let's say you run a food blog. Some potential SEO keywords could be: quick weeknight dinners easy dinner recipes 30 minute meals one pot dinners",
                            "rating": null,
                            "reviews": null
                        },
                        {
                            "rank_type": 3,
                            "rank_serp": 10,
                            "page": 1,
                            "pixel": 1369,
                            "domain": "www.indeed.com",
                            "url": "https://www.indeed.com/career-advice/career-development/types-of-keywords",
                            "title": "19 Types of Keywords",
                            "description": "6 juin 2025 — 19 types of keywords and how to use them for marketing · 1. Market segment keywords · 2. Customer-defining keywords · 3. Product-defining ...",
                            "rating": null,
                            "reviews": null
                        },
                        {
                            "rank_type": 4,
                            "rank_serp": 11,
                            "page": 1,
                            "pixel": 1515,
                            "domain": "www.usg.edu",
                            "url": "https://www.usg.edu/galileo/skills/unit04/primer04_07.phtml",
                            "title": "Keyword Search",
                            "description": "In this case, the phrase alternative fuels and automobiles are the significant keywords.",
                            "rating": null,
                            "reviews": null
                        },
                        {
                            "rank_type": 5,
                            "rank_serp": 12,
                            "page": 1,
                            "pixel": 1639,
                            "domain": "guides.lib.uh.edu",
                            "url": "https://guides.lib.uh.edu/c.php?g=1249281",
                            "title": "What are keywords and why are they important? - Guides",
                            "description": "You probably used the title of the film and the word “showtimes” as your keywords to bring up the results you needed. Keywords in academic research are similar.",
                            "rating": null,
                            "reviews": null
                        },
                        {
                            "rank_type": 6,
                            "rank_serp": 13,
                            "page": 1,
                            "pixel": 1785,
                            "domain": "www.tactee.fr",
                            "url": "https://www.tactee.fr/seo/strategie-seo/keyword-seo/",
                            "title": "Qu'est ce qu'un keyword SEO ? [Définition & conseil]",
                            "description": "13 juil. 2024 — Commerciale : l'utilisateur compare des produits ou des services, par exemple « meilleur smartphone 2024 ». Identifier l'intention de recherche ...",
                            "rating": null,
                            "reviews": null
                        },
                        {
                            "rank_type": 7,
                            "rank_serp": 14,
                            "page": 1,
                            "pixel": 1931,
                            "domain": "backlinko.com",
                            "url": "https://backlinko.com/types-of-keywords",
                            "title": "10 Types of Keywords with Examples (+ How to Find Them)",
                            "description": "15 mai 2025 — 10 Types of Keywords with Examples (+ How to Find Them) · 1. Seed Keywords · 2. Informational Keywords · 3. Commercial Keywords · 4.",
                            "rating": null,
                            "reviews": null
                        },
                        {
                            "rank_type": 8,
                            "rank_serp": 15,
                            "page": 1,
                            "pixel": 2077,
                            "domain": "learn.microsoft.com",
                            "url": "https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/keywords/",
                            "title": "C# Keywords and contextual keywords - C# reference",
                            "description": "17 avr. 2025 — For example, @if is a valid identifier, but if isn't because if is a keyword. The first table in this article lists keywords that are ...",
                            "rating": null,
                            "reviews": null
                        }
                    ]
                },
                {
                    "type": "local_pack",
                    "items": [
                        {
                            "rank_type": 1,
                            "rank_serp": 19,
                            "page": 1,
                            "pixel": 2520,
                            "domain": "lebistrotm.fr",
                            "url": "https://lebistrotm.fr/",
                            "title": "Le Bistrot M",
                            "description": "",
                            "rating": 4.6,
                            "reviews": 220,
                            "price_range": "20–30 €",
                            "details": [
                                "20–30 €",
                                "Restaurant",
                                "1 Pl. Xavier Taillade",
                                "Fermé",
                                "Ouvre à 18:30",
                                "Repas sur place",
                                "Aucun plat à emporter",
                                "Pas de livraison"
                            ]
                        },
                        {
                            "rank_type": 2,
                            "rank_serp": 20,
                            "page": 1,
                            "pixel": 2661,
                            "domain": "www.domainedesoliviers.fr",
                            "url": "http://www.domainedesoliviers.fr/",
                            "title": "Domaine des Oliviers",
                            "description": "",
                            "rating": 4.5,
                            "reviews": 1600,
                            "price_range": null,
                            "details": [
                                "Française",
                                "4 All. Paul Emile d'Allard",
                                "Fermé",
                                "Ouvre à 19:00",
                                "Hôtel discret avec piscine et restaurant"
                            ]
                        }
                    ]
                },
                {
                    "type": "images",
                    "items": [
                        {
                            "rank_type": 1,
                            "rank_serp": 16,
                            "page": 1,
                            "pixel": 2311,
                            "domain": "searchfacts.com",
                            "url": "https://searchfacts.com/what-are-keywords-in-seo/",
                            "title": "",
                            "description": ""
                        },
                        {
                            "rank_type": 2,
                            "rank_serp": 17,
                            "page": 1,
                            "pixel": 2311,
                            "domain": "backlinko.com",
                            "url": "https://backlinko.com/hub/seo/seo-keywords",
                            "title": "",
                            "description": ""
                        },
                        {
                            "rank_type": 3,
                            "rank_serp": 18,
                            "page": 1,
                            "pixel": 2311,
                            "domain": "ahrefs.com",
                            "url": "https://ahrefs.com/blog/what-are-keywords/",
                            "title": "",
                            "description": ""
                        }
                    ]
                }
            ]
        }
    ]
}
Status: 400 Bad Request
{
    "error": "InvalidParameter",
    "message": "DESCRIPTION_OF_ERROR",
    "code": 400
}

コールバックURL

コールバックURLによるSERPの回復
SERPの結果は、クエリ作成時に提供したURLで直接受け取ることができます。 必要なのは、使用したAPIキーにリンクされたHMACキーを取得することだけです。
  • コード
  • PHP
  • Python
  • Javascript
  • Ruby
  • Java
  • C#
  • GO
// 1) Read the raw body (JSON)
$raw = file_get_contents('php://input');

// 2) Retrieve the headers
$headers = function_exists('getallheaders') ? getallheaders() : [];
$signature = $headers['X-Signature'] ?? '';

// 3) (Optional) Verify the HMAC signature
$sharedSecret = 'HMAC_KEY';
$expected = hash_hmac('sha256', $raw, $sharedSecret);
if (!hash_equals($expected, $signature)) {
    http_response_code(401);
    header('Content-Type: text/plain; charset=utf-8');
    echo 'Invalid signature';
    exit;
}

// 4) Decode the JSON
$data = json_decode($raw, true);

if (json_last_error() !== JSON_ERROR_NONE) {
    http_response_code(400);
    header('Content-Type: text/plain; charset=utf-8');
    echo 'Invalid JSON';
    exit;
}

// 5) Process the data: a list holding the finished SERP
foreach ($data as $serp) {
    // $serp['id'], $serp['keyword'], $serp['results']...
}

// 6) Respond in JSON (optional, we log these responses for tracking purposes)
http_response_code(200);
header('Content-Type: application/json; charset=utf-8');
echo json_encode([
    'status' => 'ok',
    'received_at' => gmdate('c'),
    'echo' => array_column($data, 'id')
]);

SERPの処理状況

SERPs処理の現状
SERPの数をステータス別に表示します：
完了し、ユーザーが結果を取得（status=done, fetched=true）
完了し、結果はユーザーによって取得されなかった（status=done, fetched=false）
処理中（ステータス=処理中）
待機中（ステータス=保留）
get
https://api.semscraper.com/v1/serp/status
認可 : Bearer {api_key}
  • リクエスト
  • 対応に成功
Status: 200 OK
{
    "status": "success",
    "request_ms": 54,
    "count": 4,
    "data": [
        {
            "status": "done",
            "fetched": true,
            "count": 5
        },
        {
            "status": "done",
            "fetched": false,
            "count": 1000
        },
        {
            "status": "processing",
            "count": 0
        },
        {
            "status": "pending",
            "count": 0
        }
    ]
}

リクエスト履歴

リクエストを新しい順に一覧表示します。設定内容（キーワード、検索エンジン、デバイス、ロケーション、言語、深度など）とステータスを返し、SERP の結果は含みません。
ステータスや取得済みかどうかにかかわらず、アカウントのすべてのリクエストが返されます。この呼び出しによってリクエストが取得済みになることはありません。

ページ送りするには、has_more が true の間、前のレスポンスの next_cursor を cursor パラメータに指定してエンドポイントを再度呼び出します。_links.next リンクにはそのまま使える URL が入っています。リクエストの結果を取得するには、その _links.json または _links.html リンクを使用します。
制限
1回の呼び出しで最大 10,000 リクエスト
get
https://api.semscraper.com/v1/serp/list?date=2026-11-04&limit=1000
認可 : Bearer {api_key}
パラメータ
date
string
リクエストの作成日で、YYYY-MM-DD 形式です（例：2026-10-04）。指定しない場合は、すべての日付が返されます。
status
string
ステータスによる絞り込みです：pending、processing、done。指定しない場合は、すべてのステータスが返されます。
limit
integer
1ページあたりのリクエスト数で、1〜10,000 の範囲です。デフォルトは 1,000 です。
cursor
string
ページ送り用のカーソルで、前のレスポンスの next_cursor の値です。最初のページでは指定しません。
  • リクエスト
  • 対応に成功
  • エラー応答
Status: 200 OK
{
    "status": "success",
    "request_ms": 38,
    "count": 2,
    "has_more": true,
    "next_cursor": "MTI4NDU2Nzg5",
    "data": [
        {
            "id": "SERP_ID",
            "search_engine": "google_search",
            "keyword": "example keyword",
            "device": "desktop",
            "location": "fr",
            "language": "fr",
            "depth": 1,
            "geolocation": null,
            "priority": 1,
            "callback_url": null,
            "status": "done",
            "fetched": false,
            "cost": 0.0003,
            "created_at": "2026-10-04 09:12:45",
            "updated_at": "2026-10-04 09:12:58",
            "_links": {
                "json": {
                    "href": "/v1/serp?ids=SERP_ID&output=json",
                    "method": "GET",
                    "type": "application/json"
                },
                "html": {
                    "href": "/v1/serp?ids=SERP_ID&output=html",
                    "method": "GET",
                    "type": "application/json"
                }
            }
        },
        {
            "id": "SERP_ID",
            "search_engine": "google_maps",
            "keyword": "example keyword",
            "device": null,
            "location": "fr",
            "language": "fr",
            "depth": 1,
            "geolocation": "Nice, Alpes-Maritimes, France",
            "priority": 1,
            "callback_url": "https://example.com/callback",
            "status": "pending",
            "fetched": false,
            "cost": 0.0003,
            "created_at": "2026-10-04 09:12:44",
            "updated_at": null,
            "_links": {
                "json": {
                    "href": "/v1/serp?ids=SERP_ID&output=json",
                    "method": "GET",
                    "type": "application/json"
                },
                "html": {
                    "href": "/v1/serp?ids=SERP_ID&output=html",
                    "method": "GET",
                    "type": "application/json"
                }
            }
        }
    ],
    "_links": {
        "next": {
            "href": "/v1/serp/list?date=2026-10-04&limit=1000&cursor=MTI4NDU2Nzg5",
            "method": "GET",
            "type": "application/json"
        }
    }
}
Status: 400 Bad Request
{
    "error": "InvalidParameter",
    "message": "Invalid format for parameter: date",
    "code": 400
}

請求

残りのクレジット

残りのクレジットを回収
get
https://api.semscraper.com/v1/billing/credit
認可 : Bearer {api_key}
  • リクエスト
  • 対応に成功
Status: 200 OK
{
    "status": "success",
    "request_ms": 21,
    "count": 1,
    "data": [
        {
            "balance": 100.50
        }
    ]
}

支払い方法

利用可能な支払い方法
get
https://api.semscraper.com/v1/billing/payment_methods
認可 : Bearer {api_key}
  • リクエスト
  • 対応に成功
Status: 200 OK
{
    "status": "success",
    "request_ms": 43,
    "count": 3,
    "data": [
        {
            "id": 1,
            "name": "Perso",
            "num": "-4242",
            "expiration": "1226",
            "type": "Visa",
            "master": false
        },
        {
            "id": 30,
            "name": "Pro",
            "num": "-4444",
            "expiration": "1227",
            "type": "Mastercard",
            "master": true
        }
    ]
}