Halaman ini diterjemahkan oleh Cloud Translation API.

Memvalidasi alamat

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

Setelah memvalidasi alamat, Anda dapat secara opsional menampilkan informasi ke Google 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 di 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 sertakan regionCode jika Anda mengetahuinya. Untuk daftar region yang didukung, lihat region yang didukung.
Panjang total kolom address dibatasi hingga 280 karakter.

Aktifkan CASSTM secara opsional saat memvalidasi alamat

United States Postal Service® (USPS®)¹ mempertahankan Coding Depth Support System (CASSTM) untuk mendukung dan memberikan sertifikasi kepada penyedia validasi alamat. Layanan CASS CertifiedTM, seperti Address Validation API, telah dikonfirmasi karena kemampuannya mengisi informasi yang tidak ada di alamat, menstandarkannya, dan mengupdatenya untuk memberikan alamat yang paling baru dan 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 nama jalan dan nomor jalan, beserta kota, negara bagian/provinsi, 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, berjenis Address, berisi informasi mendetail tentang alamat.
Kolom geocode, berjenis Geocode, yang berisi informasi geocode untuk alamat tersebut.

Catatan: Untuk mengetahui informasi tentang perbedaan antara address dan geocode, lihat Alamat vs geocode.
Kolom verdict, berjenis Verdict, berisi validasi alamat dan hasil geocode.
Kolom metadata, berjenis AddressMetadata, yang berisi metadata alamat.
Kolom uspsData, berjenis 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 perlu validasi lebih lanjut. Jika respons menunjukkan bahwa beberapa bagian alamat tidak valid, minta pengguna untuk memeriksa dan mengonfirmasi entri alamatnya.

{
  "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 pada alamatnya setelah melihat hasil validasi pertama. Kemudian, Anda melakukan validasi kedua di alamat yang diperbarui.

Setiap panggilan Address Validation API menampilkan nilai unik dalam kolom responseId respons. Jika alamat yang Anda coba 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 untuk meningkatkan akurasi API secara keseluruhan.

Misalnya, respons yang ditampilkan di atas menyertakan kolom responseId:

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

Kemudian Anda ingin memvalidasi ulang alamat dengan perubahan pada nomor jalan dari 1600 menjadi 1500. Saat Anda memvalidasi ulang alamat, sertakan kolom previousResponseId dengan nilai responseId dari respons first:

{
  "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 first 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 menghilangkan parameter isi yang diperlukan, seperti addressLines, metode ini akan menampilkan:

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

Untuk informasi selengkapnya tentang error dan penanganan error, lihat Error.

Google Maps Platform adalah Penerima Lisensi non-eksklusif dari United States Postal Service®. Merek dagang berikut dimiliki oleh United States Postal Service® dan digunakan dengan izin: United States Postal Service®, CASSTM, CASS CertifiedTM. ↩