- HTTP-запрос
- Тело запроса
- Тело ответа
- Почтовый адрес
- Языковые параметры
- Результат проверки
- Вердикт
- Детализация
- Адрес
- Адресный компонент
- ИмяКомпонента
- Уровень подтверждения
- Геокодирование
- ШиротаДлительность
- ПлюсКод
- Область просмотра
- АдресМетаданные
- UspsData
- UspsАдрес
Проверяет адрес.
HTTP-запрос
POST https://addressvalidation.googleapis.com/v1:validateAddress
URL-адрес использует синтаксис транскодирования gRPC .
Тело запроса
Тело запроса содержит данные следующей структуры:
JSON-представление |
---|
{ "address": { object ( |
Поля | |
---|---|
address | Необходимый. Адрес проверяется. Неформатированные адреса следует отправлять через Общая длина полей в этом вводе не должна превышать 280 символов. Поддерживаемые регионы можно найти здесь . Значение API проверки адреса игнорирует значения |
previousResponseId | Это поле должно быть пустым для первого запроса на проверку адреса. Если для полной проверки одного адреса необходимо больше запросов (например, если изменения, внесенные пользователем после первоначальной проверки, необходимо повторно проверить), то каждый последующий запрос должен заполнить это поле идентификатором |
enableUspsCass | Включает режим совместимости с USPS CASS. Это влияет только на поле Рекомендуется использовать компонентный |
languageOptions | Необязательный. Предварительная версия. Эта функция находится в предварительной версии (до GA). Продукты и функции Pre-GA могут иметь ограниченную поддержку, а изменения в продуктах и функциях Pre-GA могут быть несовместимы с другими версиями Pre-GA. На предложения Pre-GA распространяются Особые условия обслуживания платформы Google Maps . Дополнительную информацию см. в описании этапов запуска . Позволяет API проверки адреса включать дополнительную информацию в ответ. |
sessionToken | Необязательный. Строка, которая идентифицирует сеанс автозаполнения для целей выставления счетов. Должна быть строкой в формате Base64, безопасной для URL и имени файла, длиной не более 36 символов ASCII. В противном случае возвращается ошибка INVALID_ARGUMENT. Сеанс начинается, когда пользователь выполняет запрос автозаполнения, и завершается, когда он выбирает место и вызывает функцию «Подробности о месте» или «Проверка адреса». В каждом сеансе может быть несколько запросов автозаполнения, за которыми следует один запрос сведений о месте или проверки адреса. Учетные данные, используемые для каждого запроса в рамках сеанса, должны принадлежать одному и тому же проекту Google Cloud Console. После завершения сеанса токен больше не действителен; ваше приложение должно генерировать новый токен для каждого сеанса. Если параметр Примечание. Проверка адреса может использоваться только в сеансах с API автозаполнения (нового), а не с API автозаполнения. Дополнительную информацию см. на странице https://developers.google.com/maps/documentation/places/web-service/session-pricing . |
Тело ответа
Ответ на запрос проверки адреса.
В случае успеха тело ответа содержит данные следующей структуры:
JSON-представление |
---|
{
"result": {
object ( |
Поля | |
---|---|
result | Результат проверки адреса. |
responseId | UUID, идентифицирующий этот ответ. Если адрес необходимо повторно проверить, этот UUID должен сопровождать новый запрос. |
Почтовый адрес
Представляет почтовый адрес, например, для адресов почтовой доставки или платежей. Учитывая почтовый адрес, почтовая служба может доставлять товары в помещение, почтовый ящик или подобное место. Он не предназначен для моделирования географических мест (дорог, городов, гор).
Обычно адрес создается посредством пользовательского ввода или путем импорта существующих данных, в зависимости от типа процесса.
Советы по вводу/редактированию адреса: - Используйте готовый к интернационализации виджет адреса, например https://github.com/google/libaddressinput . - Пользователям не должны предоставляться элементы пользовательского интерфейса для ввода или редактирования полей за пределами стран, где это поле есть. использовал.
Дополнительные инструкции по использованию этой схемы см. на странице https://support.google.com/business/answer/6397478 .
JSON-представление |
---|
{ "revision": integer, "regionCode": string, "languageCode": string, "postalCode": string, "sortingCode": string, "administrativeArea": string, "locality": string, "sublocality": string, "addressLines": [ string ], "recipients": [ string ], "organization": string } |
Поля | |
---|---|
revision | Версия схемы |
regionCode | Необязательный. CLDR-код региона страны/региона адреса. Подробности см. на https://cldr.unicode.org/ и https://www.unicode.org/cldr/charts/30/supplemental/territory_information.html . Пример: «CH» для Швейцарии. Если код региона не указан, он будет получен из адреса. Для лучшей производительности рекомендуется указать код региона, если вы его знаете. Наличие противоречивых или повторяющихся регионов может привести к снижению производительности. Например, если |
languageCode | Код языка во входном адресе зарезервирован для будущего использования и сегодня игнорируется. API возвращает адрес на языке, соответствующем тому, где находится адрес. |
postalCode | Необязательный. Почтовый индекс адреса. Не все страны используют или требуют наличия почтовых индексов, но там, где они используются, они могут вызвать дополнительную проверку других частей адреса (например, проверка штата/почтового индекса в США). |
sortingCode | Необязательный. Дополнительный код сортировки для конкретной страны. В большинстве регионов это не используется. Там, где оно используется, значение представляет собой либо строку типа «CEDEX», за которой необязательно следует число (например, «CEDEX 7»), либо просто число, представляющее «код сектора» (Ямайка), «указатель зоны доставки». (Малави) или «индикатор почтового отделения» (например, Кот-д'Ивуар). |
administrativeArea | Необязательный. Высшее административное подразделение, используемое для почтовых адресов страны или региона. Например, это может быть штат, провинция, область или префектура. В частности, для Испании это провинция, а не автономное сообщество (например, «Барселона», а не «Каталония»). Многие страны не используют административную зону в почтовых адресах. Например, в Швейцарии это место следует оставить незаселенным. |
locality | Необязательный. Обычно относится к части адреса, посвященной городу. Примеры: город в США, ИТ-коммуна, почтовый город Великобритании. В регионах мира, где населенные пункты не определены четко или не вписываются в эту структуру, оставьте locality пустым и используйте адресные строки. |
sublocality | Необязательный. Сублокальность адреса. Например, это могут быть микрорайоны, районы, районы. |
addressLines[] | Необходимый. Неструктурированные адресные строки, описывающие нижние уровни адреса. |
recipients[] | Пожалуйста, не заполняйте это поле. API проверки адреса в настоящее время не использует его. Хотя в настоящее время API не будет отклонять запросы с этим набором полей, информация будет отброшена и не будет возвращена в ответе. |
organization | Пожалуйста, не заполняйте это поле. API проверки адреса в настоящее время не использует его. Хотя в настоящее время API не будет отклонять запросы с этим набором полей, информация будет отброшена и не будет возвращена в ответе. |
Языковые параметры
Предварительная версия. Эта функция находится в предварительной версии (до GA). Продукты и функции до GA могут иметь ограниченную поддержку, а изменения в продуктах и функциях до GA могут быть несовместимы с другими версиями до GA. На предложения Pre-GA распространяются Особые условия обслуживания платформы Google Maps . Дополнительную информацию см. в описании этапов запуска .
Позволяет API проверки адреса включать дополнительную информацию в ответ.
JSON-представление |
---|
{ "returnEnglishLatinAddress": boolean } |
Поля | |
---|---|
returnEnglishLatinAddress | Предварительная версия: возврат адреса |
Результат проверки
Результат проверки адреса.
JSON-представление |
---|
{ "verdict": { object ( |
Поля | |
---|---|
verdict | Общие флаги вердикта |
address | Информация о самом адресе в отличие от геокода. |
geocode | Информация о местоположении и месте, к которому геокодирован адрес. |
metadata | Другая информация, имеющая отношение к доставляемости. |
uspsData | Дополнительные флаги доставки, предоставляемые USPS. Предоставляется только в регионе |
englishLatinAddress | Предварительная версия. Эта функция находится в предварительной версии (до GA). Продукты и функции до GA могут иметь ограниченную поддержку, а изменения в продуктах и функциях до GA могут быть несовместимы с другими версиями до GA. На предложения Pre-GA распространяются Особые условия обслуживания платформы Google Maps . Дополнительную информацию см. в описании этапов запуска . Адрес переведен на английский. Переведенные адреса нельзя повторно использовать в качестве входных данных API. Служба предоставляет их, чтобы пользователь мог использовать свой родной язык для подтверждения или отклонения проверки первоначально предоставленного адреса. Если часть адреса не имеет перевода на английский язык, служба возвращает эту часть на альтернативном языке, использующем латиницу. См. здесь объяснение того, как выбирается альтернативный язык. Если часть адреса не имеет перевода или транслитерации на языке, использующем латиницу, служба возвращает эту часть на местном языке, связанном с адресом. Включите этот вывод, используя флаг Примечание. Поле |
Вердикт
Общий обзор результатов проверки адреса и геокодирования.
JSON-представление |
---|
{ "inputGranularity": enum ( |
Поля | |
---|---|
inputGranularity | Детализация входного адреса. Это результат анализа входного адреса, который не дает никаких сигналов проверки. Информацию о сигналах проверки см. в разделе Например, если входной адрес включает определенный номер квартиры, то |
validationGranularity | Уровень детализации, на котором API может полностью проверить адрес. Например, Результат проверки компонента адреса можно найти в |
geocodeGranularity | Информация о детализации Иногда это может отличаться от указанного выше |
addressComplete | Адрес считается полным, если нет неразрешенных токенов, неожиданных или отсутствующих компонентов адреса. Если значение не установлено, это указывает на то, что значение равно |
hasUnconfirmedComponents | По крайней мере один компонент адреса не может быть классифицирован или проверен. Подробности см. |
hasInferredComponents | Был выведен (добавлен) по крайней мере один компонент адреса, которого не было во входных данных. Подробности см. |
hasReplacedComponents | По крайней мере один компонент адреса был заменен. Подробности см. |
Детализация
Различные степени детализации, которые может иметь адрес или геокод. При использовании для указания степени детализации адреса эти значения указывают, с какой степенью детализации адрес идентифицирует пункт назначения почтовой рассылки. Например, такой адрес, как «123 Main Street, Redwood City, CA, 94061», идентифицирует PREMISE
, а адрес вроде «Redwood City, CA, 94061» идентифицирует LOCALITY
. Однако, если мы не сможем найти геокод для «123 Main Street» в Редвуд-Сити, возвращаемый геокод может иметь степень детализации LOCALITY
, хотя адрес более детализирован.
Перечисления | |
---|---|
GRANULARITY_UNSPECIFIED | Значение по умолчанию. Это значение не используется. |
SUB_PREMISE | Результат ниже уровня здания, например квартира. |
PREMISE | Результат на уровне здания. |
PREMISE_PROXIMITY | Геокод, который приблизительно соответствует местоположению адреса на уровне здания. |
BLOCK | Адрес или геокод указывают на блок. Используется только в регионах с адресацией на уровне блоков, например в Японии. |
ROUTE | Геокод или адрес детализирован для маршрута, например улица, дорога или шоссе. |
OTHER | Все остальные детали, которые объединены в группы, поскольку они не могут быть доставлены. |
Адрес
Подробности постобработанного адреса. Постобработка включает в себя исправление частей адреса с ошибками, замену неправильных частей и определение недостающих частей.
JSON-представление |
---|
{ "formattedAddress": string, "postalAddress": { object ( |
Поля | |
---|---|
formattedAddress | Адрес после постобработки, отформатированный как однострочный адрес в соответствии с правилами форматирования адреса региона, в котором расположен адрес. |
postalAddress | Адрес после обработки, представленный как почтовый адрес. |
addressComponents[] | Неупорядоченный список. Отдельные компоненты адреса отформатированного и исправленного адреса, а также информация проверки. Это предоставляет информацию о статусе проверки отдельных компонентов. Компоненты адреса не упорядочены определенным образом. Не делайте никаких предположений относительно порядка компонентов адреса в списке. |
missingComponentTypes[] | Типы компонентов, которые должны были присутствовать в правильно отформатированном почтовом адресе, но не были найдены во входных данных И не могли быть определены. Компоненты этого типа отсутствуют в |
unconfirmedComponentTypes[] | Типы компонентов, которые присутствуют в |
unresolvedTokens[] | Любые токены во входных данных, которые не удалось разрешить. Это может быть ввод, который не был распознан как допустимая часть адреса (например, при вводе типа «123235253253 Main St, San Francisco, CA, 94105» неразрешенные токены могут выглядеть как |
Адресный компонент
Представляет компонент адреса, например улицу, город или штат.
JSON-представление |
---|
{ "componentName": { object ( |
Поля | |
---|---|
componentName | Имя этого компонента. |
componentType | Тип компонента адреса. Список возможных типов см. в Таблице 2: Дополнительные типы, возвращаемые службой Places . |
confirmationLevel | Указывает уровень нашей уверенности в том, что компонент правильный. |
inferred | Указывает, что компонент не был частью входных данных, но мы определили его для местоположения адреса и считаем, что его следует указывать для полного адреса. |
spellCorrected | Указывает на исправление ошибки в названии компонента. API не всегда отмечает изменения одного варианта написания на другой, например, при изменении «центра» на «центр». Он также не всегда отмечает распространенные орфографические ошибки, например, при замене «Амфитеатр Пкви» на «Амфитеатр Пкви». |
replaced | Указывает, что имя компонента было заменено совершенно другим, например, неправильный почтовый индекс был заменен на правильный для адреса. Это не косметическое изменение, входной компонент изменен на другой. |
unexpected | Указывает компонент адреса, который не ожидается в почтовом адресе для данного региона. Мы сохранили его только потому, что он был частью входных данных. |
ИмяКомпонента
Обертка для имени компонента.
JSON-представление |
---|
{ "text": string, "languageCode": string } |
Поля | |
---|---|
text | Текст имени. Например, «5th Avenue» для названия улицы или «1253» для номера улицы. |
languageCode | Код языка BCP-47. Этого не будет, если имя компонента не связано с языком, например, с номером улицы. |
Уровень подтверждения
Различные возможные значения уровней подтверждения.
Перечисления | |
---|---|
CONFIRMATION_LEVEL_UNSPECIFIED | Значение по умолчанию. Это значение не используется. |
CONFIRMED | Нам удалось убедиться, что этот компонент существует и имеет смысл в контексте остальной части адреса. |
UNCONFIRMED_BUT_PLAUSIBLE | Этот компонент не может быть подтвержден, но вполне вероятно, что он существует. Например, номер улицы в известном допустимом диапазоне номеров на улице, где конкретные номера домов не известны. |
UNCONFIRMED_AND_SUSPICIOUS | Этот компонент не был подтвержден и, скорее всего, ошибочен. Например, район, который не соответствует остальной части адреса. |
Геокодирование
Содержит информацию о месте, куда были геокодированы входные данные.
JSON-представление |
---|
{ "location": { object ( |
Поля | |
---|---|
location | Геокодированное местоположение входных данных. Использование идентификаторов мест предпочтительнее использования адресов, координат широты/долготы или плюсовых кодов. Использование координат при маршрутизации или расчете направлений движения всегда приводит к привязке точки к дороге, ближайшей к этим координатам. Это может быть не дорога, которая быстро или безопасно приведет к месту назначения, и она может находиться не рядом с точкой доступа к объекту. Кроме того, когда местоположение подвергается обратному геокодированию, нет никакой гарантии, что возвращаемый адрес будет соответствовать оригиналу. |
plusCode | Плюс-код, соответствующий |
bounds | Границы геокодированного места. |
featureSizeMeters | Размер геокодированного места в метрах. Это еще одна мера грубости геокодированного местоположения, но по физическому размеру, а не по смысловому значению. |
placeId | PlaceID места, куда геокодируется этот ввод. Дополнительную информацию об идентификаторах мест смотрите здесь . |
placeTypes[] | Тип(ы) места, к которому геокодированы входные данные. Например, |
ШиротаДлительность
Объект, представляющий пару широты и долготы. Это выражается в виде пары двойных чисел, обозначающих градусы широты и градусы долготы. Если не указано иное, этот объект должен соответствовать стандарту WGS84 . Значения должны находиться в пределах нормализованных диапазонов.
JSON-представление |
---|
{ "latitude": number, "longitude": number } |
Поля | |
---|---|
latitude | Широта в градусах. Оно должно находиться в диапазоне [-90,0, +90,0]. |
longitude | Долгота в градусах. Оно должно находиться в диапазоне [-180,0, +180,0]. |
ПлюсКод
Плюс-код ( http://plus.codes ) — это ссылка на местоположение в двух форматах: глобальный код, определяющий прямоугольник размером 14 x 14 м (1/8000 градуса) или меньше, и составной код, заменяющий префикс на ссылку на местоположение.
JSON-представление |
---|
{ "globalCode": string, "compoundCode": string } |
Поля | |
---|---|
globalCode | Глобальный (полный) код места, например «9FWM33GV+HQ», представляющий площадь 1/8000 на 1/8000 градусов (~ 14 на 14 метров). |
compoundCode | Составной код места, например «33GV+HQ, Рамберг, Норвегия», содержащий суффикс глобального кода и заменяющий префикс форматированным именем ссылочного объекта. |
Область просмотра
Окно просмотра широты и долготы, представленное в виде двух диагонально противоположных low
и high
точек. Область просмотра считается закрытой областью, т. е. включает в себя ее границу. Границы широты должны находиться в диапазоне от -90 до 90 градусов включительно, а границы долготы должны находиться в диапазоне от -180 до 180 градусов включительно. Различные случаи включают в себя:
Если
low
=high
, область просмотра состоит из этой единственной точки.Если
low.longitude
>high.longitude
, диапазон долготы инвертируется (окно просмотра пересекает линию долготы в 180 градусов).Если
low.longitude
= -180 градусов иhigh.longitude
= 180 градусов, область просмотра включает все значения долготы.Если
low.longitude
= 180 градусов иhigh.longitude
= -180 градусов, диапазон долготы пуст.Если
low.latitude
>high.latitude
, диапазон широт пуст.
Оба значения low
и high
должны быть заполнены, а представленное поле не может быть пустым (как указано в определениях выше). Пустое окно просмотра приведет к ошибке.
Например, это окно просмотра полностью охватывает Нью-Йорк:
{ "низкая": { "широта": 40,477398, "долгота": -74,259087 }, "высокая": { "широта": 40,91618, "долгота": -73,70018 } }
JSON-представление |
---|
{ "low": { object ( |
Поля | |
---|---|
low | Необходимый. Нижняя точка смотрового окна. |
high | Необходимый. Самая высокая точка смотрового окна. |
АдресМетаданные
Метаданные для адреса. metadata
не могут быть полностью заполнены для каждого адреса, отправленного в API проверки адреса.
JSON-представление |
---|
{ "business": boolean, "poBox": boolean, "residential": boolean } |
Поля | |
---|---|
business | Указывает, что это адрес компании. Если значение не установлено, это означает, что значение неизвестно. |
poBox | Указывает, что это адрес почтового ящика. Если значение не установлено, это означает, что значение неизвестно. |
residential | Указывает, что это адрес проживания. Если значение не установлено, это означает, что значение неизвестно. |
UspsData
Данные USPS для адреса. uspsData
не может быть полностью заполнена для каждого адреса в США или PR, отправленного в API проверки адреса. Рекомендуется интегрировать поля резервного адреса в ответ, если вы используете uspsData в качестве основной части ответа.
JSON-представление |
---|
{
"standardizedAddress": {
object ( |
Поля | |
---|---|
standardizedAddress | Стандартизированный адрес USPS. |
deliveryPointCode | 2-значный код пункта доставки |
deliveryPointCheckDigit | Контрольная цифра пункта доставки. Этот номер добавляется в конец Delivery_point_barcode для механически сканированной почты. Сложение всех цифр Delivery_point_barcode, DeliveryPointCheckDigit, почтового индекса и ZIP+4 вместе должно дать число, кратное 10. |
dpvConfirmation | Возможные значения для подтверждения DPV. Возвращает один символ или не возвращает никакого значения.
|
dpvFootnote | Сноски из проверки точки доставки. Несколько сносок могут быть объединены в одну строку.
|
dpvCmra | Указывает, является ли адрес CMRA (Коммерческое агентство по приему почты) — частной компанией, получающей почту для клиентов. Возвращает один символ.
|
dpvVacant | Это место свободно? Возвращает один символ.
|
dpvNoStat | Это адрес без статистики или активный адрес? Статистические адреса – это адреса, которые не заняты постоянно, или адреса, которые USPS не обслуживает. Возвращает один символ.
|
dpvNoStatReasonCode | Указывает тип NoStat. Возвращает код причины в виде int.
|
dpvDrop | Флаг указывает, что почта доставляется к одному получателю на сайте. Возвращает один символ.
|
dpvThrowback | Указывает, что почта не доставляется по указанному адресу. Возвращает один символ.
|
dpvNonDeliveryDays | Флаг указывает, что доставка почты осуществляется не каждый день недели. Возвращает один символ.
|
dpvNonDeliveryDaysValues | Целое число, обозначающее дни недоставки. Его можно запросить с помощью битовых флагов: 0x40 – воскресенье – день недоставки 0x20 – понедельник – день недоставки 0x10 – вторник – день недоставки 0x08 – среда – день недоставки 0x04 – четверг – день недоставки -день доставки 0x02 – пятница – нерабочий день 0x01 – суббота – недоставочный день |
dpvNoSecureLocation | Флаг указывает, что дверь доступна, но посылка не будет оставлена из соображений безопасности. Возвращает один символ.
|
dpvPbsa | Указывает, что адрес соответствует записи PBSA. Возвращает один символ.
|
dpvDoorNotAccessible | Флаг указывает адреса, по которым USPS не может постучать в дверь для доставки почты. Возвращает один символ.
|
dpvEnhancedDeliveryCode | Указывает, что для адреса допустимо более одного кода возврата DPV. Возвращает один символ.
|
carrierRoute | Код маршрута перевозчика. Четырехзначный код, состоящий из однобуквенного префикса и трехзначного обозначения маршрута. Префиксы:
|
carrierRouteIndicator | Индикатор сортировки тарифов маршрута оператора связи. |
ewsNoMatch | Адрес доставки сопоставляется, но файл EWS указывает, что точное совпадение скоро будет доступно. |
postOfficeCity | Главпочтамт города. |
postOfficeState | Состояние Главпочтамта. |
abbreviatedCity | Сокращенный город. |
fipsCountyCode | Код страны ФИПС. |
county | Название округа. |
elotNumber | Номер расширенной линии путешествия (eLOT). |
elotFlag | eLOT восходящий/нисходящий флаг (A/D). |
lacsLinkReturnCode | Код возврата LACSLink. |
lacsLinkIndicator | Индикатор LACSLink. |
poBoxOnlyPostalCode | Почтовый ящик только почтовый индекс. |
suitelinkFootnote | Сноски от сопоставления записей об улицах или высотных зданиях с информацией об апартаментах. Если совпадение названия компании обнаружено, возвращается дополнительный номер.
|
pmbDesignator | Обозначение единицы PMB (частный почтовый ящик). |
pmbNumber | номер PMB (личного почтового ящика); |
addressRecordType | Тип записи адреса, соответствующий входному адресу.
|
defaultAddress | Индикатор того, что найден адрес по умолчанию, но существуют более конкретные адреса. |
errorMessage | Сообщение об ошибке при получении данных USPS. Он заполняется, когда обработка USPS приостанавливается из-за обнаружения искусственно созданных адресов. При наличии этой ошибки поля данных USPS могут быть не заполнены. |
cassProcessed | Индикатор того, что запрос CASS обработан. |
UspsАдрес
Представление USPS адреса в США.
JSON-представление |
---|
{ "firstAddressLine": string, "firm": string, "secondAddressLine": string, "urbanization": string, "cityStateZipAddressLine": string, "city": string, "state": string, "zipCode": string, "zipCodeExtension": string } |
Поля | |
---|---|
firstAddressLine | Первая адресная строка. |
firm | Название фирмы. |
secondAddressLine | Вторая адресная строка. |
urbanization | Название пуэрториканской урбанизации. |
cityStateZipAddressLine | Город + штат + почтовый индекс. |
city | Название города. |
state | Двухбуквенный код штата. |
zipCode | Почтовый индекс, например, 10009. |
zipCodeExtension | Расширение почтового индекса из 4 цифр, например 5023. |
- HTTP-запрос
- Тело запроса
- Тело ответа
- Почтовый адрес
- Языковые параметры
- Результат проверки
- Вердикт
- Детализация
- Адрес
- Адресный компонент
- ИмяКомпонента
- Уровень подтверждения
- Геокодирование
- ШиротаДлительность
- ПлюсКод
- Область просмотра
- АдресМетаданные
- UspsData
- UspsАдрес
Проверяет адрес.
HTTP-запрос
POST https://addressvalidation.googleapis.com/v1:validateAddress
URL-адрес использует синтаксис транскодирования gRPC .
Тело запроса
Тело запроса содержит данные следующей структуры:
JSON-представление |
---|
{ "address": { object ( |
Поля | |
---|---|
address | Необходимый. Адрес проверяется. Неформатированные адреса следует отправлять через Общая длина полей в этом вводе не должна превышать 280 символов. Поддерживаемые регионы можно найти здесь . Значение API проверки адреса игнорирует значения |
previousResponseId | Это поле должно быть пустым для первого запроса на проверку адреса. Если для полной проверки одного адреса необходимо больше запросов (например, если изменения, внесенные пользователем после первоначальной проверки, необходимо повторно проверить), то каждый последующий запрос должен заполнить это поле идентификатором |
enableUspsCass | Включает USPS CASS -совместимый режим. Это влияет только на Рекомендуется использовать компонентный |
languageOptions | Необязательный. Предварительный просмотр: эта функция находится в предварительном просмотре (Pre-GA). Продукты и функции Pre-GA могут иметь ограниченную поддержку, а изменения в продуктах и функциях Pre-GA могут быть совместимы с другими версиями до GA. Предложения предварительного GA охватываются специфическими условиями службы платформы Google Maps . Для получения дополнительной информации см. Описания этапа запуска . Позволяет API проверки адреса включить дополнительную информацию в ответ. |
sessionToken | Необязательный. Строка, которая идентифицирует сеанс автозаполнения для выставления счетов. Должен быть url и имен файла безопасной базовой 64 строки с максимум 36 символов ASCII в длину. В противном случае возвращается ошибка valud_argument. Сеанс начинается, когда пользователь делает автозаполненный запрос, и завершается, когда он выбирает место, и вызов для размещения данных или проверки адреса. Каждый сеанс может иметь несколько автозаполненных запросов, за которыми следуют сведения об одном месте или запрос на проверку адреса. Учетные данные, используемые для каждого запроса в сеансе, должны принадлежать к одному и тому же проекту Cloud Console Google. Как только сессия завершится, токен больше не является действительным; Ваше приложение должно генерировать свежий токен для каждого сеанса. Если параметр ПРИМЕЧАНИЕ. Проверка адреса может использоваться только в сеансах с API автозаполнения (нового), а не API автозаполнения. См . |
Тело ответа
Ответ на запрос на проверку адреса.
В случае успеха тело ответа содержит данные со следующей структурой:
Представление JSON |
---|
{
"result": {
object ( |
Поля | |
---|---|
result | Результат проверки адреса. |
responseId | UUID, который идентифицирует этот ответ. Если адрес должен быть повторно оценен, этот UUID должен сопровождать новый запрос. |
Почтовый адрес
Представляет почтовый адрес, например, для почтовых доставки или платежных адресов. Учитывая почтовый адрес, почтовый сервис может доставлять предметы в предпосылку, ящик для PO или аналогичный. Он не предназначен для моделирования географических мест (дороги, города, горы).
В типичном использовании адрес будет создан с помощью пользовательского ввода или от импорта существующих данных, в зависимости от типа процесса.
Консультации по адресу адреса/редактирование: - Используйте виджет адреса, готовый к интернационализации, такой как https://github.com/google/libaddressinput ). использовал.
Для получения дополнительных рекомендаций о том, как использовать эту схему, см.: Https://support.google.com/business/answer/6397478
Представление JSON |
---|
{ "revision": integer, "regionCode": string, "languageCode": string, "postalCode": string, "sortingCode": string, "administrativeArea": string, "locality": string, "sublocality": string, "addressLines": [ string ], "recipients": [ string ], "organization": string } |
Поля | |
---|---|
revision | Редакция схемы |
regionCode | Необязательный. Кодекс региона CLDR страны/регион адреса. См. Https://cldr.unicode.org/ и https://www.unicode.org/cldr/charts/30/supplemental/territory_information.html для получения подробной информации. Пример: «Ch» для Швейцарии. Если код региона не предоставлен, он будет выведен из адреса. Для достижения наилучшей производительности рекомендуется включить код региона, если вы его знаете. Например, наличие непоследовательных или повторных регионов может привести к плохой производительности, например, если |
languageCode | Языковой код в входном адресе зарезервирован для будущего использования и игнорируется сегодня. API возвращает адрес на соответствующем языке, где находится адрес. |
postalCode | Необязательный. Почтовый код адреса. Не все страны используют или требуют присутствия почтовых кодов, но там, где они используются, они могут вызвать дополнительную проверку с другими частями адреса (например, проверка состояния/ZIP в США). |
sortingCode | Необязательный. Дополнительный, страновой, сортировочный код. Это не используется в большинстве регионов. Там, где он используется, значение представляет собой либо строку, подобную «cedex», при необходимости, за которым следует число (например, «cedex 7»), либо только число, представляющее «код сектора» (Ямайка), «Индикатор зоны доставки» (Малави) или «Индикатор почтового отделения» (например, Кот д'Ивуар). |
administrativeArea | Необязательный. Наибольшее административное подразделение, которое используется для почтовых адресов страны или региона. Например, это может быть государство, провинция, область или префектура. В частности, для Испании это провинция, а не автономное сообщество (например, «Барселона», а не «каталония»). Многие страны не используют административный район в почтовых адресах. Например, в Швейцарии это должно быть оставлено незападным. |
locality | Необязательный. Как правило, относится к городу/городской части адреса. Примеры: Американский город, IT Comune, Великобритания, почтовый город. В регионах мира, где населенные пункты не очень хорошо определены или не вписываются в эту структуру, оставляйте местность пустыми и используйте адресные линии. |
sublocality | Необязательный. Сублокальность адреса. Например, это могут быть окрестности, районы, районы. |
addressLines[] | Необходимый. Неструктурированные адресные линии, описывающие более низкие уровни адреса. |
recipients[] | Пожалуйста, избегайте установления этого поля. API проверки адреса в настоящее время не использует его. Хотя в настоящее время API не будет отклонять запросы с помощью этого поля, информация будет отброшена и не будет возвращена в ответ. |
organization | Пожалуйста, избегайте установления этого поля. API проверки адреса в настоящее время не использует его. Хотя в настоящее время API не будет отклонять запросы с помощью этого поля, информация будет отброшена и не будет возвращена в ответ. |
LanguageOptions
Предварительный просмотр: эта функция находится в предварительном просмотре (Pre-GA). Продукты и функции Pre-GA могут иметь ограниченную поддержку, а изменения в продуктах и функциях Pre-GA могут быть совместимы с другими версиями до GA. Предложения предварительного GA охватываются специфическими условиями службы платформы Google Maps . Для получения дополнительной информации см. Описания этапа запуска .
Позволяет API проверки адреса включить дополнительную информацию в ответ.
Представление JSON |
---|
{ "returnEnglishLatinAddress": boolean } |
Поля | |
---|---|
returnEnglishLatinAddress | Предварительный просмотр: вернуть |
ValidationResult
Результат проверки адреса.
Представление JSON |
---|
{ "verdict": { object ( |
Поля | |
---|---|
verdict | Общие флаги вердикта |
address | Информация об самом адресе, в отличие от геокода. |
geocode | Информация о местоположении и размещении, к которому адресовал адрес. |
metadata | Другая информация, относящаяся к доставке. |
uspsData | Дополнительные флаги доставки, предоставленные USPS. Предоставлено только в регионе |
englishLatinAddress | Предварительный просмотр: эта функция находится в предварительном просмотре (Pre-GA). Продукты и функции Pre-GA могут иметь ограниченную поддержку, а изменения в продуктах и функциях Pre-GA могут быть совместимы с другими версиями Pre-GA. Предложения предварительного GA охватываются специфическими условиями службы платформы Google Maps . Для получения дополнительной информации см. Описания этапа запуска . Адрес переведен на английский. Переведенные адреса не используются в качестве ввода API. Сервис предоставляет им так, чтобы пользователь мог использовать свой родной язык для подтверждения или опровержения проверки первоначально предоставленного адреса. Если часть адреса не имеет английского перевода, сервис возвращает эту часть на альтернативном языке, который использует латинский сценарий. Смотрите здесь для объяснения того, как выбран альтернативный язык. Если часть адреса не имеет никаких переводов или трансляций на языке, который использует латинский сценарий, сервис возвращает эту часть на локальном языке, связанном с адресом. Включите этот вывод, используя ПРИМЕЧАНИЕ. |
Вердикт
Обзор высокого уровня результата проверки адреса и GeoCode.
Представление JSON |
---|
{ "inputGranularity": enum ( |
Поля | |
---|---|
inputGranularity | Гранулярность входного адреса. Это результат анализа входного адреса и не дает никаких сигналов валидации. Для сигналов проверки см. В соответствии с Например, если входной адрес включает в себя конкретный номер квартиры, то |
validationGranularity | Уровень детализации, на который API может полностью подтвердить адрес. Например, Результат проверки компонента адреса можно найти в |
geocodeGranularity | Информация о гранулярности Это может отличаться от |
addressComplete | Адрес считается завершенным, если нет неразрешенных токенов, нет неожиданных компонентов или недостающих адресов. Если нет, указывает, что значение |
hasUnconfirmedComponents | По крайней мере, один компонент адреса не может быть классифицирован или проверен, см. |
hasInferredComponents | По крайней мере, один компонент адреса был выведен (добавлен), который не был в вводе, см. |
hasReplacedComponents | По крайней мере, один компонент адреса был заменен, см. |
Гранулярность
Различные детали, которые могут иметь адрес или геокод. При использовании для обозначения гранулярности для адреса эти значения указывают, насколько хороша гранулярность, адрес идентифицирует пункт назначения рассылки. Например, адрес, такой как «123 Main Street, Redwood City, CA, 94061», определяет PREMISE
в то время как что -то вроде «Redwood City, CA, 94061», определяет LOCALITY
. Однако, если мы не сможем найти геокоду для «123 Main Street» в Редвуд -Сити, возвращение GeoCode может иметь гранулярность LOCALITY
, даже если адрес более детальный.
Перечисления | |
---|---|
GRANULARITY_UNSPECIFIED | Значение по умолчанию. Это значение не используется. |
SUB_PREMISE | Результат уровня ниже строительства, например, квартира. |
PREMISE | Результат уровня здания. |
PREMISE_PROXIMITY | Геокод, который приближается к расположению уровня здания адреса. |
BLOCK | Адрес или геокод указывает блок. Используется только в регионах, которые имеют адресацию уровня блока, такие как Япония. |
ROUTE | Геокод или адрес гранулирован для маршрута, например, улица, дорога или шоссе. |
OTHER | Все остальные детали, которые объединяются вместе, поскольку они не доставляются. |
Адрес
Подробная информация о пост-обработанном адресе. Пост-обработка включает в себя корректирующие части с ошибками, замену неверных деталей и вывод пропущенных деталей.
Представление JSON |
---|
{ "formattedAddress": string, "postalAddress": { object ( |
Поля | |
---|---|
formattedAddress | Постопросимый адрес, отформатированный в виде однострочного адреса по правилам форматирования адреса региона, где находится адрес. |
postalAddress | Пост-обрабощенный адрес, представленный в качестве почтового адреса. |
addressComponents[] | Неупорядоченный список. Индивидуальные компоненты адреса форматированного и исправленного адреса вместе с информацией о проверке. Это предоставляет информацию о статусе проверки отдельных компонентов. Компоненты адресов не упорядочены определенным образом. Не делайте никаких предположений о заказе компонентов адреса в списке. |
missingComponentTypes[] | Типы компонентов, которые, как ожидалось, будут присутствовать в правильно отформатированном почтовом адресе, но не были обнаружены на входе и не могли быть выведены. Компоненты этого типа не присутствуют в |
unconfirmedComponentTypes[] | Типы компонентов, которые присутствуют в |
unresolvedTokens[] | Любые токены на входе, которые не могут быть разрешены. Это может быть вход, который не был признан в качестве допустимой части адреса (например, на таком входе, как «1232352532533 Main St, Сан -Франциско, Калифорния, 94105», неразрешенные токены могут выглядеть как |
AddressComponent
Представляет собой адресный компонент, такой как улица, город или штат.
Представление JSON |
---|
{ "componentName": { object ( |
Поля | |
---|---|
componentName | Имя для этого компонента. |
componentType | Тип компонента адреса. См. Таблицу 2: Дополнительные типы, возвращаемые службой мест для списка возможных типов. |
confirmationLevel | Указывает уровень уверенности, который у нас есть, что компонент правильный. |
inferred | Указывает, что компонент не был частью ввода, но мы сделали это для местоположения адреса и считаем, что он должен быть предоставлен для полного адреса. |
spellCorrected | Указывает коррекцию к неправильному написанию в имени компонента. API не всегда изменяет изменения от одного варианта орфографии к другому, например, при изменении «центра» на «Центр». Это также не всегда отмечает общие ошибки, например, при изменении «Amphitheater pkwy» на «Amphitheater pkwy». |
replaced | Указывает, что имя компонента было заменено совершенно другим, например, неправильным почтовым кодом, который заменяется тем, который является правильным для адреса. Это не косметическое изменение, входной компонент был изменен на другой. |
unexpected | Указывает адресный компонент, который не будет присутствовать в почтовом адресе для данного региона. Мы сохранили его только потому, что это было частью ввода. |
Компонент
Обертка для названия компонента.
Представление JSON |
---|
{ "text": string, "languageCode": string } |
Поля | |
---|---|
text | Название текст. Например, «5 -я авеню» для названия улицы или «1253» для номера улицы. |
languageCode | Языковой код BCP-47. Это не будет присутствовать, если имя компонента не связано с языком, таким как номер улицы. |
Подтверждение
Различные возможные значения для уровней подтверждения.
Перечисления | |
---|---|
CONFIRMATION_LEVEL_UNSPECIFIED | Значение по умолчанию. Это значение не используется. |
CONFIRMED | Мы смогли убедиться, что этот компонент существует и имеет смысл в контексте остальной части адреса. |
UNCONFIRMED_BUT_PLAUSIBLE | Этот компонент не может быть подтвержден, но вполне вероятно, что он существует. Например, номер улицы в известном достоверном диапазоне чисел на улице, где конкретные номера домов не известны. |
UNCONFIRMED_AND_SUSPICIOUS | Этот компонент не был подтвержден и, вероятно, ошибается. Например, район, который не соответствует остальной части адреса. |
Геокод
Содержит информацию о месте, в котором входы геокодировали.
Представление JSON |
---|
{ "location": { object ( |
Поля | |
---|---|
location | Геокодированное местоположение ввода. Использование идентификаторов места предпочтительнее использования адресов, координат широты/долготы или плюс коды. Использование координат при маршрутизации или расчете направлений вождения всегда приведет к тому, что точка переходит к дороге, ближайшей к этим координатам. Это не может быть дорогой, которая быстро или безопасно приведет к пункту назначения и не может быть рядом с точкой доступа к собственности. Кроме того, когда местоположение будет геокодировать, нет никакой гарантии, что возвращенный адрес будет соответствовать оригиналу. |
plusCode | Плюс код, соответствующий |
bounds | Границы геокодированного места. |
featureSizeMeters | Размер геокодированного места, в метрах. Это еще одна мера грубости геокодированного местоположения, но в физическом размере, а не в семантическом значении. |
placeId | Плосеид этого места в этом входном геокоде. Для получения дополнительной информации о идентификаторах места см. Здесь . |
placeTypes[] | Тип (ы) места, которое входные геокодировали. Например, |
Латлнг
Объект, который представляет собой пару широты/долготы. Это выражается как пара удвоений, представляющих градус широты и градусов долготы. Если не указано иное, этот объект должен соответствовать стандарту WGS84 . Значения должны быть в пределах нормализованных диапазонов.
Представление JSON |
---|
{ "latitude": number, "longitude": number } |
Поля | |
---|---|
latitude | Широта в градусах. Это должно быть в диапазоне [-90.0, +90.0]. |
longitude | Долгота в градусах. Это должно быть в диапазоне [-180.0, +180.0]. |
PlusCode
Plus Code ( http://plus.codes ) - это ссылка на местоположение с двумя форматами: глобальный код, определяющий 14mx14m (1/8000 в такой степени) или меньший прямоугольник, и составной код, заменив префикс на эталонном месте.
Представление JSON |
---|
{ "globalCode": string, "compoundCode": string } |
Поля | |
---|---|
globalCode | Глобальный (полный) код Place, такой как «9FWM33GV+HQ», представляющий площадь 1/8000 на 1/8000 градусов (~ 14 на 14 метров). |
compoundCode | Составной код Place, такой как «33GV+HQ, Ramberg, Norway», содержащий суффикс глобального кода и замена префикса с форматированным именем эталонного объекта. |
ViewPort
Широта длительного просмотра, представленное как два диагонали напротив low
и high
точек. Viewport считается закрытым регионом, то есть он включает в себя свою границу. Границы широты должны варьироваться от -90 до 90 градусов включено, а границы долготы должны варьироваться от -180 до 180 градусов включено. Различные случаи включают:
Если
low
=high
, топорт Views состоит из этой единственной точки.Если
low.longitude
>high.longitude
.Если
low.longitude
= -180 градусов иhigh.longitude
.Если
low.longitude
Longity = 180 градусов иhigh.longitude
Longity = -180 градусов, диапазон долготы пуст.Если
low.latitude
>high.latitude
Latitude, диапазон широты пуст.
Как low
, так и high
должен быть заполнен, а представленная коробка не может быть пустой (как указано по определениям выше). Пустой вид просмотра приведет к ошибке.
Например, этот вид VIELE полностью прилагает Нью -Йорк:
{"low": {"Latitude": 40.477398, "Londitude": -74.259087}, "High": {"Latitude": 40.91618, "Londitude": -73.70018}}}}}}}}}}}}}}}}}}}}}}}}}}}}}}
Представление JSON |
---|
{ "low": { object ( |
Поля | |
---|---|
low | Необходимый. Низкая точка просмотра. |
high | Необходимый. Высшая точка просмотра. |
AddrestAdata
Метаданные для адреса. metadata
не гарантированно будут полностью заполнены для каждого адреса, отправленного в API проверки адреса.
Представление JSON |
---|
{ "business": boolean, "poBox": boolean, "residential": boolean } |
Поля | |
---|---|
business | Указывает, что это адрес бизнеса. Если нет, указывает, что значение неизвестно. |
poBox | Указывает, что адрес ящика PO. Если нет, указывает, что значение неизвестно. |
residential | Указывает, что это адрес резиденции. Если нет, указывает, что значение неизвестно. |
USPSDATA
Данные USPS для адреса. uspsData
не гарантированно будет полностью заполнен для каждого адреса США или PR, отправленного в API проверки адреса. Рекомендуется интегрировать поля адреса резервного копирования в ответ, если вы используете USPSData в качестве основной части ответа.
Представление JSON |
---|
{
"standardizedAddress": {
object ( |
Поля | |
---|---|
standardizedAddress | USPS стандартизированный адрес. |
deliveryPointCode | 2 -значный код точки доставки |
deliveryPointCheckDigit | Цифровая цифра с доставкой. Этот номер добавляется к окончанию доставки_POINT_BARCODE для механического сканируемого почты. Добавление всех цифр доставки_point_barcode, reworkypointcheckdigit, почтового кода и Zip+4 вместе должен дать число делится на 10. |
dpvConfirmation | Возможные значения для подтверждения DPV. Возвращает один символ или не возвращает значения.
|
dpvFootnote | Сноски от проверки точки доставки. Несколько сносков могут быть связаны вместе в одной струне.
|
dpvCmra | Указывает, является ли адрес CMRA (агентство по получению коммерческой почты)-частное бизнес, получающий почту для клиентов. Возвращает одного персонажа.
|
dpvVacant | Это место свободным? Возвращает одного персонажа.
|
dpvNoStat | Это адрес без статистики или активный адрес? Никакие адреса статистики не являются те, которые не постоянно заняты или адреса, которые USP не обслуживают. Возвращает одного персонажа.
|
dpvNoStatReasonCode | Указывает тип ностата. Возвращает код причины как int.
|
dpvDrop | Флаг указывает, что почта доставляется в один восприимчивый на сайте. Возвращает одного персонажа.
|
dpvThrowback | Указывает, что почта не доставляется по адресу улицы. Возвращает одного персонажа.
|
dpvNonDeliveryDays | Флаг указывает, что доставка почты не выполняется каждый день недели. Возвращает одного персонажа.
|
dpvNonDeliveryDaysValues | Целое число идентифицирует дни без доставки. Его можно допросить с использованием битовых флагов: 0x40-воскресенье-день без доставки 0x20-понедельник-день без доставки 0x10-вторник-день без доставки 0x08-среда-день без доставки 0x04-четверг не является нон. -Длевина День 0x02-пятница-день без доставки 0x01-Суббота-день без доставки |
dpvNoSecureLocation | Флаг указывает, что дверь доступна, но пакет не останется из -за проблем безопасности. Возвращает одного персонажа.
|
dpvPbsa | Указывает, что адрес был сопоставлен с записью PBSA. Возвращает одного персонажа.
|
dpvDoorNotAccessible | Флаг указывает адреса, где USPS не может постучать в дверь для доставки почты. Возвращает одного персонажа.
|
dpvEnhancedDeliveryCode | Указывает, что для адреса действительнее более одного кода возврата DPV. Возвращает одного персонажа.
|
carrierRoute | Код маршрута перевозчика. Четыре кода символа, состоящий из префикса одной буквы и трехзначного обозначения маршрута. Префиксы:
|
carrierRouteIndicator | Индикатор сортировки скорости маршрута перевозчика. |
ewsNoMatch | Адрес доставки подходит, но файл EWS указывает, что в ближайшее время будет доступно точное совпадение. |
postOfficeCity | Главное почтовое отделение города. |
postOfficeState | Основное государство почтового отделения. |
abbreviatedCity | Сокращенный город. |
fipsCountyCode | Кодекс округа Фипс. |
county | Имя округа. |
elotNumber | Усовершенствованная линия путешествия (ELOT). |
elotFlag | ЭКОЛОТ АНЦИПАНСКИЙ/УГОДНЫЙ ФЛАГ (A/D). |
lacsLinkReturnCode | Код возврата lacslink. |
lacsLinkIndicator | Индикатор LACSLINK. |
poBoxOnlyPostalCode | Ящик для почтового ящика. |
suitelinkFootnote | Сноски от сопоставления уличной или высокой записи с информацией. Если сопоставление названия бизнеса найдено, второстепенное число возвращается.
|
pmbDesignator | PMB (Private Mail Box) Устройство устройства. |
pmbNumber | PMB (частный почтовый ящик) номер; |
addressRecordType | Тип адресной записи, которая соответствует входному адресу.
|
defaultAddress | Индикатор того, что адрес по умолчанию был найден, но существуют более конкретные адреса. |
errorMessage | Сообщение об ошибке для поиска данных USPS. Это заполнено, когда обработка USPS приостановлена из -за обнаружения искусственно созданных адресов. Поля данных USPS не могут быть заполнены, когда присутствует эта ошибка. |
cassProcessed | Индикатор того, что запрос был обработан CASS. |
Uspsaddress
USPS представление адреса США.
Представление JSON |
---|
{ "firstAddressLine": string, "firm": string, "secondAddressLine": string, "urbanization": string, "cityStateZipAddressLine": string, "city": string, "state": string, "zipCode": string, "zipCodeExtension": string } |
Поля | |
---|---|
firstAddressLine | Первая адресная строка. |
firm | Название фирмы. |
secondAddressLine | Вторая адресная строка. |
urbanization | Пуэрториканское имя урбанизации. |
cityStateZipAddressLine | Город + государство + почтовый код. |
city | Название города. |
state | 2 буквенного состояния код. |
zipCode | Почтовый код, например, 10009. |
zipCodeExtension | 4-значное расширение почтового кода, например, 5023. |