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 ProvideValidationMasukan (REST) atau MenyediakanValidationMasukan (gRPC). Untuk mengetahui informasi dan contohnya, lihat Memberikan masukan validasi alamat.

Permintaan validasi alamat

Validasikan alamat dengan mengirimkan permintaan POST ke metode validasiAddress:

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

Teruskan isi JSON ke permintaan yang menentukan alamat untuk 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 sertakan regionCode jika Anda mengetahuinya. Untuk mengetahui 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 Sistem Dukungan Akurasi Coding (CASSTM) untuk mendukung dan mensertifikasi penyedia validasi alamat. Layanan CASS CertifiedTM, seperti Address Validation API, telah terkonfirmasi karena kemampuannya untuk mengisi informasi yang tidak ada dalam alamat, menstandarkannya, dan memperbaruinya untuk memberikan alamat yang paling baru dan akurat kepada Anda.

Khusus untuk region "US" dan "PR", Anda dapat mengaktifkan pemrosesan CASS dengan menetapkan enableUspsCass ke true di isi permintaan.

Untuk hasil terbaik saat menggunakan CASS, berikan alamat yang menyertakan nomor jalan dan kota, serta 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, dengan jenis Address, yang berisi informasi mendetail mengenai alamat.

• Kolom geocode, dengan jenis Geocode, berisi informasi geocode untuk alamat.

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

• Kolom metadata, dengan jenis AddressMetadata, yang berisi metadata alamat.

• Kolom uspsData, dari 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 disetel 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 Anda 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 ke alamatnya setelah melihat hasil validasi pertama. Kemudian, Anda melakukan validasi kedua di alamat yang diperbarui.

Setiap panggilan Address Validation API akan menampilkan nilai unik di kolom responseId pada 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 meningkatkan akurasi API secara keseluruhan.

Misalnya, respons yang ditunjukkan di atas menyertakan kolom responseId:

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

Selanjutnya, Anda dapat memvalidasi ulang alamat dengan perubahan nomor jalan dari 1600 menjadi 1500. Saat Anda memvalidasi ulang alamat, 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 dari 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 informasi selengkapnya tentang error dan penanganan error, lihat Error.