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 sertakanregionCode
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®)1 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.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. ↩