> ## 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.

# 住所検証API：住所の実在確認と正規化

> DiditのPOST /v3/address-validation/は住所の実在を確認し、座標付きで正規化した住所を返します。構造化入力と1行入力に対応し、住所1件あたり$0.10です。

Diditの住所検証APIは、郵便住所が実在することを確認し、配送先住所行、住所の構成要素、座標とともに正規化された形で返します。バックエンドが保持している住所について、実在するかどうか、また正規化するとどのような形になるかを知る必要がある場合は、`POST /v3/address-validation/`を使用します。

住所検証が確認するのは住所のみです。住所を人物と紐付けることは決してありません。`verified`という結果は、その場所が実在することを意味し、誰かがそこに住んでいることを意味するものではありません。

## 住所を送信する

住所は`address`に1行で送信するか、構造化されたフィールドとして送信してください。構造化する場合は`address_line_1`と、利用可能であれば`address_line_2`、`city`、`region`、`postal_code`を使用します。
1つのリクエストで両方の形式を送信しないでください。
`country`は常に必須で、ISO 3166-1 alpha-2またはalpha-3コードで指定します。

## レスポンスを解釈する

* `address_validation.status`は、以降の処理の基準となる結果です。
  * `verified`: 住所が建物（または部屋や私書箱）の単位まで確認されました。
  * `partially_verified`: 通りの単位まで、またはその場所について郵便参照データが保持する最も詳細なレベルまでしか確認されませんでした。
  * `not_verified`: 一致したのは地域または都市のみであるか、何も一致しませんでした。
  * `unavailable`: 検証を実行できませんでした。後で再試行してください。
* `address_validation.verification_level`は、一致した最も詳細なレベルで、`administrative_area`、`locality`、`thoroughfare`、`premise`、`delivery_point`のいずれかです。
* `address_validation.address`と`address_validation.formatted_address`には、その国の表記方法に従って正規化された住所が格納されます。
* `address_validation.latitude`と`address_validation.longitude`は、一致した住所の位置を示します。
* `request_id`はリクエストを識別します。セッションは作成されず、結果はこのレスポンスでのみ返されるため、必要な情報は保存してください。

HTTPステータスは、`unavailable`を含め、完了したすべてのリクエストで`200`です。

## ワークフロー内での住所検証

同じチェックは、本人確認および住所証明のワークフローステップのアドオンとしても利用できます。
ステップの設定で`address_validation_enabled`を有効にすると、本人が提供した住所（本人確認書類または住所証明書類に記載されたもの）が、アップロードされた書類が読み取られると検証されます。
結果は、セッションの判定におけるそのステップのエントリ（`id_verifications[]`または`poa_verifications[]`）の`address_validation`オブジェクトに格納されます。
`partially_verified`または`not_verified`の住所は`ADDRESS_NOT_VERIFIED`警告を発生させます。その警告のアクションはステップの`address_not_verified_action`です（デフォルトは`NO_ACTION`で、警告を記録するだけです）。
`unavailable`の検証がこの警告を発生させることはなく、認証結果を変えることもありません。

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

サンドボックスキーはリクエストを検証し、送信したアドレスをそのまま返す決定論的な`verified`結果を常に返します。クレジットは消費しません。

## 請求

住所検証APIの呼び出しは、検証された住所1件あたり$0.10です。 `unavailable`の結果は課金されません。
ワークフローでは、アドオンの料金はステップが検証した住所1件あたり$0.10です。


## OpenAPI

````yaml ja/openapi-25.json POST /v3/address-validation/
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/address-validation/:
    post:
      tags:
        - Standalone APIs
      summary: 住所を検証する
      description: >-
        住所が実在することを確認し、正規化された住所（配送用の行、構成要素、座標）を返します。確認するのは住所のみで、住所を個人に紐付けることはありません。


        **リクエスト。**
        住所は1行（`address`）または構造化フィールド（`address_line_1`、および任意で`address_line_2`、`city`、`region`、`postal_code`）のいずれかで送信し、両方を送信しないでください。また、`country`（ISO
        3166-1 alpha-2またはalpha-3）を必ず含めてください。


        **結果。**
        `address_validation.status`は、`verified`（建物単位まで確認済み）、`partially_verified`（通り以上の単位でのみ確認済み）、`not_verified`（地域または市区町村のみ一致、または一致なし）、`unavailable`（検証を実行できなかった）のいずれかです。完了したすべてのリクエストでHTTPは`200`となり、`unavailable`も含まれます。`unavailable`の結果は後で再試行してください。


        **請求。**
        本番環境での呼び出しは、検証済み住所1件あたり$0.10です。`unavailable`の結果は課金されません。利用記録以外は何も保存されません。セッションは作成されず、結果はこのレスポンスでのみ返されます。


        **サンドボックス。**
        サンドボックスキーはリクエストを検証し、送信された住所をそのまま返す決定論的な`verified`結果を常に返します。クレジットは消費されません。


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


        **レート制限。**
        すべてのPOST/PATCH/DELETEエンドポイントで共有される書き込み枠として、APIキーごとに1分あたり300リクエストです。
      operationId: post_v3_address_validation
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddressValidationRequest'
            examples:
              Structured:
                summary: 構造化された住所フィールド
                value:
                  address_line_1: 1600 Amphitheatre Pkwy
                  city: Mountain View
                  region: CA
                  postal_code: '94043'
                  country: US
              One line:
                summary: 1行で表した住所全体
                value:
                  address: Paseo de la Castellana 259, 28046 Madrid
                  country: ES
      responses:
        '200':
          description: >-
            検証が完了しました。`address_validation.status`を確認してください。完了したリクエストのHTTPステータスは常に`200`です。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddressValidationResponse'
              examples:
                Verified:
                  summary: 建物単位まで確認された実在の住所
                  value:
                    request_id: 6f7d2c1e-1c5a-4a1e-9b8f-2a1f0f4b9c3d
                    address_validation:
                      status: verified
                      verification_level: premise
                      address:
                        address_line_1: 1600 Amphitheatre Pkwy
                        address_line_2: null
                        city: Mountain View
                        region: CA
                        postal_code: 94043-1351
                        country: US
                      formatted_address: 1600 Amphitheatre Pkwy, Mountain View CA 94043-1351
                      latitude: 37.422022
                      longitude: -122.08429
                    created_at: '2026-10-27T11:20:00.000000+00:00'
                Not verified:
                  summary: '架空の通り名: 市区町村のみが一致'
                  value:
                    request_id: 0b9e3f4a-6c2d-4e8b-a1f7-5d3c2b1a0e9f
                    address_validation:
                      status: not_verified
                      verification_level: locality
                      address:
                        address_line_1: Calle Inventada Que No Existe 99999 28046
                        address_line_2: null
                        city: Madrid
                        region: Madrid
                        postal_code: null
                        country: ES
                      formatted_address: >-
                        Calle Inventada Que No Existe 99999 28046, Madrid,
                        MADRID, SPAIN
                      latitude: 40.42603054
                      longitude: -3.68645331
                    created_at: '2026-10-27T11:21:00.000000+00:00'
                Unavailable:
                  summary: 検証を実行できませんでした。課金されません
                  value:
                    request_id: 3c1b2a0f-9e8d-4c7b-b6a5-1f0e9d8c7b6a
                    address_validation:
                      status: unavailable
                      verification_level: null
                      address: null
                      formatted_address: null
                      latitude: null
                      longitude: null
                    created_at: '2026-10-27T11:22:00.000000+00:00'
        '400':
          $ref: '#/components/responses/AddressValidationValidationError'
        '403':
          $ref: '#/components/responses/AddressValidationPermissionDenied'
        '429':
          $ref: '#/components/responses/RateLimitedWrite'
      security:
        - ApiKeyAuth: []
      x-codeSamples:
        - lang: curl
          label: curl
          source: |-
            curl -X POST https://verification.didit.me/v3/address-validation/ \
              -H 'x-api-key: YOUR_API_KEY' \
              -H 'Content-Type: application/json' \
              -d '{
                "address_line_1": "1600 Amphitheatre Pkwy",
                "city": "Mountain View",
                "region": "CA",
                "postal_code": "94043",
                "country": "US"
              }'
        - lang: python
          label: Python
          source: |-
            from didit import Didit

            # Reads DIDIT_API_KEY.
            client = Didit()

            result = client.address_validation.validate(
                address_line_1="1600 Amphitheatre Pkwy",
                city="Mountain View",
                region="CA",
                postal_code="94043",
                country="US",
            )
            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.addressValidation.validate({
              address_line_1: "1600 Amphitheatre Pkwy",
              city: "Mountain View",
              region: "CA",
              postal_code: "94043",
              country: "US",
            });
            console.log(result);
        - lang: java
          label: Java
          source: >-
            import me.didit.Didit;

            import me.didit.types.AddressValidationRequest;


            // Reads DIDIT_API_KEY.

            Didit client = new Didit();


            var result =
            client.addressValidation().validate(AddressValidationRequest.builder()
                    .addressLine1("1600 Amphitheatre Pkwy")
                    .city("Mountain View")
                    .region("CA")
                    .postalCode("94043")
                    .country("US")
                    .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->addressValidation->validate([
                'address_line_1' => '1600 Amphitheatre Pkwy',
                'city' => 'Mountain View',
                'region' => 'CA',
                'postal_code' => '94043',
                'country' => 'US',
            ]);
            print_r($result->toArray());
        - lang: ruby
          label: Ruby
          source: |-
            require "didit"

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

            result = didit.address_validation.validate(
              address_line_1: "1600 Amphitheatre Pkwy",
              city: "Mountain View",
              region: "CA",
              postal_code: "94043",
              country: "US"
            )
            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.AddressValidation.ValidateAsync(new
            AddressValidationRequest

            {
                AddressLine1 = "1600 Amphitheatre Pkwy",
                City = "Mountain View",
                Region = "CA",
                PostalCode = "94043",
                Country = "US",
            });

            Console.WriteLine(JsonSerializer.Serialize(result));
components:
  schemas:
    AddressValidationRequest:
      type: object
      required:
        - country
      description: >-
        住所1件。1行（`address`）、または少なくとも`address_line_1`を含む構造化フィールドのいずれかで指定します。両方を指定することはできません。
      properties:
        address:
          type: string
          maxLength: 500
          description: 1行で表した住所全体。
          example: Paseo de la Castellana 259, 28046 Madrid
        address_line_1:
          type: string
          maxLength: 255
          description: 通り名と番地。
          example: 1600 Amphitheatre Pkwy
        address_line_2:
          type: string
          maxLength: 255
          description: 部屋番号、スイート、階、または建物名。
        city:
          type: string
          maxLength: 128
          description: 都市または地域。
          example: Mountain View
        region:
          type: string
          maxLength: 128
          description: 州、県、または地域。
          example: CA
        postal_code:
          type: string
          maxLength: 32
          example: '94043'
        country:
          type: string
          maxLength: 3
          description: 住所の国を示すISO 3166-1 alpha-2またはalpha-3コード。
          example: US
    AddressValidationResponse:
      type: object
      required:
        - request_id
        - address_validation
        - created_at
      properties:
        request_id:
          type: string
          format: uuid
          description: このリクエストの識別子です。サポートへの問い合わせ時に伝えてください。セッションは作成されません。
        address_validation:
          $ref: '#/components/schemas/AddressValidationResult'
        created_at:
          type: string
          format: date-time
    AddressValidationResult:
      type: object
      description: >-
        1件のAddress
        Validationの結果です。住所が存在するかどうかと、その正規化された形式を示します。住所の確認のみを行い、住所を個人と紐付けることはありません。
      required:
        - status
        - verification_level
        - address
        - formatted_address
        - latitude
        - longitude
      properties:
        status:
          type: string
          enum:
            - verified
            - partially_verified
            - not_verified
            - unavailable
          description: >-
            `verified`：住所が建物単位（または部屋番号や私書箱単位）まで確認されました。`partially_verified`：通りまで、またはその場所について郵便参照データが保持する最も詳細なレベルまでしか確認されませんでした。`not_verified`：地域または市区町村のみが一致したか、何も一致しませんでした。`unavailable`：検証を実行できませんでした（例：参照サービスが応答しなかった場合）。この場合は課金されず、認証に影響することはありません。
        verification_level:
          type: string
          nullable: true
          enum:
            - administrative_area
            - locality
            - thoroughfare
            - premise
            - delivery_point
            - null
          description: 住所が一致した最も詳細なレベルです。何も一致しなかった場合、または`status`が`unavailable`の場合は`null`です。
        address:
          type: object
          nullable: true
          description: 正規化済みの住所。`status`が`unavailable`の場合は`null`です。
          properties:
            address_line_1:
              type: string
              nullable: true
              description: 配送先住所の1行目です。その国の表記どおりに記載します。
              example: 1600 Amphitheatre Pkwy
            address_line_2:
              type: string
              nullable: true
              description: 住所に2行目がある場合の配送先情報の2行目（部屋番号、建物名、地区名など）。
            city:
              type: string
              nullable: true
              example: Mountain View
            region:
              type: string
              nullable: true
              description: 州、県、または地域。
              example: CA
            postal_code:
              type: string
              nullable: true
              example: 94043-1351
            country:
              type: string
              nullable: true
              description: ISO 3166-1 alpha-2国コード。
              example: US
        formatted_address:
          type: string
          nullable: true
          description: 1行にまとめた正規化済みの住所。
          example: 1600 Amphitheatre Pkwy, Mountain View CA 94043-1351
        latitude:
          type: number
          nullable: true
          example: 37.422022
        longitude:
          type: number
          nullable: true
          example: -122.08429
  responses:
    AddressValidationValidationError:
      description: 'リクエストボディが無効です: `country`がないか不明、住所がない、または`address`と構造化フィールドの両方が指定されています。'
      content:
        application/json:
          examples:
            Unknown country:
              value:
                country:
                  - >-
                    Use an ISO 3166-1 alpha-2 or alpha-3 country code, e.g. 'US'
                    or 'USA'.
            No address:
              value:
                address:
                  - >-
                    Send the address: 'address' on one line, or the structured
                    fields with 'address_line_1'.
            Both shapes:
              value:
                address:
                  - >-
                    Send either 'address' or the structured fields
                    (address_line_1, ...), not both.
    AddressValidationPermissionDenied:
      description: >-
        APIキーがないか無効である、スコープ付きキーに`sessions`の書き込みアクセス権がない、または組織が検証の費用を賄えません。このAPIが`401`を返すことはありません。
      content:
        application/json:
          examples:
            Missing or invalid API key:
              value:
                detail: You do not have permission to perform this action.
            Not enough credits:
              value:
                detail: >-
                  You don't have enough credits to perform this request. Please
                  top up at https://business.didit.me
                code: insufficient_credits
    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.