web-scraper-api

Oxylabs Web Scraper API

認証

環境変数の認証情報を使用した HTTP Basic Auth が必要です。

curl -u "$OXY_WSA_USERNAME:$OXY_WSA_PASSWORD" ...

エンドポイント

POST https://realtime.oxylabs.io/v1/queries   # immediate response
POST https://data.oxylabs.io/v1/queries       # Push-Pull jobs, callbacks, storage
Content-Type: application/json

主なパラメーター

パラメーター	必須	説明
source	はい	対象のスクレーパー（例：universal、amazon_product、google_search）
url	条件付き	スクレイピング対象の URL（universal および *_url ソースの場合）
query	条件付き	検索クエリまたは商品 ID（*_search および *_product ソースの場合）
parse	いいえ	構造化データの解析を有効にします（対応ソースでは推奨）
render	いいえ	JavaScript のレンダリング：html または png
geo_location	いいえ	地理的ターゲティング：対応している場合、国／州／市、ZIP／郵便番号、座標、または Criteria ID
session_id	いいえ	複数のジョブで同じプロキシ IP を再利用します
content_encoding	いいえ	Realtime または Push-Pull 経由で画像ファイルをダウンロードする場合は base64 に設定します
user_agent_type	いいえ	デバイス／ブラウザーのプリセット。例：desktop_chrome、mobile_ios、tablet_android
locale	いいえ	インターフェース言語／Accept-Language。例：de-DE
callback_url	いいえ	Push-Pull のコールバックエンドポイント
storage_type, storage_url	いいえ	Push-Pull のクラウドアップロード先（gcs、s3、tos、s3_compatible）
markdown, xhr	いいえ	Markdown またはキャプチャした XHR の結果タイプを有効にします
browser_instructions	いいえ	レンダリング時のブラウザー操作。render: "html" が必要です
parsing_instructions, parser_preset	いいえ	カスタム解析ルールまたは保存済みプリセット。parse: true と組み合わせます
client_notes	いいえ	ジョブのメタデータとともに保存されるクライアント側のジョブタグ
domain, subdomain, start_page, pages, limit, store_id, delivery_zip, fulfillment_type	ソース固有	マーケットプレイス／検索／ストアの地域設定およびページネーション用フィールド

user_agent_type の値：desktop、desktop_chrome、desktop_edge、desktop_firefox、desktop_opera、desktop_safari、mobile、mobile_android、mobile_ios、tablet、tablet_android、tablet_ios。

コンテキストパラメーター

context に { "key": "...", "value": ... } オブジェクトとして追加します。

キー	用途
force_headers, headers	カスタムヘッダーを管理対象のヘッダーと統合します
force_cookies, cookies	カスタム Cookie を管理対象の Cookie と統合します
http_method, content	Base64 エンコードされた本文コンテンツを含む post を使用します
follow_redirects	3xx のリダイレクトチェーンを追跡します
successful_status_codes	特定の標準以外の HTTP ステータスコードを成功として扱います

複数形式の出力を利用するには、ペイロードで形式を有効にし（parse、markdown、xhr、render: "png"）、?type=raw,parsed,png,markdown,xhr でリクエストします。

バッチ Push-Pull ジョブでは、query または url にのみ配列を使用して POST /v1/queries/batch を呼び出し、その他のパラメーターはすべて単一の値にします。バッチの最大サイズは 5,000 件です。

クイックスタート

任意の URL をスクレイピング：

curl -X POST 'https://realtime.oxylabs.io/v1/queries' \
  -u "$OXY_WSA_USERNAME:$OXY_WSA_PASSWORD" \
  -H 'Content-Type: application/json' \
  -d '{"source": "universal", "url": "https://example.com"}'

解析を有効にした Google 検索：

curl -X POST 'https://realtime.oxylabs.io/v1/queries' \
  -u "$OXY_WSA_USERNAME:$OXY_WSA_PASSWORD" \
  -H 'Content-Type: application/json' \
  -d '{"source": "google_search", "query": "best laptops", "parse": true}'

ASIN を指定した Amazon 商品：

curl -X POST 'https://realtime.oxylabs.io/v1/queries' \
  -u "$OXY_WSA_USERNAME:$OXY_WSA_PASSWORD" \
  -H 'Content-Type: application/json' \
  -d '{"source": "amazon_product", "query": "B07FZ8S74R", "parse": true}'

適切なソースの選び方

1. 利用可能な場合は専用ソースを使用します（amazon_product、google_search）—解析の精度と信頼性が向上します
2. 未対応のサイトには universal を使用します — 任意の URL で動作します
3. 対応ソースで構造化 JSON 出力を得るには、parse: true を有効にします

レスポンスの構造

{
  "results": [{
    "content": "...",
    "status_code": 200,
    "url": "https://..."
  }]
}

parse: true の場合、content には生の HTML ではなく構造化データ（タイトル、価格、レビューなど）が含まれます。

利用可能なソース

カテゴリ別にまとめた、対応ソース 40 種類以上の完全なリストについては、sources.md を参照してください。

その他の例

位置情報、JavaScript レンダリング、カスタムヘッダーを含む詳細なリクエスト／レスポンス例については、examples.md を参照してください。

エラー処理

コード	意味
200	成功
400	無効なパラメーター
401	認証に失敗しました
403	アクセスが拒否されました
429	レート制限を超過しました

主なガイドライン

• 構造化データを取得するには、対応するソースで常に parse: true を設定してください
• 米国のEコマースの地理位置情報にはZIPコードを使用してください（例："90210"）
• 検索エンジンでは国／州の形式を使用してください（例："California,United States"）
• JavaScriptを多用するページでは render: "html" を追加してください
• 強制レンダリング対象のページで自動的な強制レンダリングを無効にする場合にのみ render: "" を使用してください。レンダリングを伴うRealtimeまたはProxy Endpointのリクエストでは、クライアントのタイムアウトを180秒前後に設定してください
• 画像URLをスクレイピングする場合は content_encoding: "base64" を追加し、ファイルを保存する前に results[0].content をデコードしてください