Method: validateAddress

Valida um endereço.

Solicitação HTTP

POST https://addressvalidation.googleapis.com/v1:validateAddress

O URL usa a sintaxe de transcodificação gRPC.

Corpo da solicitação

O corpo da solicitação contém dados com a seguinte estrutura:

Representação JSON
{
  "address": {
    object (PostalAddress)
  },
  "previousResponseId": string,
  "enableUspsCass": boolean,
  "languageOptions": {
    object (LanguageOptions)
  },
  "sessionToken": string
}
Campos
address

object (PostalAddress)

Obrigatório. O endereço que está sendo validado. Endereços não formatados devem ser enviados por addressLines.

O tamanho total dos campos nessa entrada não pode exceder 280 caracteres.

As regiões disponíveis podem ser encontradas aqui.

O valor languageCode no endereço de entrada é reservado para usos futuros e é ignorado hoje. O resultado do endereço validado será preenchido com base no idioma preferido para o endereço fornecido, conforme identificado pelo sistema.

A API Address Validation ignora os valores em recipients e organization. Quaisquer valores nesses campos serão descartados e não serão retornados. Não as defina.

previousResponseId

string

Este campo precisa estar vazio na primeira solicitação de validação de endereço. Se mais solicitações forem necessárias para validar totalmente um único endereço (por exemplo, se as alterações feitas pelo usuário após a validação inicial precisarem ser revalidadas), cada solicitação de acompanhamento precisará preencher esse campo com o responseId desde a primeira resposta na sequência de validação.

enableUspsCass

boolean

Ativa o modo compatível com USPS CASS. Isso afeta apenas o campo google.maps.addressvalidation.v1.ValidationResult.usps_data de google.maps.addressvalidation.v1.ValidationResult. Observação: para solicitações ativadas para endereços em Porto Rico pelo USPS CASS, um google.type.PostalAddress.region_code do address precisa ser fornecido como "PR", ou um google.type.PostalAddress.administrative_area do address precisa ser fornecido como "Porto Rico" (não diferencia maiúsculas de minúsculas) ou "PR".

É recomendável usar um address componente ou, como alternativa, especificar pelo menos dois google.type.PostalAddress.address_lines, em que a primeira linha contém o número e o nome da rua, e a segunda linha contém a cidade, o estado e o CEP.

languageOptions

object (LanguageOptions)

Opcional. Pré-lançamento: esse recurso está em pré-lançamento (pré-GA). Os produtos e recursos em pré-GA têm suporte limitado, e é possível que as mudanças neles não sejam compatíveis com outras versões nessa fase. Todos os produtos em pré-GA são cobertos pelos Termos de Serviço específicos da Plataforma Google Maps. Para mais informações, consulte as descrições da fase de lançamento.

Permite que a API Address Validation inclua informações adicionais na resposta.

sessionToken

string

Opcional. Uma string que identifica uma sessão de preenchimento automático para fins de faturamento. Precisa ser uma string base64 segura para URL e nome de arquivo com no máximo 36 caracteres ASCII. Caso contrário, um erro INVALID_ARGUMENT será retornado.

A sessão começa quando o usuário faz uma consulta do Autocomplete e termina quando seleciona um lugar e faz uma chamada para Place Details ou Address Validation. Cada sessão pode ter várias consultas do Autocomplete, seguidas por uma solicitação do Place Details ou do Address Validation. As credenciais usadas para cada solicitação em uma sessão precisam pertencer ao mesmo projeto do Console do Google Cloud. Após a conclusão de uma sessão, o token deixa de ser válido; seu aplicativo deve gerar um novo token para cada sessão. Se o parâmetro sessionToken for omitido ou você reutilizar um token, a sessão vai ser cobrada como se nenhum token de sessão tivesse sido fornecido (cada solicitação é faturada separadamente).

Observação: a validação de endereço só pode ser usada em sessões com a API Autocomplete (nova), não com a API Autocomplete. Consulte https://developers.google.com/maps/documentation/places/web-service/session-pricing para saber mais detalhes.

Corpo da resposta

A resposta a uma solicitação de validação de endereço.

Se bem-sucedido, o corpo da resposta incluirá dados com a estrutura a seguir:

Representação JSON
{
  "result": {
    object (ValidationResult)
  },
  "responseId": string
}
Campos
result

object (ValidationResult)

O resultado da validação de endereço.

responseId

string

O UUID que identifica essa resposta. Se o endereço precisar ser validado novamente, esse UUID precisa acompanhar a nova solicitação.

PostalAddress

Representa um endereço postal, por exemplo, para endereços para pagamento ou distribuição postal. Com um endereço postal, o serviço de correios pode entregar itens em um local, uma caixa postal ou outro local semelhante. Não se destina a modelar locais geográficos (estradas, cidades, montanhas).

No uso normal, um endereço seria criado por digitação do usuário ou pela importação de dados existentes, dependendo do tipo de processo.

Conselhos sobre entrada / edição de endereço: - Use um widget de endereço pronto para internacionalização, como https://github.com/google/libaddressinput. - Os usuários não devem ver elementos da IU para entrada ou edição de campos fora dos países em que esse campo é usado.

Para mais orientações sobre como usar este esquema, consulte: https://support.google.com/business/answer/6397478.

Representação JSON
{
  "revision": integer,
  "regionCode": string,
  "languageCode": string,
  "postalCode": string,
  "sortingCode": string,
  "administrativeArea": string,
  "locality": string,
  "sublocality": string,
  "addressLines": [
    string
  ],
  "recipients": [
    string
  ],
  "organization": string
}
Campos
revision

integer

A revisão de esquema de PostalAddress. Qualquer valor diferente de 0 faz com que a API retorne um erro INVALID_ARGUMENT.

regionCode

string

Opcional. Código regional CLDR do país/região do endereço. Para mais detalhes, acesse https://cldr.unicode.org/ e https://www.unicode.org/cldr/charts/30/supplemental/territory_information.html. Exemplo: "CH" para Suíça. Se o código regional não for fornecido, ele será inferido com base no endereço. Para o melhor desempenho, é recomendável incluir o código da região, se você souber. Ter regiões inconsistentes ou repetidas pode levar a um desempenho ruim. Por exemplo, se o addressLines já incluir a região, não forneça o código da região novamente neste campo. Consulte as regiões com suporte nas Perguntas frequentes.

languageCode

string

O código do idioma no endereço de entrada é reservado para usos futuros e é ignorado hoje. A API retorna o endereço no idioma apropriado para onde ele está localizado.

postalCode

string

Opcional. Código postal do endereço. Nem todos os países usam ou exigem códigos postais, mas nos locais onde são usados, eles podem desencadear uma validação adicional com outras partes do endereço (por exemplo, validação de estado/CEP nos EUA).

sortingCode

string

Opcional. Código de classificação adicional específico de país. Não é usado na maioria das regiões. Nos locais em que é usado, o valor é uma string como “CEDEX”, que pode ser seguida por um número (por exemplo, “CEDEX 7”), ou apenas um número sozinho, representando o “código do setor” (Jamaica), o “indicador de área de entrega” (Malawi) ou o “indicador de agência de correio” (por exemplo, Costa do Marfim).

administrativeArea

string

Opcional. A maior subdivisão administrativa que é usada para endereços postais de um país ou uma região. Por exemplo, pode ser um estado, uma província, uma zona ou uma prefeitura. Especificamente na Espanha, é a província, e não a comunidade autônoma (por exemplo, “Barcelona”, não “Catalunha”). Muitos países não usam área administrativa em endereços postais. Por exemplo, na Suíça, isso deve ser deixado em branco.

locality

string

Opcional. Geralmente se refere à parte do endereço relativa a cidade/município. Exemplos: cidade nos EUA, comunidade na Itália, distrito postal no Reino Unido. Em regiões onde as localidades não são claramente definidas ou não se encaixam bem nessa estrutura, deixe a localidade em branco e use addressLines.

sublocality

string

Opcional. Sublocalidade do endereço. Por exemplo, pode ser bairro ou distrito.

addressLines[]

string

Obrigatório. Linhas de endereço não estruturadas que descrevem os níveis mais baixos de um endereço.

Como os valores em addressLines não têm informações de tipo e podem conter vários valores em um único campo (por exemplo, "Austin, TX"), é importante que a ordem da linha seja clara. Ela precisa estar em “ordem de envelope” para o país ou região do endereço.

A representação estrutural mínima permitida de um endereço consiste em todas as informações colocadas no addressLines. Se um regionCode não for fornecido, a região será inferida com base nas linhas de endereço.

Criar um endereço que contenha apenas addressLines e a geocodificação é a maneira recomendada de lidar com endereços completamente não estruturados (em vez de adivinhar quais partes do endereço devem ser localidades ou áreas político-administrativas).

recipients[]

string

Evite definir esse campo. A API Address Validation não o usa atualmente. Embora, no momento, a API não recuse solicitações com esse campo definido, as informações serão descartadas e não serão retornadas na resposta.

organization

string

Evite definir esse campo. A API Address Validation não o usa atualmente. Embora, no momento, a API não recuse solicitações com esse campo definido, as informações serão descartadas e não serão retornadas na resposta.

LanguageOptions

Pré-lançamento: esse recurso está em pré-lançamento (pré-GA). Os produtos e recursos em pré-GA têm suporte limitado, e é possível que as mudanças neles não sejam compatíveis com outras versões nessa fase. Todos os produtos em pré-GA são cobertos pelos Termos de Serviço específicos da Plataforma Google Maps. Para mais informações, consulte as descrições da fase de lançamento.

Permite que a API Address Validation inclua informações adicionais na resposta.

Representação JSON
{
  "returnEnglishLatinAddress": boolean
}
Campos
returnEnglishLatinAddress

boolean

Prévia: retorne uma google.maps.addressvalidation.v1.Address em inglês. Consulte google.maps.addressvalidation.v1.ValidationResult.english_latin_address para mais detalhes.

ValidationResult

O resultado da validação de um endereço.

Representação JSON
{
  "verdict": {
    object (Verdict)
  },
  "address": {
    object (Address)
  },
  "geocode": {
    object (Geocode)
  },
  "metadata": {
    object (AddressMetadata)
  },
  "uspsData": {
    object (UspsData)
  },
  "englishLatinAddress": {
    object (Address)
  }
}
Campos
verdict

object (Verdict)

Sinalizações gerais de veredito

address

object (Address)

Informações sobre o endereço em si, não o geocódigo.

geocode

object (Geocode)

Informações sobre o local e o local para o qual o endereço foi geocodificado.

metadata

object (AddressMetadata)

Outras informações relevantes para a capacidade de entrega. Não há garantia de que o metadata será totalmente preenchido para cada endereço enviado à API Address Validation.

uspsData

object (UspsData)

Sinalizações de entrega extra fornecidas pelo USPS. Fornecido somente nas regiões US e PR.

englishLatinAddress

object (Address)

Pré-lançamento: esse recurso está em pré-lançamento (pré-GA). Os produtos e recursos em pré-GA têm suporte limitado, e é possível que as mudanças neles não sejam compatíveis com outras versões nessa fase. Todos os produtos em pré-GA são cobertos pelos Termos de Serviço específicos da Plataforma Google Maps. Para mais informações, consulte as descrições da fase de lançamento.

O endereço traduzido para o inglês.

Endereços traduzidos não são reutilizáveis como entrada da API. O serviço as fornece para que o usuário possa usar o idioma nativo para confirmar ou negar a validação do endereço fornecido originalmente.

Se parte do endereço não tiver uma tradução para o inglês, o serviço retornará essa parte em um idioma alternativo que usa script latino. Clique aqui para uma explicação sobre como o idioma alternativo é selecionado. Se parte do endereço não tiver traduções ou transliterações em um idioma que use script latino, o serviço retornará essa parte no idioma local associado ao endereço.

Ative essa saída usando a sinalização google.maps.addressvalidation.v1.LanguageOptions.return_english_latin_address.

Observação: o campo google.maps.addressvalidation.v1.Address.unconfirmed_component_types em englishLatinAddress e os campos google.maps.addressvalidation.v1.AddressComponent.confirmation_level em englishLatinAddress.address_components não estão preenchidos.

Veredito

Visão geral de alto nível do resultado da validação de endereço e do geocódigo.

Representação JSON
{
  "inputGranularity": enum (Granularity),
  "validationGranularity": enum (Granularity),
  "geocodeGranularity": enum (Granularity),
  "addressComplete": boolean,
  "hasUnconfirmedComponents": boolean,
  "hasInferredComponents": boolean,
  "hasReplacedComponents": boolean
}
Campos
inputGranularity

enum (Granularity)

A granularidade do endereço input. Esse é o resultado da análise do endereço de entrada e não fornece sinais de validação. Para sinais de validação, consulte validationGranularity abaixo.

Por exemplo, se o endereço de entrada incluir um número de apartamento específico, inputGranularity aqui será SUB_PREMISE. Se não for possível fazer a correspondência com o número do apartamento nos bancos de dados ou ele for inválido, o validationGranularity provavelmente vai ser PREMISE ou menos.

validationGranularity

enum (Granularity)

O nível de granularidade em que a API pode validate totalmente o endereço. Por exemplo, um validationGranularity de PREMISE indica que todos os componentes de endereço no nível PREMISE ou mais abrangentes podem ser validados.

O resultado da validação de componente por endereço pode ser encontrado em google.maps.addressvalidation.v1.Address.address_components.

geocodeGranularity

enum (Granularity)

Informações sobre a granularidade de geocode. Isso pode ser entendido como o significado semântico de quão aproximada ou fina é a localização geocodificada.

Às vezes, ele pode ser diferente do validationGranularity acima. Por exemplo, nosso banco de dados pode registrar a existência do número de um apartamento, mas não tem uma localização precisa do apartamento em um grande complexo de apartamentos. Nesse caso, o validationGranularity será SUB_PREMISE, mas o geocodeGranularity será PREMISE.

addressComplete

boolean

O endereço é considerado completo quando não há tokens não resolvidos nem componentes de endereço inesperados ou ausentes. Se não for definido, indica que o valor é false. Consulte os campos missingComponentTypes, unresolvedTokens ou unexpected para saber mais detalhes.

hasUnconfirmedComponents

boolean

Pelo menos um componente de endereço não pode ser categorizado ou validado. Consulte google.maps.addressvalidation.v1.Address.address_components para mais detalhes.

hasInferredComponents

boolean

Pelo menos um componente de endereço foi inferido (adicionado) que não estava na entrada. Consulte google.maps.addressvalidation.v1.Address.address_components para mais detalhes.

hasReplacedComponents

boolean

Pelo menos um componente de endereço foi substituído. Consulte google.maps.addressvalidation.v1.Address.address_components para mais detalhes.

Granularidade

As várias granularidades que um endereço ou geocódigo pode ter. Quando usados para indicar a granularidade de um endereço, esses valores indicam com que granularidade o endereço identifica um destino de correspondência. Por exemplo, um endereço como "123 Main Street, Redwood City, CA, 94061" identifica uma PREMISE, enquanto algo como "Redwood City, CA, 94061" identifica uma LOCALITY. No entanto, se não for possível encontrar um geocódigo para "123 Main Street" em Redwood City, o geocódigo retornado poderá ter granularidade de LOCALITY, mesmo que o endereço seja mais granular.

Enums
GRANULARITY_UNSPECIFIED Valor padrão. Esse valor não é usado.
SUB_PREMISE Resultado abaixo do nível do edifício, como um apartamento.
PREMISE Resultado no nível do edifício.
PREMISE_PROXIMITY Um geocódigo que se aproxima da localização no nível do edifício do endereço.
BLOCK O endereço ou geocódigo indica um bloco. Usado apenas em regiões que têm endereçamento no nível do bloco, como o Japão.
ROUTE O geocódigo ou endereço é granular para um trajeto, como uma rua, estrada ou rodovia.
OTHER Todas as outras granularidades, agrupadas porque não podem ser entregues.

Endereço

Detalhes do endereço pós-processado. O pós-processamento inclui a correção de partes com erros ortográficos do endereço, a substituição de partes incorretas e a inferência de partes ausentes.

Representação JSON
{
  "formattedAddress": string,
  "postalAddress": {
    object (PostalAddress)
  },
  "addressComponents": [
    {
      object (AddressComponent)
    }
  ],
  "missingComponentTypes": [
    string
  ],
  "unconfirmedComponentTypes": [
    string
  ],
  "unresolvedTokens": [
    string
  ]
}
Campos
formattedAddress

string

O endereço pós-processado, formatado como um endereço de linha única, seguindo as regras de formatação de endereço da região onde o endereço está localizado.

postalAddress

object (PostalAddress)

O endereço pós-processado representado como um endereço postal.

addressComponents[]

object (AddressComponent)

Lista não ordenada. Os componentes de endereço individuais do endereço formatado e corrigido, junto com as informações de validação. Assim você vai ter informações sobre o status de validação dos componentes individuais.

Os componentes de endereço não são ordenados de uma maneira específica. Não faça suposições sobre a ordem dos componentes de endereço na lista.

missingComponentTypes[]

string

Os tipos de componentes que deveriam estar presentes em um endereço de correspondência formatado corretamente, mas que não foram encontrados na entrada, E não puderam ser inferidos. Componentes desse tipo não estão presentes em formattedAddress, postalAddress ou addressComponents. Por exemplo, ['street_number', 'route'] para uma entrada como "Boulder, Colorado, 80301, EUA". Você pode encontrar a lista de tipos disponíveis aqui.

unconfirmedComponentTypes[]

string

Os tipos dos componentes que estão presentes no addressComponents, mas não foram confirmados como corretos. Esse campo é fornecido por conveniência: o conteúdo dele é equivalente a iterar o addressComponents para encontrar os tipos de todos os componentes em que confirmationLevel não é CONFIRMED ou a flag inferred não está definida como true. Você pode encontrar a lista de tipos disponíveis aqui.

unresolvedTokens[]

string

Todos os tokens na entrada que não puderam ser resolvidos. Talvez seja uma entrada que não foi reconhecida como parte válida de um endereço. Por exemplo, em uma entrada como "123235253253 Main St, San Francisco, CA, 94105", os tokens não resolvidos podem parecer ["123235253253"], porque esse número não parece ser um número válido.

AddressComponent

Representa um componente de endereço, como uma rua, cidade ou estado.

Representação JSON
{
  "componentName": {
    object (ComponentName)
  },
  "componentType": string,
  "confirmationLevel": enum (ConfirmationLevel),
  "inferred": boolean,
  "spellCorrected": boolean,
  "replaced": boolean,
  "unexpected": boolean
}
Campos
componentName

object (ComponentName)

O nome desse componente.

componentType

string

O tipo do componente de endereço. Consulte a Tabela 2: outros tipos retornados pelo serviço Places para ver uma lista dos tipos possíveis.

confirmationLevel

enum (ConfirmationLevel)

Indica o nível de certeza de que o componente está correto.

inferred

boolean

Indica que o componente não fazia parte da entrada, mas o inferimos para o local do endereço e acreditamos que ele deve ser fornecido para um endereço completo.

spellCorrected

boolean

Indica uma correção de um erro de digitação no nome do componente. A API nem sempre sinaliza alterações de uma variante de ortografia para outra, como ao alterar "centro" para "centro". Ele também nem sempre sinaliza erros ortográficos comuns, como ao alterar "Amphitheater Pkwy" para "Amphitheatre Pkwy".

replaced

boolean

Indica que o nome do componente foi substituído por um totalmente diferente. Por exemplo, um CEP incorreto está sendo substituído por um correto para o endereço. Como essa não é uma mudança estética, o componente de entrada foi alterado para outro diferente.

unexpected

boolean

Indica um componente de endereço que não deve estar presente em um endereço postal da região especificada. Ela foi mantida apenas porque fazia parte da entrada.

ComponentName

Um wrapper para o nome do componente.

Representação JSON
{
  "text": string,
  "languageCode": string
}
Campos
text

string

Texto do nome. Por exemplo, "5th Avenue" para o nome da rua ou "1253" para o número da rua.

languageCode

string

O código de idioma BCP-47. Ele não estará presente se o nome do componente não estiver associado a um idioma, como o número da rua.

ConfirmationLevel

Os diferentes valores possíveis para os níveis de confirmação.

Enums
CONFIRMATION_LEVEL_UNSPECIFIED Valor padrão. Esse valor não é usado.
CONFIRMED Verificamos que esse componente existe e faz sentido no contexto do restante do endereço.
UNCONFIRMED_BUT_PLAUSIBLE Não foi possível confirmar esse componente, mas é plausível que ele exista. Por exemplo, um número dentro de um intervalo válido conhecido de números em uma rua em que os números específicos das casas não são conhecidos.
UNCONFIRMED_AND_SUSPICIOUS Este componente não foi confirmado e provavelmente está errado. Por exemplo, um bairro que não se encaixa no restante do endereço.

Geocodificação

Contém informações sobre o local no qual a entrada foi geocodificada.

Representação JSON
{
  "location": {
    object (LatLng)
  },
  "plusCode": {
    object (PlusCode)
  },
  "bounds": {
    object (Viewport)
  },
  "featureSizeMeters": number,
  "placeId": string,
  "placeTypes": [
    string
  ]
}
Campos
location

object (LatLng)

A localização geocodificada da entrada.

É preferível usar IDs de lugar em vez de endereços, coordenadas de latitude/longitude ou Plus Codes. Usar coordenadas ao criar trajetos ou calcular rotas sempre resultará no direcionamento do ponto para a estrada mais próxima dessas coordenadas. Essa não pode ser uma estrada que leve ao destino com rapidez ou segurança e não pode estar perto de um ponto de acesso à propriedade. Além disso, quando um local é geocodificado inversamente, não há garantia de que o endereço retornado corresponderá ao original.

plusCode

object (PlusCode)

O Plus Code correspondente ao location.

bounds

object (Viewport)

Os limites do lugar geocodificado.

featureSizeMeters

number

O tamanho do lugar geocodificado, em metros. Essa é outra medida da nitidez da localização geocodificada, mas em tamanho físico e não em significado semântico.

placeId

string

O PlaceID do lugar ao qual esta entrada é geocodificada.

Para mais informações sobre IDs de lugares, clique aqui.

placeTypes[]

string

Os tipos de lugar para os quais a entrada foi geocodificada. Por exemplo, ['locality', 'political']. Você pode encontrar a lista completa dos tipos aqui.

LatLng

Um objeto que representa um par de latitude/longitude. Ele é expresso como um par de valores duplos para representar graus de latitude e longitude. A menos que especificado de outra forma, esse objeto precisa estar em conformidade com o padrão WGS84. Os valores precisam estar dentro de intervalos normalizados.

Representação JSON
{
  "latitude": number,
  "longitude": number
}
Campos
latitude

number

A latitude em graus. Precisa estar no intervalo [-90,0, +90,0].

longitude

number

A longitude em graus. Precisa estar no intervalo [-180,0, +180,0].

PlusCode

O Plus Code (http://plus.codes) é uma referência de local com dois formatos: código global que define um 14mx14m (1/8000o de grau) ou retângulo menor e código composto, que substitui o prefixo por um local de referência.

Representação JSON
{
  "globalCode": string,
  "compoundCode": string
}
Campos
globalCode

string

O código global (completo) do lugar, como "9FWM33GV+HQ", que representa uma área de 1/8.000 por 1/8.000 graus (aproximadamente 14 por 14 metros).

compoundCode

string

O código composto do lugar, como "33GV+HQ, Ramberg, Noruega", que contém o sufixo do código global e substitui o prefixo por um nome formatado de uma entidade de referência.

Janela de visualização

Uma janela de visualização de latitude e longitude, representada como dois pontos low e high diagonalmente opostos. Uma janela de visualização é considerada uma região fechada, ou seja, inclui seu limite. Os limites de latitude devem variar de -90 a 90 graus, inclusive, e os limites de longitude devem variar de -180 a 180 graus. Vários casos incluem:

  • Se low = high, a janela de visualização consiste nesse único ponto.

  • Se low.longitude > high.longitude, o intervalo de longitude será invertido (a janela de visualização cruza a linha de longitude de 180 graus).

  • Se low.longitude = -180 graus e high.longitude = 180 graus, a janela de visualização incluirá todas as longitudes.

  • Se low.longitude = 180 graus e high.longitude = -180 graus, o intervalo de longitude ficará vazio.

  • Se low.latitude > high.latitude, o intervalo de latitude estará vazio.

low e high precisam ser preenchidos, e a caixa representada não pode estar vazia (conforme especificado pelas definições acima). Uma janela de visualização vazia vai resultar em erro.

Por exemplo, esta janela de visualização abrange totalmente a cidade de Nova York:

{ "low": { "latitude": 40.477398, "longitude": -74.259087 }, "high": { "latitude": 40.91618, "longitude": -73.70018 } }

Representação JSON
{
  "low": {
    object (LatLng)
  },
  "high": {
    object (LatLng)
  }
}
Campos
low

object (LatLng)

Obrigatório. O ponto inferior da janela de visualização.

high

object (LatLng)

Obrigatório. O ponto alto da janela de visualização.

AddressMetadata

Os metadados do endereço. Não há garantia de que o metadata será totalmente preenchido para cada endereço enviado à API Address Validation.

Representação JSON
{
  "business": boolean,
  "poBox": boolean,
  "residential": boolean
}
Campos
business

boolean

Indica que este é o endereço de uma empresa. Se não for definido, indica que o valor é desconhecido.

poBox

boolean

Indica o endereço de uma caixa postal. Se não for definido, indica que o valor é desconhecido.

residential

boolean

Indica que é o endereço de uma residência. Se não for definido, indica que o valor é desconhecido.

UspsData

Os dados do USPS para o endereço. Não é garantido que o uspsData será totalmente preenchido para cada endereço dos EUA ou PR enviado à API Address Validation. É recomendável integrar os campos de endereço de backup na resposta se você utilizar uspsData como a parte principal da resposta.

Representação JSON
{
  "standardizedAddress": {
    object (UspsAddress)
  },
  "deliveryPointCode": string,
  "deliveryPointCheckDigit": string,
  "dpvConfirmation": string,
  "dpvFootnote": string,
  "dpvCmra": string,
  "dpvVacant": string,
  "dpvNoStat": string,
  "dpvNoStatReasonCode": integer,
  "dpvDrop": string,
  "dpvThrowback": string,
  "dpvNonDeliveryDays": string,
  "dpvNonDeliveryDaysValues": integer,
  "dpvNoSecureLocation": string,
  "dpvPbsa": string,
  "dpvDoorNotAccessible": string,
  "dpvEnhancedDeliveryCode": string,
  "carrierRoute": string,
  "carrierRouteIndicator": string,
  "ewsNoMatch": boolean,
  "postOfficeCity": string,
  "postOfficeState": string,
  "abbreviatedCity": string,
  "fipsCountyCode": string,
  "county": string,
  "elotNumber": string,
  "elotFlag": string,
  "lacsLinkReturnCode": string,
  "lacsLinkIndicator": string,
  "poBoxOnlyPostalCode": boolean,
  "suitelinkFootnote": string,
  "pmbDesignator": string,
  "pmbNumber": string,
  "addressRecordType": string,
  "defaultAddress": boolean,
  "errorMessage": string,
  "cassProcessed": boolean
}
Campos
standardizedAddress

object (UspsAddress)

Endereço padronizado do USPS.

deliveryPointCode

string

Código do ponto de entrega de dois dígitos

deliveryPointCheckDigit

string

O dígito de verificação do ponto de entrega. Esse número é adicionado ao final do campo "delivery_point_barcode" de mensagens digitalizadas mecanicamente. A soma de todos os dígitos de delivery_point_barcode, deliveryPointCheckDigit, CEP e ZIP+4 deve resultar em um número divisível por 10.

dpvConfirmation

string

Os valores possíveis para confirmação de DPV. Retorna um único caractere ou não retorna valor.

  • N: não foi possível confirmar as informações de número principal e secundário.
  • D: o endereço foi confirmado como DPV somente para o número principal, sem as informações do número secundário.
  • S: o endereço foi confirmado como DPV somente para o número principal, e as informações do número secundário estavam presentes, mas não foram confirmadas.
  • Y: o endereço foi confirmado com DPV para os números primários e secundários.
  • Vazio: se a resposta não contiver um valor dpvConfirmation, o endereço não foi enviado para confirmação de DPV.
dpvFootnote

string

Notas de rodapé da validação do ponto de entrega. Várias notas de rodapé podem ser agrupadas na mesma string.

  • AA: o endereço de entrada correspondente ao arquivo ZIP+4
  • A1: o endereço de entrada não corresponde ao arquivo ZIP+4
  • BB: correspondente a DPV (todos os componentes)
  • CC: o número secundário não corresponde e não é obrigatório
  • C1: o número secundário não corresponde, mas é obrigatório
  • N1: endereço alto sem número secundário
  • M1: número principal ausente
  • M3: o número principal é inválido
  • P1: insira o número da ordem de compra, RR ou HC do endereço de entrada
  • P3: o número da ordem de compra, RR ou caixa HC do endereço de entrada é inválido
  • F1: o endereço de entrada correspondente a um endereço militar
  • G1: o endereço de entrada corresponde a um endereço de entrega geral
  • U1: o endereço de entrada corresponde a um CEP exclusivo
  • PB: endereço de entrada correspondente ao registro PBSA
  • RR: endereço confirmado de DPV com informações de PMB
  • R1: endereço confirmado do DPV sem informações do PMB
  • R7: registro da Rota R777 ou R779 da transportadora
  • IA: endereço informado identificado
  • TA: número principal correspondido descartando um alfa final
dpvCmra

string

Indica se o endereço é uma Agência Recebedora de E-mails Comercial (CMRA, na sigla em inglês), uma empresa particular que recebe e-mails de clientes. Retorna um único caractere.

  • Y: o endereço é uma CMRA
  • N: o endereço não é uma CMRA
dpvVacant

string

Esse lugar está vazio? Retorna um único caractere.

  • Y: o endereço está vago
  • N: o endereço não está vago.
dpvNoStat

string

Este é um endereço ativo ou sem estatísticas? Nenhum endereço de estatística é aquele que não está continuamente ocupado ou endereços não atendidos pelo USPS. Retorna um único caractere.

  • Y: o endereço não está ativo.
  • N: o endereço está ativo
dpvNoStatReasonCode

integer

Indica o tipo de NoStat. Retorna um código de motivo como int.

  • 1: endereço de entrega interno (IDA, na sigla em inglês) – endereços que não recebem correspondências diretamente da USPS, mas são entregues em um endereço de entrega que os atende.
  • 2: CDS – endereços que ainda não se tornaram entregues. Por exemplo, uma nova subdivisão em que os lotes e números primários foram determinados, mas ainda não há estrutura para a ocupação.
  • 3: Colisão: endereços que não são realmente confirmados por DPV.
  • 4: CMZ (faculdade, militar e outros tipos) – ZIP + 4 registros da USPS incorporados aos dados.
  • 5: normal: indica que os endereços não recebem entrega e que eles não são contabilizados como possíveis entregas.
  • 6: secundário obrigatório: o endereço requer informações secundárias.
dpvDrop

string

A sinalização indica que os e-mails são entregues a um único recepcionável em um site. Retorna um único caractere.

  • Y: o e-mail é entregue a um único destinatário em um site.
  • N: o e-mail não é entregue a um único receptivo em um site.
dpvThrowback

string

Indica que a correspondência não é entregue no endereço. Retorna um único caractere.

  • Y: a correspondência não é entregue no endereço.
  • N: a correspondência é entregue no endereço.
dpvNonDeliveryDays

string

A sinalização indica que a entrega de e-mails não é realizada todos os dias da semana. Retorna um único caractere.

  • Y: a entrega pelo e-mail não é realizada todos os dias da semana.
  • N: nenhuma indicação de que a entrega do e-mail não é realizada todos os dias da semana.
dpvNonDeliveryDaysValues

integer

Número inteiro que identifica os dias de não entrega. Ele pode ser interrogado usando bit flags: 0x40 – Domingo é um dia de não entrega 0x20 – Segunda é um dia de não entrega 0x10 – Terça é um dia de não entrega 0x08 – Quarta-feira é um dia de não entrega 0x04 – Quinta-feira é um dia de não entrega 0x02 – Sábado é um dia de não entrega 0x02 – Sábado é um dia de não entrega 0x08

dpvNoSecureLocation

string

A flag indica que a porta está acessível, mas o pacote não será deixado por motivos de segurança. Retorna um único caractere.

  • Y: o pacote não será enviado por motivos de segurança.
  • N: nenhuma indicação de que o pacote não será enviado por questões de segurança
dpvPbsa

string

Indica que o endereço corresponde ao registro do PBSA. Retorna um único caractere.

  • Y: o endereço corresponde ao registro do PBSA.
  • N: o endereço não corresponde ao registro do PBSA.
dpvDoorNotAccessible

string

A sinalização indica os endereços onde o USPS não pode bater em uma porta para entregar correspondências. Retorna um único caractere.

  • Y: a porta não está acessível.
  • N: nenhuma indicação de que a porta não está acessível.
dpvEnhancedDeliveryCode

string

Indica que mais de um código de retorno DPV é válido para o endereço. Retorna um único caractere.

  • Y: o endereço foi confirmado com DPV para os números primários e secundários.
  • N: não foi possível confirmar as informações de número principal e secundário.
  • S: o endereço foi confirmado como DPV somente para o número principal, e as informações do número secundário estavam presentes por não confirmado, ou um único alfa final de um número principal foi descartado para fazer uma correspondência de DPV e as informações secundárias necessárias.
  • D: o endereço foi confirmado como DPV somente para o número principal, sem as informações do número secundário.
  • R: o endereço confirmado, mas atribuído à rota fantasma R777 e R779, e à entrega pelo USPS não foi fornecido.
carrierRoute

string

O código de rota da transportadora. Um código de quatro caracteres que consiste em um prefixo de uma letra e um indicador de trajeto com três dígitos.

Prefixos:

  • C: rota da transportadora (ou trajeto da cidade)
  • R: trajeto rural
  • H: trajeto do contrato da rodovia
  • B: seção de caixa postal
  • G: unidade geral de entrega
carrierRouteIndicator

string

Indicador de classificação da taxa de rota da transportadora.

ewsNoMatch

boolean

O endereço de entrega é compatível, mas o arquivo EWS indica que uma correspondência exata estará disponível em breve.

postOfficeCity

string

Principal cidade dos correios.

postOfficeState

string

Estado da agência dos correios principal.

abbreviatedCity

string

Cidade abreviada.

fipsCountyCode

string

o código do condado FIPS.

county

string

Nome do condado.

elotNumber

string

Número da Linha de Viagem melhorada (eLOT, na sigla em inglês).

elotFlag

string

Bandeira crescente/decrescente eLOT (A/D).

poBoxOnlyPostalCode

boolean

CEP apenas por caixa postal.

pmbDesignator

string

Designador de unidade de PMB (Private Mail Box).

pmbNumber

string

Número do PMB (Private Mail Box)

addressRecordType

string

Tipo do registro de endereço que corresponde ao endereço de entrada.

  • F: FIRM. Essa é uma correspondência com um registro firme, que é o melhor nível de correspondência disponível para um endereço.
  • G: ENTREGA GERAL. Essa é uma correspondência com um registro de entrega geral.
  • H: Edifício / Apartamento. Esta é uma correspondência com um registro de edifício ou apartamento.
  • P: CAIXA POSTAL DO ESCRITÓRIO. Corresponde a uma caixa postal.
  • R: RURAL RURAL ou CONTRATO MATERIAL: corresponde a um registro de rota rural ou contrato de rodovia, ambos os quais podem ter intervalos de número de caixa associados.
  • S: STREET RECORD: correspondência a um registro de rua que contém um intervalo de números principal válido.
defaultAddress

boolean

Indicador de que um endereço padrão foi encontrado, mas existem endereços mais específicos.

errorMessage

string

Mensagem de erro para recuperação de dados USPS. Ele é preenchido quando o processamento do USPS é suspenso devido à detecção de endereços criados artificialmente.

Os campos de dados do USPS talvez não estejam preenchidos quando esse erro estiver presente.

cassProcessed

boolean

Indicador de que a solicitação foi processada pelo CASS.

UspsAddress

Representação do USPS de um endereço nos EUA.

Representação JSON
{
  "firstAddressLine": string,
  "firm": string,
  "secondAddressLine": string,
  "urbanization": string,
  "cityStateZipAddressLine": string,
  "city": string,
  "state": string,
  "zipCode": string,
  "zipCodeExtension": string
}
Campos
firstAddressLine

string

Primeira linha de endereço.

firm

string

Nome da empresa.

secondAddressLine

string

Segunda linha de endereço.

urbanization

string

Nome da urbanização porto-riquenha.

cityStateZipAddressLine

string

Cidade + estado + código postal.

city

string

Nome da cidade.

state

string

Código de estado de duas letras.

zipCode

string

Código postal, por exemplo, 10009.

zipCodeExtension

string

Extensão de quatro dígitos do código postal, por exemplo, 5023.