バックエンドからIPアドレスをルックアップする

指定したIPアドレスを、利用可能な国、地域、都市、おおよその座標データに解決します。Watch-IPのIPルックアップAPIはIPv4・IPv6の入力を受け付け、サードパーティのIPジオロケーションデータベースに基づくJSON結果を返します。サーバー上でシークレットAPIキーを使用し、明示的な一致、欠落レコード、null許容の位置情報フィールドを前提にアプリケーションを構築してください。

ルックアッププランを見るルックアップへのアクセスについて相談する →

解決したいアドレスを指定する

アプリケーションが取得したIPアドレスを指定し、Authorization: Bearerとシークレットキーで認証してGET /v1/lookup/{ip}を呼び出してください。このルックアップは、リクエストの送信に使われた接続ではなく、URL内のアドレスを解決します。そのため、レポート作成や地域エンリッチメントを含む、既にIPアドレスを保持しているバックエンドの業務フローに適しています。転送されたヘッダーに頼る前に、アプリケーションがどのようにエンドユーザーのIPを取得しているかを確認し、自社が管理するプロキシ経路のみを信頼してください。通常のウェブサイト訪問者の統合には、公開可能キーと地域エンリッチメントを備えたブラウザジオロケーションエンドポイントという別の方法があります。

単体アドレスからバッチへ

業務フローに複数のIPアドレスが含まれる場合、バッチエンドポイントは1回のリクエストで最大100件を受け付け、同じ順序で結果を返します。単体ルックアップと同じ結果形式、同じサーバーサイドのシークレットキー認証モデルを使用します。バッチ処理はリクエストの送信方法を変えるだけです—ルックアップの利用量は依然としてIPごとに計測されるため、1つのバッチが1単位のルックアップ利用量になるわけではありません。

おおよそのデータを前提に構築する

1つのIPは、共有ゲートウェイ、ホスティングネットワーク、VPN出口、モバイルキャリアの接続を表す場合があります。位置情報レコードは不完全であったり、データプロバイダーによって異なることがあります。ルックアップは、指定したアドレスに関する参考情報として利用し、個人の居住地や身元の証明としては利用しないでください。

レスポンスフィールド

ip: この結果に対応する入力アドレス。
found: 一致するデータベースレコードが見つかったかどうか。falseは、データベースが利用できない、または読み込まれていないことを意味する場合もあり、そのアドレスに位置情報データが存在しないことを証明するものではありません。
country, continent: 利用可能な場合の国・大陸コード。
region: 現在のマッピングによる区分の識別子であり、必ずしも完全な地域名ではありません。
city, latitude, longitude: 元データベースで利用可能な場合の、おおよその都市と座標。
postalCode, timezone: 現在の情報源データベースでは提供されません—常にnullです。

サーバーサイドのリクエストを送信する

cURL — GET /v1/lookup/{ip}

curl --fail-with-body \
  'https://api.watch-ip.com/v1/lookup/8.8.8.8' \
  --header "Authorization: Bearer ${WATCH_IP_SECRET_KEY}"

まずサーバーの環境変数にWATCH_IP_SECRET_KEYを設定してください。8.8.8.8は構文的に有効な例のアドレスであり、このスニペットは特定の国、都市、レスポンスを保証するものではありません。

よくある質問

このAPIを使って他人のIPアドレスをルックアップできますか?

このエンドポイントは指定されたIPアドレスを受け付け、利用可能なデータベースの位置情報を返しますが、個人の名前、正確な住所、身元は返しません。処理する権限があるデータのみをご利用ください。

IPv6に対応していますか?

このエンドポイントはIPv4とIPv6の入力を検証します。有効なアドレスでも、データベースレコードや一部の位置情報フィールドが欠落している場合があります。

ルックアップにはタイムゾーン、ASN、VPN検知が含まれますか?

いいえ。現在のルックアップレスポンスにはASNやセキュリティ指標は含まれず、その情報源データベースはタイムゾーンや郵便番号のフィールドを提供しません。接続元クライアントモデルがアプリケーションに合う場合は、訪問者ジオロケーションを別途ご確認ください。

ブラウザのJavaScriptからリクエストを送信できますか?

いいえ—ルックアップ用のシークレットをブラウザのコードに絶対に公開しないでください。ルックアップの呼び出しはバックエンドから行い、直接ブラウザでジオロケーションを行う場合は公開可能キーを使った訪問者エンドポイントをご利用ください。

これは無料の訪問者用キーに含まれていますか?

いいえ。ルックアップは別のシークレットキーとプランファミリーを使用します。訪問者向けの無料プランではサーバーサイドのルックアップへのアクセスは付与されません。

found: falseは何を意味しますか?

ルックアップが一致するレコードを返さなかったことを意味します。現在の実装ではデータベースが利用できない、または読み込まれていない場合にもこれが発生する可能性があるため、「位置情報が利用できません」と表示し、この結果を無効な入力、認証失敗、レート制限エラーとは区別してください。