Tài liệu này mô tả một số tình huống thực tế, trong đó API xác thực địa chỉ cung cấp tín hiệu phản hồi cho các địa chỉ đảm bảo hành vi xác nhận từ hệ thống của bạn. Xem phần Tổng quan về quy trình công việc trong bài viết Xây dựng logic xác thực để nắm được ngữ cảnh.
Ví dụ thường gặp: xác nhận
Ví dụ sau minh hoạ trường hợp các khu vực đô thị có tên đường phố tương tự nhau. Giả sử người dùng có ý định nhập địa chỉ cho Google Building D ở Kirkland, WA, United States. Tuy nhiên, thay vì thành phố Kirkland, họ lại vô tình đi vào Seattle.
| Đã nhập địa chỉ | Khu vực |
|---|---|
| Toà nhà D, 451 7th Avenue South, Seattle, WA 98033 | Hoa Kỳ |
Kết quả cho dữ liệu đã thay thế
Ví dụ dưới đây nhấn mạnh các tín hiệu quan trọng của câu trả lời.
{
"inputGranularity": "SUB_PREMISE",
"validationGranularity": "PREMISE_PROXIMITY",
"geocodeGranularity": "PREMISE_PROXIMITY",
"addressComplete": true,
"hasUnconfirmedComponents": true
"hasReplacedComponents": true
}
PREMISE_PROXIMITY cho biết độ gần của một địa chỉ cấp toà nhà, nhưng không chi tiết như SUB_PREMISE (đây là độ chi tiết được cung cấp khi nhập vào dữ liệu đầu vào).
Phản hồi cũng chứa cả thành phần chưa được xác nhận và thành phần được thay thế, vì vậy, tổ hợp này sẽ đưa thành phần này vào danh mục xác nhận.
Một truy vấn về các thành phần địa chỉ cho thấy các khu vực cần quan tâm sau:
{
"componentName": {
"text": "451",
},
"componentType": "street_number",
"confirmationLevel": "UNCONFIRMED_BUT_PLAUSIBLE",
}
...
{
"componentName": {
"text": "98104",
},
"componentType": "postal_code",
"confirmationLevel": "CONFIRMED",
"replaced": true
}
...
{
"componentName": {
"text": "Building D",
"language_code": "en"
},
"componentType": "subpremise",
"confirmationLevel": "UNCONFIRMED_BUT_PLAUSIBLE",
}
.......
"unconfirmedComponentTypes": [
"street_number",
"subpremise"
]
Trong trường hợp này, API xác thực địa chỉ tìm được kết quả gần đúng với địa chỉ được cung cấp ở Seattle và thay thế mã bưu chính (một thành phần cấp cao hơn) để phân giải đến địa chỉ Seattle. Đây có thể là một phương án thay thế hợp lệ, nhưng cùng với việc các thành phần chưa được xác nhận, bạn cần đảm bảo rằng người dùng định nhập địa chỉ Seattle chứ không phải địa chỉ nào khác, như Kirkland.
Ví dụ về trường hợp đặc biệt: xác nhận
Sau đây là ví dụ minh hoạ các loại trường hợp đặc biệt sau đây:
- Suy luận nhỏ ĐƯỢC xác nhận. API xác thực địa chỉ suy luận quốc gia, mã bưu chính hoặc tiểu bang, nhưng mọi thông tin khác đều được cung cấp và xác nhận. Sự kết hợp của cả mức độ chi tiết và mức độ xác nhận tạo ra một suy luận nhỏ không nhất thiết phải thực hiện hành động xác nhận.
- Thành phần địa chỉ ngoài dự kiến KHÔNG được xác nhận. Các thành phần địa chỉ chưa được xác nhận sẽ làm tăng mức độ rủi ro của địa chỉ. Điều này có thể đảm bảo bạn đã xác nhận.
- Thành phần địa chỉ ngoài dự kiến đã được xác nhận. Thành phần này không bắt buộc phải có một địa chỉ phù hợp và API Xác thực địa chỉ sẽ xoá thành phần đó khỏi kết quả. Các vấn đề về định dạng thường không đảm bảo việc xác nhận.
Những suy luận nhỏ ĐƯỢC xác nhận
Khi kết hợp với dữ liệu đã xác nhận ở cấp độ chi tiết hơn, API vẫn có thể đưa ra suy luận chính xác nếu dữ liệu đầu vào chỉ thiếu một thành phần thuộc các loại sau:
- Thành phố
- Tiểu bang
- Mã bưu chính
- Quốc gia
Ví dụ: một khách hàng cung cấp địa chỉ đường phố hợp lệ cho nhà hàng McDonald's ở Springfield, Massachusetts, nhưng lại quên nhập thành phố và cung cấp mã bưu chính mà không có phần mở rộng gồm 4 chữ số.
| Đã nhập địa chỉ | Khu vực |
|---|---|
| 1402 Đường Allen, MA 01118 | Hoa Kỳ |
Kết quả cho thành phố bị thiếu
{
"inputGranularity": "PREMISE",
"validationGranularity": "PREMISE",
"geocodeGranularity": "PREMISE",
"addressComplete": true,
"hasInferredComponents": true
}
Trong trường hợp API xác thực địa chỉ suy luận các thành phần cấp cao hơn để tạo một địa chỉ có thể phân phối, bạn có thể yên tâm hơn rằng dữ liệu từ hệ thống là chính xác. Điều này là do các thành phần suy luận đại diện cho một khu vực địa lý rộng sẽ dễ dàng so khớp với các thành phần địa chỉ đã xác nhận và chi tiết hơn. Ngay cả ở những quốc gia nơi tên thành phố bị lặp lại, chẳng hạn như Springfield ở Hoa Kỳ, các thành phần khác kết hợp với thành phần này có thể cung cấp một địa chỉ duy nhất.
Trong ví dụ trên, việc quét tất cả các thành phần địa chỉ sẽ cho thấy mọi thành phần đều được xác nhận, có nghĩa là khớp với dữ liệu do API Xác thực địa chỉ lưu trữ và dịch vụ cũng dự đoán 2 thành phần cấp cao hơn.
{
"componentName": {
"text": "Springfield",
"languageCode": "en"
},
"componentType": "locality",
"confirmationLevel": "CONFIRMED",
"inferred": true
},
{
"componentName": {
"text": "1806"
},
"componentType": "postal_code_suffix",
"confirmationLevel": "CONFIRMED",
"inferred": true
}
Thành phần địa chỉ không mong muốn KHÔNG được xác nhận
Tình huống này minh hoạ tầm quan trọng của việc kiểm tra khi các thành phần chưa được xác nhận. Nếu một thành phần địa chỉ không mong muốn, API Xác thực địa chỉ sẽ xoá thành phần đó khỏi kết quả. Trong những trường hợp này, bạn có thể chấp nhận địa chỉ hoặc xác nhận lại với khách hàng, tuỳ thuộc vào mức độ rủi ro và mức độ tin cậy của bạn.
Ví dụ: địa chỉ có thể đến từ một khu vực nơi khách hàng thường nhập thông tin vô hại bị cơ quan bưu chính bỏ qua. Trong trường hợp đó, bạn sẽ chấp nhận địa chỉ này. Tuy nhiên, trong một số trường hợp, một thành phần chưa được xác nhận có thể không phải là những gì khách hàng muốn.
| Đã nhập địa chỉ | Khu vực |
|---|---|
| 1 Rue Grenache, la caritat 2, 34630 Saint-Thibéry | Pháp |
Kết quả cho thành phần địa chỉ không mong muốn chưa được xác nhận
{
"inputGranularity": "PREMISE",
"validationGranularity": "PREMISE",
"geocodeGranularity": "PREMISE",
"unconfirmedComponents": true
}
Ngoài kết quả có các thành phần chưa được xác nhận, API Xác thực địa chỉ còn trả về địa chỉ được định dạng sau:
"formattedAddress": "1 Rue Grenache, 34630 Saint-Thibéry, France",
Một lượt quét các thành phần chưa được xác nhận cho thấy API đã xoá la caritat 2 khỏi địa chỉ được trả về:
{
"componentName": {
"text": "la caritat 2",
"languageCode": "fr"
},
"componentType": "sublocality_level_1",
"confirmationLevel": "UNCONFIRMED_BUT_PLAUSIBLE",
"unexpected": true
}
Thành phần địa chỉ ngoài dự kiến đã được xác nhận IS
Ví dụ này minh hoạ việc đưa một hạt của Vương quốc Anh vào địa chỉ được cung cấp. Đây là một phương thức phổ biến. Tuy nhiên, đây không phải là yêu cầu của cơ quan bưu chính của Vương quốc Anh và về cơ bản sẽ bị bỏ qua. Vui lòng xem postoffice.co.uk và Cách gửi thư tại Vương quốc Anh và quốc tế.
Do đó, khi khách hàng cung cấp một hạt ở địa chỉ ở Vương quốc Anh, dịch vụ sẽ đánh giá thông tin này là thông tin đầu vào không mong muốn.
| Đã nhập địa chỉ | Khu vực |
|---|---|
| 33 Dunalley St, Cheltenham, Gloucestershire, GL50 4AP | Vương quốc Anh |
Kết quả cho thành phần địa chỉ không mong muốn đã được xác nhận
{
"inputGranularity": "PREMISE",
"validationGranularity": "PREMISE",
"geocodeGranularity": "PREMISE"
}
Ở đây, address_complete đánh giá là false và kết quả phân tích thành phần địa chỉ cho thấy một cờ ngoài dự kiến.
{
"componentName": {
"text": "Gloucestershire",
"languageCode": "en"
},
"componentType": "administrative_area_level_2",
"confirmationLevel": "CONFIRMED",
"unexpected": true
}
Mặc dù Gloucestershire là hạt chính xác cho địa chỉ đã nhập, nhưng bản thân địa chỉ đó lại được định dạng không đúng. Hãy nhớ rằng API xác thực địa chỉ cũng đánh giá thông tin để đảm bảo định dạng phù hợp.