1. Oracle Address, Email, and Phone Verificationの使用
  2. 住所検証REST APIの使用
機械翻訳について

住所検証REST APIの使用

住所検証では、アプリケーションでグローバル住所を検索して検証できます。

このビデオでは、REST API機能の概要をご覧いただけます。

トピック

住所の検索

住所検証には、先行入力住所検索および住所補完の機能が含まれます。 この機能は、バージョン2 (v2)およびバージョン3 (v3)で使用可能な3つのエンドポイントで提供されます。 新規ユーザーはv3をご使用ください。

検索APIは、間接モードまたは直接モードのいずれかで使用できます。

間接モード

RESTエンドポイント:

/api/v3/address/find

/api/v3/address/retrieve

間接モードの場合、クライアントはサードパーティ・プロバイダを直接コールしません。クライアントはOracle Address Verification Serviceとのみ対話します。 その後、Oracleはfindコールをサードパーティ・プロバイダに転送します。

最初に、検索を絞り込むためにfindがコールされ、次にretrieveがコールされて完全な住所レコードを取得します。 このモードではfindのパフォーマンスが遅くなるため、可能な場合は常に直接モードを使用することをお薦めします。

直接モード

RESTエンドポイント:

/api/v3/address/preparefind

/api/v3/address/retrieve

ここで、クライアントは最初にアプリケーション・ページの初期化時にpreparefindをコールします。 preparefindへの応答として、クライアントは、サードパーティ・アプリケーションでfindコールを直接実行するための情報および資格証明を受信します。 Retrieveが、サードパーティ・アプリケーションではなく検証エンドポイントに対して再度実行されます(この後の項のユース・ケースを参照)。

単純検索のユース・ケース
目的のUS住所の最初の3文字を「123」のように入力するとすぐに最初のfind要求が発行されるとします。 結果の要求および応答は次のとおりです。
ノート: 例は間接モードを示しています。 機能は直接モードでも同じですが、最初にpreparefindを使用します。
要求 
http://adc00qrw.oracle.com:7767/av/api/v3/address/find?Text=123
応答 
[
  {
    "Id": "US|US|ENG|94107-CA-SAN_FRANCISCO--ST-TOWNSEND--123",
    "Type": "BuildingNumber",
    "Text": "123 Townsend St",
    "Highlight": "0-3",
    "Description": "San Francisco CA 94107 - 320 Addresses"
  },
  {
    "Id": "US|US|ENG|94105-CA-SAN_FRANCISCO--ST-MISSION--123",
    "Type": "BuildingNumber",
    "Text": "123 Mission St",
    "Highlight": "0-3",
    "Description": "San Francisco CA 94105 - 48 Addresses"
  },
  {
    "Id": "US|US|A|Z222445177|123",
    "Type": "Address",
    "Text": "123 2nd St",
    "Highlight": "0-3",
    "Description": "San Francisco CA 94105"
  },
  {
    "Id": "US|US|A|Z222445178|1",
    "Type": "Address",
    "Text": "123 2nd St Ste 1",
    "Highlight": "0-3",
    "Description": "San Francisco CA 94105"
  },
  {
    "Id": "US|US|A|Z223933823|123",
    "Type": "Address",
    "Text": "123 Mission St",
    "Highlight": "0-3",
    "Description": "San Francisco CA 94105"
  },
  {
    "Id": "US|US|ENG|94103-CA-SAN_FRANCISCO--ST-GUERRERO--123",
    "Type": "BuildingNumber",
    "Text": "123 Guerrero St Apt",
    "Highlight": "0-3",
    "Description": "San Francisco CA 94103 - 3 Addresses"
  },
  {
    "Id": "US|US|A|Z222437371|123",
    "Type": "Address",
    "Text": "123 Guerrero St",
    "Highlight": "0-3",
    "Description": "San Francisco CA 94103"
  },
  {
    "Id": "US|US|A|Z222457206|123",
    "Type": "Address",
    "Text": "123 Waverly Pl",
    "Highlight": "0-3",
    "Description": "San Francisco CA 94108"
  },
  {
    "Id": "US|US|A|Z222454357|123",
    "Type": "Address",
    "Text": "123 Joice St",
    "Highlight": "0-3",
    "Description": "San Francisco CA 94108"
  },
  {
    "Id": "US|US|ENG|94108-CA-SAN_FRANCISCO--ST-JOICE--123",
    "Type": "BuildingNumber",
    "Text": "123 Joice St Apt",
    "Highlight": "0-3",
    "Description": "San Francisco CA 94108 - 4 Addresses"
  }
]

郵送先住所は、TypeフィールドがAddressに設定されているすべてのJSONオブジェクトの応答に含まれています。 この単純なユース・ケースでは、ユーザー・インタフェースで他のすべてのタイプ(BuildingNumber、Streetなど)を抑制し、住所オブジェクトのみを表示できます。

住所"123 Guerrero St"を見つけるには、クリックします。 これにより、クライアント・アプリケーションは/address/retrieveエンドポイントに要求を発行し、値US|US|A|Z222437371|123が設定されたIDパラメータを渡して完全な住所レコードを取得します。

そうでない場合は住所の入力を続行する必要がありますが、UIは必要な住所が見つかるまで同等のfind要求を引き続き発行します。

住所の取得

IDが取得されたら、パラメータとしてそのIDが指定された/address/retrieveエンドポイントをコールすることで、この住所の完全かつコンポーネント化された情報を取得できます。

この単純なfindのユース・ケースでは次の結果が生成されます。

要求 
http://adc00qrw.oracle.com:7767/av/api/v3/address/retrieve?Id=US|US|A|Z222437371|123
応答 
[
    {
        "Id": "US|US|A|Z222437371|123",
        "Premise": "123",
        "Thoroughfare": "Guerrero St",
        "Locality": "San Francisco",
        "DeliveryAddress1": "123 Guerrero St",
        "SubAdministrativeArea": "San Francisco",
        "AdministrativeArea": "CA",
        "AdministrativeAreaName": "California",
        "PostalCode": "94103-1072",
        "CountryName": "United States",
        "ISO3166-2": "US",
        "ISO3166-3": "USA",
        "ISO3166-N": "840",
        "Address": "123 Guerrero St|SAN FRANCISCO CA 94103-1072",
        "DeliveryAddress": "123 Guerrero St",
        "Address1": "123 Guerrero St",
        "Address2": "SAN FRANCISCO CA 94103-1072",
        "PostalCodePrimary": "94103",
        "PostalCodeSecondary": "1072"
    }
]
拡張検索のユース・ケース
米国で住所"941 Dolores St, unit #3"を検索する必要があり、文字"941"と入力し始めたとします。 UIによって開始された対応するRESTトランザクションが、要求1および応答1に示されています。
ノート: 例は間接モードを示しています。 機能は直接モードでも同じですが、最初にpreparefindを使用します。

この場合、UIではType=Addressのみでなく、すべてのタイプのレコードを考慮します。 応答1の結果を見て、文字の入力をさらに続行せず、かわりにTypeがBuildingNumberである"Dolores St Apt"という結果を選択しました。 UIは、これが住所の最終選択ではなく、さらに4つの住所を含む結果のいずれかへのドリルダウンであることを理解する必要があります。 これは、要求2に示すように、結果のIDを使用してContainerパラメータとして新しい要求に渡すことによって行われます。 応答2では、前の結果は表示されなくなりますが、4つのアパートがすべて表示されます。

3番目のユニットが表示されたら、ID値US|US|A|Z222467771|3を使用して/address/retrieveエンドポイントをコールしてレコードを取得します。

要求1 
http://adc00qrw.oracle.com:7767/av/api/v3/address/find?Text=941
応答1 
[
 {
 "Id": "US|US|A|Z222467773|941",
 "Type": "Address",
 "Text": "941 Dolores St",
 "Highlight": "0-3",
 "Description": "San Francisco CA 94110"
 },
 {
 "Id": "US|US|ENG|94110-CA-SAN_FRANCISCO--ST-DOLORES--941",
 "Type": "BuildingNumber",
 "Text": "941 Dolores St Apt",
 "Highlight": "0-3",
 "Description": "San Francisco CA 94110 - 4 Addresses"
 },
 {
 "Id": "US|US|ENG|94117-CA-SAN_FRANCISCO--ST-PAGE--941",
 "Type": "BuildingNumber",
 "Text": "941 Page St Apt",
 "Highlight": "0-3",
 "Description": "San Francisco CA 94117 - 5 Addresses"
 },
 {
 "Id": "US|US|A|Z222490758|941",
 "Type": "Address",
 "Text": "941 Page St",
 "Highlight": "0-3",
 "Description": "San Francisco CA 94117"
 },
 {
 "Id": "US|US|A|Z222412877|941",
 "Type": "Address",
 "Text": "941 Ridgeview Ct Unit",
 "Highlight": "0-3",
 "Description": "South San Francisco CA 94080"
 },
 {
 "Id": "US|US|A|Z222412876|941",
 "Type": "Address",
 "Text": "941 Ridgeview Ct",
 "Highlight": "0-3",
 "Description": "South San Francisco CA 94080"
 },
 {
 "Id": "US|US|A|Z213529633|941",
 "Type": "Address",
 "Text": "941 Shorepoint Ct",
 "Highlight": "0-3",
 "Description": "Alameda CA 94501"
 },
 {
 "Id": "US|US|ENG|94501-CA-ALAMEDA--CT-SHOREPOINT--941",
 "Type": "BuildingNumber",
 "Text": "941 Shorepoint Ct Apt",
 "Highlight": "0-3",
 "Description": "Alameda CA 94501 - 146 Addresses"
 },
 {
 "Id": "US|US|ENG|94608-CA-EMERYVILLE--ST-37TH--941",
 "Type": "BuildingNumber",
 "Text": "941 37th St Apt",
 "Highlight": "0-3",
 "Description": "Emeryville CA 94608 - 5 Addresses"
 },
 {
 "Id": "US|US|A|Z224475658|941",
 "Type": "Address",
 "Text": "941 Aileen St",
 "Highlight": "0-3",
 "Description": "Emeryville CA 94608"
 }
]
要求2 
http://adc00qrw.oracle.com:7767/av/api/v3/address/find?Text=941&Container=US|US|ENG|94110-CA-SAN_FRANCISCO--ST-DOLORES--941
応答2 
[[
 {
 "Id": "US|US|A|Z222467771|1",
 "Type": "Address",
 "Text": "941 Dolores St Apt 1",
 "Highlight": "",
 "Description": "San Francisco CA 94110"
 },
 {
 "Id": "US|US|A|Z222467771|2",
 "Type": "Address",
 "Text": "941 Dolores St Apt 2",
 "Highlight": "",
 "Description": "San Francisco CA 94110"
 },
 {
 "Id": "US|US|A|Z222467771|3",
 "Type": "Address",
 "Text": "941 Dolores St Apt 3",
 "Highlight": "",
 "Description": "San Francisco CA 94110"
 },
 {
 "Id": "US|US|A|Z222467771|4",
 "Type": "Address",
 "Text": "941 Dolores St Apt 4",
 "Highlight": "",
 "Description": "San Francisco CA 94110"
 },
 {
 "Id": "US|US|A|Z222467772|A",
 "Type": "Address",
 "Text": "941 Dolores St Apt A",
 "Highlight": "",
 "Description": "San Francisco CA 94110"
 }
]

詳細は、Oracle Address, Email, and Phone VerificationのREST APIを参照してください。

住所の検証

住所検証を使用して次のことができます。

  • 住所を修正および補正します。 たとえば、入力に誤りがある市区町村や番地名を修正し、完全な郵便番号や都道府県など、欠落している要素を追加し、緯度、経度などの地理的な場所を取得できます。

  • 郵便ファイルから住所の正確な表記を取得します。 たとえば、「street」を「St」、「parkw」を「Pkwy」に変更します。

  • outputscript (v2)またはOutputScript (v3)を使用して住所を音訳します。 次の値がサポートされています。

    • Native: その国で最もよく使用されるスクリプトで出力を返します(次を参照)。

    • Latn: ラテン・アルファベット(英語)で出力を返します。

    • 値なし(デフォルト): 住所出力スクリプトを、住所入力スクリプトとして指定されたものと一致させるよう試行します。

    たとえば、ラテン・スクリプトで日本の住所を入力し、検証済出力をHaniスクリプトで取得します。 これは特定の国の住所に対してサポートされています。

    ネイティブ・スクリプト(ISOおよびフル・ネーム)と、これがサポートされていることが知られている国を次に紹介します。

    • Latn - ラテン語(可能な場合は英語表記に変換)

    • Cyrl - キリル言語(ロシア)

    • Grek - ギリシャ語(ギリシャ)

    • Hebr - ヘブライ語(イスラエル)

    • Hani - 漢字(日本)

    • Hans - 簡体字中国語(中国)

    • Arab - アラビア語(アラブ首長国連邦)

    • Thai - タイ語(タイ)

    • Hang - ハングル(韓国)

    • Native - 可能な場合はネイティブ・スクリプトで出力

    音訳は双方向であり、一般にNativeからLatnおよびLatnからNativeへと、前述のスクリプトの隣に記載されている国のデータを使用して行われます。 ただし、LatnからHansへは中国以外の国では利用できません。

    Loqateでは、ここに記載されている国以外でのラテン・スクリプトとネイティブ・スクリプト間の処理や音訳はサポートしていません。 たとえば、ギリシャ語(Grek)がポルトガルの住所に対して使用されている場合、Loqateはレコードを解析または検証できず、ラテン・スクリプトに音訳することもできません。 同様に、ラテン・スクリプトで入力されたポルトガルの住所は、他のどのスクリプトにも音訳できません。

    Loqateの音訳サポートの詳細は、https://support.loqate.com/character-scripts/を参照してください。

ノート: 有効な住所を持っていることがわかっており、標準化する場合以外は、minimumverificationmatchscoreを100に設定しないでください。 通常、国のデフォルトのminimumverificationlevelを使用します(例: US=4)。 例外は、郵便番号を確認する必要がある場合です。
次の例は、住所を検証する手順を示しています。 1件の住所確認要求、複数の住所でプロセスは同じです。

  1. 最初に、承認を設定します。 APIは標準のOAuth 2.0フローを使用して、APIクライアントおよびユーザーを承認および認証します。 APIを使用している場合は、OAuthクライアントIDおよびクライアント・シークレットがすでにある必要があります。 次のPOSTメソッドを使用してアクセス・トークンを要求できます: http://host:port/av/api/v3/oauth2/token。OAuthサンプル

    次に、受信した資格証明(キー値)を入力します。キー値

  2. 住所検証URLとしてhttp://host:port/av/api/v3/address/verifyと入力し、本文に入力として検証する住所を入力します。 この例では、Address1、Address2およびCountryのみを指定しています。

    入力として検証する住所

  3. 「送信」をクリックすると、検証済の標準化された完全な住所が応答として返されます。

    応答の検証済住所