API проверки адреса предоставляет тело ответа в виде объекта JSON, содержащего два свойства верхнего уровня:
-
result
— объект типаValidationResult
-
responseID
{
"result": {
// Validation verdict.
"verdict": {},
// Address details determined by the API.
"address": {},
// The geocode generated for the input address.
"geocode": {},
// Information indicating if the address is a business, residence, etc.
"metadata": {},
// Information about the address from the US Postal Service
// ("US" and "PR" addresses only).
"uspsData": {},
},
// A unique identifier generated for every request to the API.
"responseId": "ID"
}
В этом документе основное внимание уделяется объекту result
. Дополнительные сведения об responseID
см. в разделе Обработка обновленных адресов .
verdict
собственности
Свойство verdict
суммирует результаты проверки адреса и должно быть первым свойством, которое необходимо оценить при построении логики проверки адреса. Свойство может возвращать различные поля, в зависимости от качества выходного адреса. Например, ниже показано свойство verdict
адреса хорошего качества, которое возвращает 4 поля для этого конкретного запроса:
"verdict": {
"inputGranularity": "PREMISE",
"validationGranularity": "PREMISE",
"geocodeGranularity": "PREMISE",
"addressComplete": true
}
В следующих разделах суммируются все поля свойства verdict
.
См. Вердикт в справочном руководстве. |
Детализация адреса
Детализация адреса относится к уровню детализации, используемому при определении специфики адреса или геокода. Специфичность адреса в ответе validationGranularity
является ключевым сигналом того, можно ли доставить адрес.
Свойство verdict
возвращает следующие сигналы детализации:
-
inputGranularity
— описывает уровень детализации, полученной из адреса, отправленного в API проверки адреса. Уровень детализации адреса в запросе влияет на уровень детализации адреса в ответе проверки. Например, адрес сinputGranularity
ниже уровняPREMISE
ниже уровня PREMISE обычно не приводит к тому, что уровеньvalidationGranularity
достигает уровняPREMISE
. -
validationGranularity
— уровень детализации, на котором API проверки адреса может полностью проверить адрес. В большинстве случаев уровень детализацииPREMISE
илиSUB_PREMISE
указывает на качественный адрес, который, скорее всего, будет доставлен. -
geocodeGranularity
— описывает уровень детализации геокода, связанного с адресом. Например, записи Google могут указывать на наличие номера квартиры, но не на точное местоположение этой конкретной квартиры в большом жилом комплексе. В этом случаеvalidationGranularity
— этоSUB_PREMISE
, аgeocodeGranularity
is
PREMISE`.
См. раздел «Детализация» в справочном руководстве. |
Полнота адреса
Вердикт возвращает свойство addressComplete
как сигнал о высококачественном адресе, что означает, в частности, что в нем нет недостающих, неразрешенных или неожиданных компонентов:
"verdict": {
"inputGranularity": "PREMISE",
"validationGranularity": "PREMISE",
"geocodeGranularity": "PREMISE",
"addressComplete": true
}
Если в адресе отсутствуют, неразрешенные или неожиданные компоненты, в поле устанавливается значение false
.
См. addressComplete в разделах «Вердикт» и «Адрес» справочного руководства. |
Качество адреса
Ряд возможных полей указывает либо на проблемы с компонентами адреса, либо на их корректировки, например предполагаемые или отсутствующие компоненты адреса. Например, следующее свойство verdict
указывает адрес с неподтвержденными компонентами и отсутствующим полем addressComplete
:
"verdict": {
"inputGranularity": "PREMISE",
"validationGranularity": "OTHER",
"geocodeGranularity": "OTHER",
"hasUnconfirmedComponents": true,
"hasInferredComponents": true
}
См. Вердикт в справочном руководстве. |
Свойства address
и addressComponent
Свойство address
обеспечивает форматирование обработанного адреса, указанного в запросе, а также сводные данные адреса на уровне компонентов, включая части адреса с ошибками, замененные неправильные части и предполагаемые недостающие части.
См. Address в справочном руководстве. |
Свойство addressComponent
— это подкомпонент address
, который предоставляет подробный список элементов (или компонентов) адреса, обработанного API проверки адреса. API идентифицирует каждое поле компонента по его имени, типу и уровню подтверждения.
См. addressComponent в справочном руководстве. |
Свойство geocode
Свойство geocode
указывает геокодированное местоположение, связанное с входным адресом. Это свойство предоставляет подробную информацию о самом местоположении, например его идентификатор места.
См. Geocode в справочном руководстве. |
Свойство metadata
Это свойство может не заполняться для каждого адреса, обрабатываемого API проверки адреса, но указывает, является ли адрес жилым, деловым или почтовым ящиком.
См. описание API проверки адреса и ссылку на Address metadata . |
Свойство uspsData
Это свойство предоставляет полезную информацию о почтовых адресах США. Однако не гарантируется, что он будет полностью заполнен для каждого адреса, проверенного службой. По этой причине вам не следует полагаться на это свойство как на единственное средство проверки адресов, а вместо этого также проверять verdict
и address
.
См. раздел «Обработка адресов в США» и ссылку на UspsData . |