> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# IPリスクAPI：位置情報・VPN・データセンター判定

> DiditのIPリスクAPIは、位置情報、ISP、VPN/Tor、データセンター、脅威、申告国との不一致といったシグナルからIPアドレスのリスクをスコアリングします。

`POST /v3/ip/risk/`は、バックエンドがすでにIPアドレスを保持しており、サーバー間でリスク判定を行う必要がある場合に使用します。

レスポンスには、位置情報、ネットワークの所有者情報、VPN/Torおよびデータセンターのフラグ、脅威データが含まれます。申告された国を送信した場合は`country_mismatch`も含まれます。

## レスポンスの解釈

* `status`は、解決された国が`claimed_country`と一致しない場合、またはアドレスがVPN、Tor、データセンターのインフラに関連付けられている場合に`In Review`になります。それ以外の場合は`Approved`です。
* `ip.ip_country_code`には解決された国コードが入ります。国の比較は、生の国名文字列を自分で比較するのではなく、`ip.country_mismatch`を使って行ってください。
* `ip.latitude`と`ip.longitude`はネットワークに基づくおおよその位置情報であり、デバイスの正確な位置ではありません。
* `ip.is_vpn_or_tor`、`ip.is_data_center`、`ip.proxy_type`、`ip.threat`には、ネットワークリスクの根拠が含まれます。
* `ip.asn_number`、`ip.asn_organization`、`ip.connection_type`、`ip.carrier`は、アドレスが属するネットワークを表します。
* `request_id`はAPIセッションIDです。結果を後続のWebhookやコンソール上のアクティビティと紐付ける必要がある場合は、`vendor_data`と一緒に保存してください。

> [!NOTE]
>
> IP情報の付加はベストエフォートです。どの情報源からも使用可能なデータが返されない場合、エンドポイントは`ip.ip_address: null`、`ip.country_mismatch: null`、空の`ip.threat`オブジェクトを含む承認済みのレスポンスを返します。また、取得できない場合は個々のフィールドが`null`になることもあります。

## デバイスインテリジェンス

IP Risk APIはサーバー間でのみ利用するエンドポイントです。デバイスフィンガープリントはそうではありません。バックエンドだけではブラウザやデバイスのシグナルを観測できないためです。ホスト型フローおよびSDKのセッションでは、Diditは収集済みのデバイスフィールドをセッションのレスポンスで提供します。これには`device_fingerprint`、デバイスとブラウザの詳細、`user_agent`、未加工のデバイスデータ、セッション間の一致が含まれます。

## サンドボックスでの動作

サンドボックスキーはリクエストを検証し、決定論的な承認済みデータを返します。外部のインテリジェンスサービスへの接続、クレジットの消費、セッションの作成、Networksへのデータ提供は行いません。

## 請求

IP Risk APIの呼び出し1回あたりの料金は、定価で\$0.02です。本番環境のリクエストは、照会が開始された時点で課金対象になります。


## OpenAPI

````yaml ja/openapi-25.json POST /v3/ip/risk/
openapi: 3.0.0
info:
  version: 3.0.0
  title: Didit Verification API
  description: 本人確認API。x-api-keyヘッダーで認証します。
servers:
  - url: https://verification.didit.me
security: []
tags: []
paths:
  /v3/ip/risk/:
    post:
      tags:
        - Standalone APIs
      summary: IPアドレスのリスクをスコアリングする
      description: >-
        指定されたIPアドレスについて、位置情報、ネットワークの所有構造、VPN/Torおよびデータセンターのフラグ、脅威データ、`country_mismatch`を返します。このエンドポイントはAPIセッションを作成し、そのIDを`request_id`として返します。


        **判定。**
        特定された国が`claimed_country`と矛盾する場合、またはアドレスがVPN、Tor、データセンターのインフラに関連付けられている場合、`status`は`In
        Review`になります。それ以外の場合は`Approved`です。


        **ベストエフォート。**
        IPのエンリッチメントはベストエフォートで行われます。どのエンリッチメントソースからも利用可能なデータが返されなかった場合、このエンドポイントは`ip.ip_address:
        null`、`ip.country_mismatch: null`、空の`ip.threat`オブジェクトを含む承認済みのレスポンスを返します。


        **請求。** 本番環境での呼び出しにはIP Risk APIの料金が適用されます。照会が開始された時点でリクエストは課金対象になります。


        **サンドボックス。**
        サンドボックスのキーはリクエストを検証し、クレジットの消費、セッションの作成、Networksへの寄与を行わずに、決定論的な承認済みデータを返します。


        **認証。**
        アプリケーションのAPIキーを`x-api-key`で送信してください。認証情報がない場合や無効な場合は`403`が返されます。このAPIが`401`を返すことはありません。


        **レート制限。**
        すべてのPOST/PATCH/DELETEエンドポイントで共有される書き込み枠として、APIキーごとに1分あたり300リクエストです。
      operationId: post_v3ip_risk
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IPRiskRequest'
            examples:
              Minimal:
                summary: デフォルト設定で住所をスコアリング
                value:
                  ip_address: 8.8.8.8
              With claimed country:
                summary: 不一致検出のために申告された国を指定してスコアリング
                value:
                  ip_address: 8.8.8.8
                  claimed_country: ESP
                  user_agent: >-
                    Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)
                    AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.4
                    Safari/605.1.15
                  vendor_data: lead-123
      responses:
        '200':
          description: リスク評価が完了しました。判定は`status`で確認してください。完了したルックアップでは、HTTPは常に`200`です。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IPRiskResponse'
              examples:
                Clean residential IP:
                  summary: 居住住所、申告された国が一致
                  value:
                    request_id: 9a96ed2a-721e-4b86-8cbf-d61eda529279
                    status: Approved
                    ip:
                      status: Approved
                      ip_address: 192.0.2.10
                      ip_country: Spain
                      ip_country_code: ES
                      ip_state: Madrid
                      ip_city: Madrid
                      latitude: 40.4168
                      longitude: -3.7038
                      isp: Example Telecom
                      organization: Example Telecom SA
                      is_vpn_or_tor: false
                      is_data_center: false
                      time_zone: Europe/Madrid
                      time_zone_offset: '+0200'
                      asn_number: 3352
                      asn_organization: EXAMPLE-TELECOM
                      connection_type: broadband
                      carrier: Example Telecom
                      proxy_type: null
                      claimed_country: ESP
                      country_mismatch: false
                      threat: {}
                    vendor_data: lead-123
                    metadata: null
                    created_at: '2026-09-01T10:30:00.123456+00:00'
                Datacenter mismatch:
                  summary: 申告された国と矛盾するデータセンターの住所
                  value:
                    request_id: 5b1d4e9a-3c7b-4f8e-9a2d-1b0c9d8e7f6a
                    status: In Review
                    ip:
                      status: In Review
                      ip_address: 8.8.8.8
                      ip_country: United States
                      ip_country_code: US
                      ip_state: California
                      ip_city: Mountain View
                      latitude: 37.386
                      longitude: -122.0838
                      isp: Google
                      organization: Google LLC
                      is_vpn_or_tor: true
                      is_data_center: true
                      time_zone: America/Los_Angeles
                      time_zone_offset: '-0700'
                      asn_number: 15169
                      asn_organization: GOOGLE, US
                      connection_type: hosting
                      carrier: null
                      proxy_type: VPN
                      claimed_country: ESP
                      country_mismatch: true
                      threat:
                        is_proxy: true
                        is_data_center: true
                        is_tor: false
                    vendor_data: lead-126
                    metadata: null
                    created_at: '2026-09-01T10:30:00.123456+00:00'
        '400':
          $ref: '#/components/responses/IPRiskValidationError'
        '403':
          $ref: '#/components/responses/RiskPermissionDenied'
        '429':
          $ref: '#/components/responses/RateLimitedWrite'
      security:
        - ApiKeyAuth: []
      x-codeSamples:
        - lang: curl
          label: curl
          source: |-
            curl -X POST https://verification.didit.me/v3/ip/risk/ \
              -H 'x-api-key: YOUR_API_KEY' \
              -H 'Content-Type: application/json' \
              -d '{
                "ip_address": "8.8.8.8",
                "claimed_country": "ESP",
                "user_agent": "Mozilla/5.0",
                "vendor_data": "lead-123"
              }'
        - lang: python
          label: Python
          source: |-
            from didit import Didit

            # Reads DIDIT_API_KEY.
            client = Didit()

            result = client.ip.assess_risk(
                ip_address="8.8.8.8",
            )
            print(result)
        - lang: javascript
          label: Node.js
          source: |-
            import Didit from "@didit-protocol/sdk-node";

            // Reads DIDIT_API_KEY.
            const didit = new Didit();

            const result = await didit.ip.assessRisk({
              ip_address: "8.8.8.8",
            });
            console.log(result);
        - lang: go
          label: Go
          source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.IP.AssessRisk(ctx, didit.IPRiskRequest{\n\tIPAddress: \"8.8.8.8\",\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)"
        - lang: java
          label: Java
          source: |-
            import me.didit.Didit;
            import me.didit.types.IPRiskRequest;

            // Reads DIDIT_API_KEY.
            Didit client = new Didit();

            var result = client.ip().assessRisk(IPRiskRequest.builder()
                    .ipAddress("8.8.8.8")
                    .build());
            System.out.println(result);
        - lang: php
          label: PHP
          source: |-
            <?php

            require 'vendor/autoload.php';

            use Didit\DiditClient;

            // Reads DIDIT_API_KEY.
            $didit = new DiditClient();

            $result = $didit->ip->assessRisk([
                'ip_address' => '8.8.8.8',
            ]);
            print_r($result->toArray());
        - lang: ruby
          label: Ruby
          source: |-
            require "didit"

            # Reads DIDIT_API_KEY.
            didit = Didit::Client.new

            result = didit.ip.assess_risk(ip_address: "8.8.8.8")
            puts result.to_h
        - lang: csharp
          label: .NET
          source: |-
            using System;
            using System.Text.Json;
            using Didit;

            // Reads DIDIT_API_KEY.
            using var client = new DiditClient();

            var result = await client.Ip.AssessRiskAsync(new IPRiskRequest
            {
                IpAddress = "8.8.8.8",
            });
            Console.WriteLine(JsonSerializer.Serialize(result));
components:
  schemas:
    IPRiskRequest:
      type: object
      required:
        - ip_address
      properties:
        ip_address:
          type: string
          format: ip
          description: スコアリング対象のIPv4またはIPv6アドレス。
          example: 8.8.8.8
        claimed_country:
          type: string
          maxLength: 3
          description: >-
            ユーザーまたはセッションが申告した任意のISO 3166-1
            alpha-2またはalpha-3の国です。`country_mismatch`の算出に使用されます。
          example: ESP
        user_agent:
          type: string
          maxLength: 512
          description: バックエンドで観測されたユーザーエージェント。リクエストのコンテキストとして保存されます。デバイスフィンガープリントは提供しません。
        vendor_data:
          type: string
          description: このリクエストに対する固定の参照値です。APIセッションに保存され、レスポンスでそのまま返されます。
        metadata:
          type: object
          nullable: true
          additionalProperties: true
          description: 機密性のないJSONメタデータです。APIセッションに保存され、レスポンスでそのまま返されます。
    IPRiskResponse:
      type: object
      required:
        - request_id
        - status
        - created_at
      properties:
        request_id:
          type: string
          format: uuid
          description: >-
            このリクエストで作成されたAPIセッションのID。結果を後続のWebhookやコンソール上のアクティビティと関連付ける必要がある場合は、`vendor_data`とともに保存してください。
        status:
          type: string
          enum:
            - Approved
            - In Review
          description: このAPIセッションの判定。ネットワークまたは国の不一致リスクがある場合は`In Review`、それ以外は`Approved`です。
        vendor_data:
          type: string
          nullable: true
          description: 送信した`vendor_data`のエコー。送信しなかった場合は`null`です。
        metadata:
          type: object
          nullable: true
          additionalProperties: true
          description: 送信した`metadata`のエコー。送信しなかった場合は`null`です。
        created_at:
          type: string
          format: date-time
          description: このレスポンスの日時。
        ip:
          type: object
          description: IPリスクの結果。照会で利用可能なデータが返されなかった場合、個々のエンリッチメントフィールドは`null`になることがあります。
          required:
            - status
            - threat
          properties:
            status:
              type: string
              enum:
                - Approved
                - In Review
              description: >-
                特定された国が`claimed_country`と矛盾する場合、またはそのアドレスがVPN、Tor、データセンターのインフラに関連付けられている場合は`In
                Review`です。それ以外は`Approved`です。
            ip_address:
              type: string
              nullable: true
              description: スコアリングされたアドレスです。どのエンリッチメントソースからも利用可能なデータが返されなかった場合は`null`になります。
            ip_country:
              type: string
              nullable: true
              description: 特定された国名。
            ip_country_code:
              type: string
              nullable: true
              description: >-
                特定された国コード。国を比較する際は、生の国名文字列を自分で比較するのではなく、`country_mismatch`を使用してください。
            ip_state:
              type: string
              nullable: true
              description: 特定された州または地域。
            ip_city:
              type: string
              nullable: true
              description: 特定された都市。
            latitude:
              type: number
              nullable: true
              description: ネットワークに基づくおおよその位置情報であり、デバイスの正確な位置ではありません。
            longitude:
              type: number
              nullable: true
              description: ネットワークに基づくおおよその位置情報であり、デバイスの正確な位置ではありません。
            isp:
              type: string
              nullable: true
              description: そのアドレスにサービスを提供しているインターネットサービスプロバイダー。
            organization:
              type: string
              nullable: true
              description: アドレスブロックを所有する組織です。
            is_vpn_or_tor:
              type: boolean
              nullable: true
              description: このアドレスがVPNまたはTorのインフラに関連付けられている場合は`true`です。
            is_data_center:
              type: boolean
              nullable: true
              description: このアドレスがホスティングまたはデータセンターのネットワークに属している場合は`true`です。
            time_zone:
              type: string
              nullable: true
              description: 特定された位置のタイムゾーン。
            time_zone_offset:
              type: string
              nullable: true
              description: 特定された位置のUTCオフセット。
            asn_number:
              type: number
              nullable: true
              description: 自律システム番号。
            asn_organization:
              type: string
              nullable: true
              description: 自律システムを運用している組織です。
            connection_type:
              type: string
              nullable: true
              description: 接続の分類（例：`cellular`、`hosting`）。
            carrier:
              type: string
              nullable: true
              description: アドレスがモバイルネットワーク上にある場合の携帯通信事業者。
            proxy_type:
              type: string
              nullable: true
              description: アドレスがプロキシの背後にある場合のプロキシ分類です。
            claimed_country:
              type: string
              nullable: true
              description: 送信した`claimed_country`のエコー。
            country_mismatch:
              type: boolean
              nullable: true
              description: >-
                判定された国が`claimed_country`と異なる場合は`true`です。エンリッチメントデータまたは申告された国が利用できない場合は`null`になります。
            threat:
              type: object
              additionalProperties: true
              description: >-
                エンリッチメントソースから得られる自由形式のネットワーク脅威の証拠（例：`is_proxy`、`is_tor`）。エンリッチメントデータがない場合は空のオブジェクトになります。安定した仕様ではなく、診断用の詳細情報として扱ってください。
  responses:
    IPRiskValidationError:
      description: リクエストのバリデーションに失敗しました。
      content:
        application/json:
          examples:
            Missing IP address:
              summary: IPアドレスがありません
              value:
                ip_address:
                  - This field is required.
            Invalid IP address:
              summary: 無効なIPアドレス
              value:
                ip_address:
                  - Enter a valid IPv4 or IPv6 address.
            Country hint too long:
              summary: 国のヒントが長すぎます
              value:
                claimed_country:
                  - Ensure this field has no more than 3 characters.
    RiskPermissionDenied:
      description: APIキーがないか無効である、または組織がライブ照会の費用を賄えません。このAPIが`401`を返すことはありません。
      content:
        application/json:
          examples:
            Missing or invalid API key:
              summary: '`x-api-key`ヘッダーがないか、キーが無効または失効しています'
              value:
                detail: You do not have permission to perform this action.
            Not enough credits:
              summary: 組織の残高で照会料金を賄えません
              value:
                error: You don't have enough credits to perform this request.
    RateLimitedWrite:
      description: APIキーあたり毎分300リクエストの共有書き込み制限を超えました。再試行する前に`Retry-After`に従ってください。
      content:
        application/json:
          schema:
            type: object
            required:
              - detail
            properties:
              detail:
                type: string
          example:
            detail: >-
              Write request rate limit exceeded. You can make up to 300 requests
              per minute.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        お客様のアプリケーションのAPIキーです。Business ConsoleのDevelopers -> API
        keysで取得できます。プライマリキーはフルアクセス権を持ちます。名前付きキーにはスコープを設定できます。リソースごとのアクセス権（なし、読み取り、書き込み）、一部のワークフローまたは承認済みセッションへの限定、IPアドレスのリストへの限定、有効期限の設定です。401は、キーが誤っている、失効している、または期限切れであることを意味します。403は、キーが送信されていない、キーにこのリソースやアクションへのアクセス権がない、またはIPリスト外のアドレスからリクエストが送信されたことを意味します。セッションのルートでの404は、セッションがキーのワークフローまたはステータスの対象外であることを意味します。メディアへのアクセス権がないキーでは、画像、動画、PDFのURLがnullで返されます。セッションの書き込み権限がないキーでは、セッションのリンクとトークンがnullで返されます。詳細は次を参照してください:
        https://docs.didit.me/console/api-keys

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.