Отправить запрос на проверку адреса

Чтобы проверить адрес с помощью 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®) ¹ поддерживает Систему поддержки точности кодирования (CASS™) для поддержки и сертификации поставщиков проверки адресов. Служба CASS Certified™, такая как 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"
  }
}

Дополнительные сведения об ошибках и их обработке см. в разделе Ошибки .