Mengirim permintaan validasi alamat

Untuk memvalidasi alamat menggunakan Address Validation API, panggil metode validateAddress (REST) atau metode ValidateAddress (gRPC). Dokumentasi ini menggunakan REST untuk contohnya, tetapi pendekatannya mirip dengan gRPC.

Setelah memvalidasi alamat, Anda dapat menampilkan informasi ke Google secara opsional tentang hasil validasi alamat dengan memanggil metode provideValidationFeedback (REST) atau metode ProvideValidationFeedback (gRPC). Untuk mengetahui informasi dan contohnya, lihat Memberikan masukan validasi alamat.

Permintaan validasi alamat

Validasi alamat dengan mengirimkan permintaan POST ke metode validateAddress:

https://addressvalidation.googleapis.com/v1:validateAddress?key=YOUR_API_KEY

Teruskan isi JSON ke permintaan yang menentukan alamat yang akan divalidasi:

curl -X POST -d '{
  "address": {
    "regionCode": "US",
    "locality": "Mountain View",
    "addressLines": ["1600 Amphitheatre Pkwy"]
  }
}' \
-H 'Content-Type: application/json' \
"https://addressvalidation.googleapis.com/v1:validateAddress?key=YOUR_API_KEY"

Kolom address dalam isi permintaan, dengan jenis PostalAddress, harus berisi setidaknya satu entri di addressLines.

• Kolom regionCode bersifat opsional. Jika dihilangkan, API akan menyimpulkan wilayah dari alamat. Namun, untuk performa terbaik, sebaiknya Anda menyertakan regionCode jika Anda mengetahuinya. Untuk mengetahui daftar region yang didukung, lihat region yang didukung.

• Panjang total kolom address dibatasi hingga 280 karakter.

Secara opsional, aktifkan CASSTM saat memvalidasi alamat

United States Postal Service® (USPS®)¹ menggunakan Coding Accuracy Support System (CASSTM) untuk mendukung dan mensertifikasi penyedia validasi alamat. Layanan CASS CertifiedTM, seperti Address Validation API, telah dikonfirmasi kemampuannya untuk mengisi informasi yang hilang dari alamat, menstandarkannya, dan memperbaruinya untuk memberi Anda alamat terbaru dan paling akurat.

Khusus untuk wilayah "US" dan "PR", Anda dapat mengaktifkan pemrosesan CASS secara opsional dengan menetapkan enableUspsCass ke true dalam isi permintaan.

Untuk hasil terbaik saat menggunakan CASS, berikan alamat yang menyertakan nomor jalan dan jalan beserta kota, negara bagian, dan kode pos:

{
  "address": {
    "regionCode": "US",
    "locality": "Mountain View",
    "administrativeArea": "CA",
    "postalCode": "94043",
    "addressLines": ["1600 Amphitheatre Pkwy"]
  },
  "enableUspsCass": true
}

Anda juga dapat menentukan alamat lengkap sebagai dua string dalam array addressLines:

{
  "address": {
    "regionCode": "US",
    "addressLines": ["1600 Amphitheatre Pkwy", "Mountain View, CA, 94043"]
  },
  "enableUspsCass": true
}

Respons validasi alamat

Jika permintaan berhasil, server akan merespons dengan kode status 200 OK HTTP dan isi respons yang berisi informasi tentang alamat yang divalidasi.

Kolom result respons berisi objek ValidationResult. Objek ini mencakup:

• Kolom address, dari jenis Address, yang berisi informasi mendetail tentang alamat.

• Kolom geocode, dari jenis Geocode, yang berisi informasi geocoding untuk alamat tersebut.

• Kolom verdict, dari jenis Verdict, yang berisi hasil validasi alamat dan geocode.

• Kolom metadata, dari jenis AddressMetadata, yang berisi metadata untuk alamat.

• Kolom uspsData, dengan jenis USPSData, yang berisi data USPS untuk alamat. Data ini hanya tersedia untuk alamat di Amerika Serikat dan Puerto Riko.

Karena respons berikut berisi addressComplete yang ditetapkan ke true, respons menunjukkan bahwa alamat ini sepenuhnya valid, sehingga tidak diperlukan validasi lebih lanjut. Jika respons menunjukkan bahwa beberapa bagian alamat tidak valid, minta pengguna untuk memeriksa dan mengonfirmasi entri alamat mereka.

{
  "result": {
    "verdict": {
      "inputGranularity": "PREMISE",
      "validationGranularity": "PREMISE",
      "geocodeGranularity": "PREMISE",
      "addressComplete": true,
      "hasInferredComponents": true
    },
    "address": {
      "formattedAddress": "1600 Amphitheatre Parkway, Mountain View, CA 94043-1351, USA",
      "postalAddress": {
        "regionCode": "US",
        "languageCode": "en",
        "postalCode": "94043-1351",
        "administrativeArea": "CA",
        "locality": "Mountain View",
        "addressLines": [
          "1600 Amphitheatre Pkwy"
        ]
      },
      "addressComponents": [
        {
          "componentName": {
            "text": "1600",
            "languageCode": "en"
          },
          "componentType": "street_number",
          "confirmationLevel": "CONFIRMED"
        },
        {
          "componentName": {
            "text": "Amphitheatre Parkway",
            "languageCode": "en"
          },
          "componentType": "route",
          "confirmationLevel": "CONFIRMED"
        },
        {
          "componentName": {
            "text": "Mountain View",
            "languageCode": "en"
          },
          "componentType": "locality",
          "confirmationLevel": "CONFIRMED"
        },
        {
          "componentName": {
            "text": "USA",
            "languageCode": "en"
          },
          "componentType": "country",
          "confirmationLevel": "CONFIRMED"
        },
        {
          "componentName": {
            "text": "94043"
          },
          "componentType": "postal_code",
          "confirmationLevel": "CONFIRMED",
          "inferred": true
        },
        {
          "componentName": {
            "text": "CA",
            "languageCode": "en"
          },
          "componentType": "administrative_area_level_1",
          "confirmationLevel": "CONFIRMED",
          "inferred": true
        },
        {
          "componentName": {
            "text": "1351"
          },
          "componentType": "postal_code_suffix",
          "confirmationLevel": "CONFIRMED",
          "inferred": true
        }
      ]
    },
    "geocode": {
      "location": {
        "latitude": 37.4223878,
        "longitude": -122.0841877
      },
      "plusCode": {
        "globalCode": "849VCWC8+X8"
      },
      "bounds": {
        "low": {
          "latitude": 37.4220699,
          "longitude": -122.084958
        },
        "high": {
          "latitude": 37.4226618,
          "longitude": -122.0829302
        }
      },
      "featureSizeMeters": 116.538734,
      "placeId": "ChIJj38IfwK6j4ARNcyPDnEGa9g",
      "placeTypes": [
        "premise"
      ]
    },
    "metadata": {
      "business": false,
      "poBox": false
    },
    "uspsData": {
      "standardizedAddress": {
        "firstAddressLine": "1600 AMPHITHEATRE PKWY",
        "cityStateZipAddressLine": "MOUNTAIN VIEW CA 94043-1351",
        "city": "MOUNTAIN VIEW",
        "state": "CA",
        "zipCode": "94043",
        "zipCodeExtension": "1351"
      },
      "deliveryPointCode": "00",
      "deliveryPointCheckDigit": "0",
      "dpvConfirmation": "Y",
      "dpvFootnote": "AABB",
      "dpvCmra": "N",
      "dpvVacant": "N",
      "dpvNoStat": "Y",
      "carrierRoute": "C909",
      "carrierRouteIndicator": "D",
      "postOfficeCity": "MOUNTAIN VIEW",
      "postOfficeState": "CA",
      "fipsCountyCode": "085",
      "county": "SANTA CLARA",
      "elotNumber": "0103",
      "elotFlag": "A",
      "addressRecordType": "S"
    }
  },
  "responseId": "de22bed8-7f52-44cb-8526-faceac57150a"
}

Memvalidasi alamat yang diperbarui

Dalam beberapa kasus, Anda mungkin harus melakukan beberapa panggilan ke Address Validation API untuk satu alamat. Misalnya, pengguna mungkin membuat perubahan atau koreksi alamat setelah melihat hasil validasi pertama. Kemudian, Anda melakukan validasi kedua pada alamat yang diperbarui.

Setiap panggilan Address Validation API menampilkan nilai unik di kolom responseId respons. Jika alamat yang ingin Anda validasi perlu divalidasi ulang, teruskan responseId dari respons validasi pertama di kolom previousResponseId untuk semua permintaan tindak lanjut ke Address Validation API.

Dengan menyertakan kolom previousResponseId dalam permintaan baru, Anda dapat membantu kami meningkatkan akurasi API secara keseluruhan.

Misalnya, respons yang ditampilkan di atas menyertakan kolom responseId:

  "responseId": "de22bed8-7f52-44cb-8526-faceac57150a"

Kemudian, Anda perlu memvalidasi ulang alamat tersebut dengan mengubah nomor jalan dari 1600 menjadi 1500. Saat Anda memvalidasi ulang alamat tersebut, sertakan kolom previousResponseId dengan nilai responseId dari respons pertama:

{
  "address": {
    "regionCode" : "US",
    "locality" : "Mountain View",
    "addressLines" : ["1500 Amphitheatre Pkwy"]
  },
  "previousResponseId": "de22bed8-7f52-44cb-8526-faceac57150a"
}

Untuk permintaan yang menggunakan CASS:

{
  "address": {
    "regionCode" : "US",
    "locality" : "Mountain View",
    "addressLines" : ["1500 Amphitheatre Pkwy"]
  },
  "previousResponseId": "de22bed8-7f52-44cb-8526-faceac57150a",
  "enableUspsCass": true

}

Hasil setiap panggilan berikutnya menampilkan nilai baru di kolom responseId. Namun, terus teruskan nilai responseId dari respons pertama di kolom previousResponseId pada semua panggilan berikutnya untuk pembaruan alamat.

Penanganan error

Address Validation API menampilkan pesan error sebagai bagian dari respons terhadap panggilan metode. Misalnya, jika Anda menghilangkan kunci API dari permintaan, metode ini akan menampilkan:

{
  "error": {
    "code": 403,
    "message": "The request is missing a valid API key.",
    "status": "PERMISSION_DENIED"
  }
}

Jika Anda menghapus parameter isi yang diperlukan, seperti addressLines, metode akan menampilkan:

{
  "error": {
    "code": 400,
    "message": "Address lines missing from request.",
    "status": "INVALID_ARGUMENT"
  }
}

Untuk mengetahui informasi lebih lanjut tentang penanganan error dan error, lihat Error.