Чтобы проверить адрес с помощью API проверки адресов, вызовите метод validateAddress (REST) или метод ValidateAddress (gRPC). В этой документации для примеров используется REST, но подход аналогичен gRPC .
После проверки адреса вы можете дополнительно вернуть в Google информацию о результатах проверки адреса, вызвав метод ProvideValidationFeedback (REST) или ProvideValidationFeedback (gRPC). Дополнительные сведения и примеры см. в разделе Предоставление отзыва о проверке адреса .
Запрос проверки адреса
Подтвердите адрес, отправив запрос POST
методу validateAddress :
https://addressvalidation.googleapis.com/v1:validateAddress?key=YOUR_API_KEY
Передайте тело JSON в запрос, определяющий адрес для проверки:
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"
Поле address
в тексте запроса типа PostalAddress должно содержать хотя бы одну запись в addressLines
.
Поле
regionCode
является необязательным. Если этот параметр опущен, API определяет регион по адресу. Однако для наилучшей производительности мы рекомендуем включатьregionCode
, если он вам известен. Список поддерживаемых регионов см. в разделе Поддерживаемые регионы .Общая длина поля
address
ограничена 280 символами.
Опционально включите CASS™ при проверке адреса
Почтовая служба США® (USPS®) 1 поддерживает Систему поддержки точности кодирования (CASS™) для поддержки и сертификации поставщиков проверки адресов. Служба CASS Certified™, такая как Address Validation API, была подтверждена за ее способность заполнять информацию, отсутствующую в адресе, стандартизировать ее и обновлять, чтобы предоставить вам самый актуальный и самый точный адрес.
Только для регионов «США» и «PR» вы можете дополнительно включить обработку CASS, задав для параметра enableUspsCass
значение true
в тексте запроса.
Для достижения наилучших результатов при использовании CASS укажите адрес, который включает улицу и номер дома, а также город, штат и почтовый индекс:
{
"address": {
"regionCode": "US",
"locality": "Mountain View",
"administrativeArea": "CA",
"postalCode": "94043",
"addressLines": ["1600 Amphitheatre Pkwy"]
},
"enableUspsCass": true
}
Вы также можете указать полный адрес в виде двух строк в массиве addressLines
:
{
"address": {
"regionCode": "US",
"addressLines": ["1600 Amphitheatre Pkwy", "Mountain View, CA, 94043"]
},
"enableUspsCass": true
}
Ответ проверки адреса
Если запрос выполнен успешно, сервер отвечает кодом состояния HTTP 200 OK
и телом ответа , содержащим информацию о проверенном адресе.
Поле result
ответа содержит объект ValidationResult . Этот объект включает в себя:
Поле
address
типа Address , содержащее подробную информацию об адресе.Поле
geocode
типа Geocode , содержащее информацию о геокоде для адреса.Поле
verdict
типа Verdict , содержащее результат проверки адреса и геокодирования.Поле
metadata
типа AddressMetadata , содержащее метаданные для адреса.Поле
uspsData
типа USPSData , содержащее данные USPS для адреса. Эти данные доступны только для адресов в США и Пуэрто-Рико.
Поскольку в следующем ответе для addressComplete
установлено значение true
, ответ указывает, что этот адрес полностью действителен, поэтому дальнейшая проверка не требуется. Если в ответе указано, что какая-то часть адреса недействительна, предложите пользователю проверить и подтвердить ввод адреса.
{
"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"
}
Подтвердить обновленный адрес
В некоторых случаях может потребоваться несколько вызовов API проверки адресов для одного адреса. Например, пользователь может внести изменения или исправления в свой адрес, увидев результаты первой проверки. Затем вы выполняете вторую проверку обновленного адреса.
Каждый вызов API проверки адресов возвращает уникальное значение в поле responseId
ответа. Если адрес, который вы пытаетесь проверить, нуждается в повторной проверке, передайте responseId
из первого ответа проверки в поле previousResponseId
для всех последующих запросов к API проверки адреса.
Включив поле previousResponseId
в новый запрос, вы поможете нам повысить общую точность API.
Например, ответ, показанный выше, включает поле responseId
:
"responseId": "de22bed8-7f52-44cb-8526-faceac57150a"
Затем вы хотите повторно проверить адрес, изменив номер улицы с 1600 на 1500. При повторной проверке адреса включите в поле previousResponseId
значение responseId
из первого ответа:
{ "address": { "regionCode" : "US", "locality" : "Mountain View", "addressLines" : ["1500 Amphitheatre Pkwy"] }, "previousResponseId": "de22bed8-7f52-44cb-8526-faceac57150a" }
Для запроса с использованием CASS:
{ "address": { "regionCode" : "US", "locality" : "Mountain View", "addressLines" : ["1500 Amphitheatre Pkwy"] }, "previousResponseId": "de22bed8-7f52-44cb-8526-faceac57150a", "enableUspsCass": true }
Результаты каждого последующего вызова возвращают новое значение в поле responseId
. Однако продолжайте передавать значение responseId
из первого ответа в поле previousResponseId
при всех последующих вызовах обновлений адреса.
Обработка ошибок
API проверки адресов возвращает сообщения об ошибках как часть ответа на вызов метода. Например, если вы не укажете ключ API в запросе, метод вернет:
{ "error": { "code": 403, "message": "The request is missing a valid API key.", "status": "PERMISSION_DENIED" } }
Если вы опустите обязательный параметр тела, например, addressLines
, метод вернет:
{ "error": { "code": 400, "message": "Address lines missing from request.", "status": "INVALID_ARGUMENT" } }
Дополнительные сведения об ошибках и их обработке см. в разделе Ошибки .
Платформа Google Maps является неэксклюзивным лицензиатом Почтовой службы США®. Следующие товарные знаки принадлежат Почтовой службе США® и используются с разрешения: Почтовая служба США®, CASS™, CASS Certified™. ↩