- Solicitação HTTP
- Corpo da solicitação
- Corpo da resposta
- PostalAddress
- ValidationResult
- Veredicto
- Granularidade
- Endereço
- AddressComponent
- ComponentName
- ConfirmationLevel.
- Geocodificação
- LatLng
- PlusCode
- Janela de visualização
- AddressMetadata
- UspsData
- UspsAddress
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 ( |
Campos | |
---|---|
address |
Obrigatório. O endereço que está sendo validado. Endereços não formatados devem ser enviados via O tamanho total dos campos nessa entrada não pode exceder 280 caracteres. As regiões compatíveis podem ser encontradas neste link. O valor A API Address Validation ignora os valores em |
previousResponseId |
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 que o usuário fizer após a validação inicial precisarem ser revalidadas), cada solicitação de acompanhamento precisará preencher esse campo com |
enableUspsCass |
Ativa o modo compatível com CAPS de USPS. Isso afeta apenas o campo É recomendável usar um |
Corpo da resposta
Se bem-sucedido, o corpo da resposta incluirá dados com a estrutura a seguir:
A resposta a uma solicitação de validação de endereço.
Representação JSON |
---|
{
"result": {
object ( |
Campos | |
---|---|
result |
O resultado da validação do endereço. |
responseId |
O UUID que identifica essa resposta. Se o endereço precisar ser revalidado, 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.
Recomendação sobre digitação / edição de endereços: - Use um widget de endereço pronto para internacionalização, como https://github.com/google/libaddressinput. - Os usuários não devem ver elementos de 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 |
A revisão de esquema do |
regionCode |
Opcional. Código regional CLDR do país/região do endereço. Consulte https://cldr.unicode.org/ e https://www.unicode.org/cldr/charts/30/supplemental/territory_information.html para mais detalhes. Exemplo: "CH" para Suíça. Se o código da região não for fornecido, será inferido a partir do endereço. Para um melhor desempenho, é recomendável incluir o código da região, se souber. A presença de regiões inconsistentes ou repetidas pode levar a um desempenho insatisfatório. Por exemplo, se o |
languageCode |
O código de idioma no endereço de entrada é reservado para usos futuros e é ignorado hoje. A API retorna o endereço no idioma apropriado de onde o endereço está localizado. |
postalCode |
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 |
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 |
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 |
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 |
Opcional. Sublocalidade do endereço. Por exemplo, pode ser bairro ou distrito. |
addressLines[] |
Obrigatório. Linhas de endereço não estruturadas que descrevem os níveis mais baixos de um endereço. |
recipients[] |
Evite definir este campo. A Address Validation API não a usa no momento. Embora, no momento, a API não rejeite solicitações com esse campo definido, as informações serão descartadas e não serão retornadas na resposta. |
organization |
Evite definir este campo. A Address Validation API não a usa no momento. Embora, no momento, a API não rejeite solicitações com esse campo definido, as informações serão descartadas e não serão retornadas na resposta. |
ValidationResult
O resultado da validação de um endereço.
Representação JSON |
---|
{ "verdict": { object ( |
Campos | |
---|---|
verdict |
Sinalizações gerais do veredito |
address |
Informações sobre o endereço propriamente dito em oposição ao geocódigo. |
geocode |
Informações sobre o local e o local para o qual o endereço foi geocodificado. |
metadata |
Outras informações relevantes para a entrega. Não há garantia de que |
uspsData |
Sinalizações adicionais de entrega fornecidas pelo USPS. Fornecido apenas nas regiões |
Veredito
Visão geral de alto nível do geocódigo e do resultado da validação de endereço.
Representação JSON |
---|
{ "inputGranularity": enum ( |
Campos | |
---|---|
inputGranularity |
A granularidade do endereço de input. Isso é o resultado da análise do endereço de entrada e não fornece nenhum sinal de validação. Para indicadores de validação, consulte Por exemplo, se o endereço de entrada incluir um número específico de apartamento, o |
validationGranularity |
O nível de granularidade para a qual a API pode validar totalmente o endereço. Por exemplo, um O resultado da validação do componente por endereço pode ser encontrado em |
geocodeGranularity |
Informações sobre a granularidade da Às vezes, pode ser diferente do |
addressComplete |
O endereço é considerado completo quando não há tokens não resolvidos e nenhum componente de endereço inesperado ou ausente. Consulte os campos |
hasUnconfirmedComponents |
Pelo menos um componente de endereço não pode ser categorizado ou validado, consulte |
hasInferredComponents |
Pelo menos um componente do endereço foi inferido (adicionado) e não estava na entrada. Consulte |
hasReplacedComponents |
Pelo menos um componente de endereço foi substituído. Consulte |
Granularidade
As várias granularidades que um endereço ou geocódigo podem ter. Quando usados para indicar a granularidade de um endereço, esses valores indicam a granularidade com que o endereço identifica um destino de e-mail. Por exemplo, um endereço como "123 Main Street, Redwood City, CA, 94061" identifica um PREMISE
, enquanto algo como "Redwood City, CA, 94061" identifica um LOCALITY
. No entanto, se não for possível encontrar um geocódigo para "123 Main Street" em Redwood City, o geocódigo retornado pode ter granularidade LOCALITY
, embora o endereço seja mais granular.
Enums | |
---|---|
GRANULARITY_UNSPECIFIED |
Valor padrão. Esse valor não é usado. |
SUB_PREMISE |
Resultado abaixo do edifício, como um apartamento. |
PREMISE |
Resultado no nível do edifício. |
PREMISE_PROXIMITY |
Um geocódigo que se aproxima do local no nível da construção do endereço. |
BLOCK |
O endereço ou geocódigo indica um bloco. Usado apenas em regiões que têm endereço no nível de bloco, como Japão. |
ROUTE |
O geocódigo ou endereço é granular para trajeto, como uma rua, uma estrada ou uma rodovia. |
OTHER |
Todas as outras granularidades, que são agrupadas porque não podem ser entregues. |
Address
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 das partes incorretas e a inferência de partes ausentes.
Representação JSON |
---|
{ "formattedAddress": string, "postalAddress": { object ( |
Campos | |
---|---|
formattedAddress |
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 |
O endereço pós-processado representado como um endereço postal. |
addressComponents[] |
Lista não ordenada. Os componentes de endereço individuais do endereço formatado e corrigido, junto com as informações de validação. Isso fornece informações sobre o status de validação dos componentes individuais. Os componentes de endereço não são ordenados de maneira específica. Não faça suposições sobre a ordem dos componentes de endereço na lista. |
missingComponentTypes[] |
Os tipos de componentes que estavam 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 |
unconfirmedComponentTypes[] |
Os tipos dos componentes que estão presentes no |
unresolvedTokens[] |
Quaisquer tokens na entrada que não puderam ser resolvidos. Pode ser uma entrada que não foi reconhecida como uma parte válida de um endereço (por exemplo, uma entrada como "123235253253 Main St, São Francisco, CA, 94105"), os tokens não resolvidos podem ser semelhantes a |
AddressComponent
Representa um componente de endereço, como rua, cidade ou estado.
Representação JSON |
---|
{ "componentName": { object ( |
Campos | |
---|---|
componentName |
É o nome desse componente. |
componentType |
O tipo do componente de endereço. Consulte a Tabela 2: Tipos adicionais retornados pelo serviço do Google Places para obter uma lista de tipos possíveis. |
confirmationLevel |
Indica o nível de certeza que temos de que o componente está correto. |
inferred |
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 |
Indica que a ortografia do nome do componente foi corrigida de forma pequena, por exemplo, trocando dois caracteres que apareciam na ordem errada. Isso indica uma alteração estética. |
replaced |
Indica que o nome do componente foi substituído por outro completamente diferente, por exemplo, um CEP errado está sendo substituído por um que está correto para o endereço. Essa não é uma alteração estética. O componente de entrada foi alterado para outra. |
unexpected |
Indica que um componente de endereço não deve estar presente em um endereço postal da região especificada. Nós a retemos somente porque ela fazia parte da entrada. |
Nome do componente
Um wrapper para o nome do componente.
Representação JSON |
---|
{ "text": string, "languageCode": string } |
Campos | |
---|---|
text |
O texto do nome. Por exemplo, "5th Avenue" para um nome de rua ou "1253" para um número de rua. |
languageCode |
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 um número de rua. |
Nível de confirmação
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 |
Conseguimos verificar se 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 existe a possibilidade de ele existir. Por exemplo, um número de rua dentro de um intervalo válido de números, em uma rua em que números de casa específicos não são conhecidos. |
UNCONFIRMED_AND_SUSPICIOUS |
Este componente não foi confirmado e provavelmente está incorreto. Por exemplo, um bairro que não corresponde ao restante do endereço. |
Geocodificação
Contém informações sobre o local em que a entrada foi geocodificada.
Representação JSON |
---|
{ "location": { object ( |
Campos | |
---|---|
location |
O local geocodificado da entrada. É preferível usar IDs de lugares em vez de endereços, coordenadas de latitude/longitude ou códigos plus. Usar coordenadas ao traçar ou calcular rotas de carro fará com que o ponto seja direcionado para a estrada mais próxima dessas coordenadas. Esta não pode ser uma estrada que levará com rapidez ou segurança ao destino e pode não estar próxima de um ponto de acesso à propriedade. Além disso, quando um local é geocodificado inverso, não há garantia de que o endereço retornado corresponderá ao original. |
plusCode |
O código plus correspondente ao |
bounds |
Os limites do local geocodificado. |
featureSizeMeters |
O tamanho do lugar geocodificado, em metros. Essa é outra medida da grosseria do local geocodificado, mas em tamanho físico em vez de significado semântico. |
placeId |
O ID de local do lugar para o qual esta entrada é geocodificada. Para mais informações sobre IDs de lugares, clique aqui. |
placeTypes[] |
Os tipos de lugar para os quais a entrada foi geocodificada. Por exemplo, |
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 seja especificado de outra forma, esse objeto deve 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 |
A latitude em graus. Precisa estar no intervalo [-90,0, +90,0]. |
longitude |
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 retângulo menor de 1/4.000 graus ou de menor, e um código composto, que substitui o prefixo por um local de referência.
Representação JSON |
---|
{ "globalCode": string, "compoundCode": string } |
Campos | |
---|---|
globalCode |
Código global (completo) do lugar, como "9FWM33GV+HQ", representando uma área de 1/8.000 por 1/8.000 graus (~14 por 14 metros). |
compoundCode |
Código composto do lugar, como "33GV+HQ, Ramberg, Noruega", contendo o sufixo do código global e substituindo o prefixo pelo 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
na diagonal. Uma janela de visualização é considerada uma região fechada, ou seja, inclui seu limite. Os limites de latitude precisam variar entre -90 e 90 graus, e os limites de longitude precisam estar entre -180 e 180 graus. Diversos casos incluem:
Se
low
=high
, a janela de visualização consiste nesse único ponto.Se
low.longitude
>high.longitude
, o intervalo de longitude é invertido (a janela de visualização cruza a linha de longitude de 180 graus).Se
low.longitude
= -180 graus ehigh.longitude
= 180 graus, a janela de visualização incluirá todas as longitudes.Se
low.longitude
= 180 graus ehigh.longitude
= -180 graus, o intervalo de longitude estará 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 resultará em um erro.
Por exemplo, esta janela de visualização abrange totalmente Nova York:
{ "low": { "latitude": 40.477398, "longitude": -74.259087 }, "high": { "latitude": 40.91618, "longitude": -73.70018 } }
Representação JSON |
---|
{ "low": { object ( |
Campos | |
---|---|
low |
Obrigatório. O ponto baixo da janela de visualização. |
high |
Obrigatório. O ponto alto da janela de visualização. |
Metadados de endereço
Os metadados do endereço. Não há garantia de que metadata
será totalmente preenchido para cada endereço enviado à API Address Validation.
Representação JSON |
---|
{ "business": boolean, "poBox": boolean, "residential": boolean } |
Campos | |
---|---|
business |
Indica que este é o endereço de uma empresa. Se não for definido, indica que o valor é desconhecido. |
poBox |
Indica o endereço de uma caixa postal. Se não for definido, indica que o valor é desconhecido. |
residential |
Indica que este é o endereço de uma residência. Se não for definido, indica que o valor é desconhecido. |
Dados de uso
Os dados do USPS do endereço. Não há garantia de que uspsData
será totalmente preenchido para cada endereço nos EUA ou PR enviado para a API Address Validation. Se você usar uspsData como parte principal da resposta, recomendamos que integre os campos de endereço de backup da resposta.
Representação JSON |
---|
{
"standardizedAddress": {
object ( |
Campos | |
---|---|
standardizedAddress |
Endereço padronizado da USPS. |
deliveryPointCode |
Código do ponto de entrega de dois dígitos |
deliveryPointCheckDigit |
O dígito de verificação do ponto de entrega. Esse número é adicionado ao final do código de entrega entrega_mail. Adicionar todos os dígitos do delivery_point_barcode, deliveryPointCheckDigit, código postal e CEP + 4 juntos deve gerar um número divisível por 10. |
dpvConfirmation |
Os valores possíveis para confirmação do DPV. Retorna um único caractere.
|
dpvFootnote |
As notas de rodapé da validação do ponto de entrega. Várias notas de rodapé podem ser agrupadas na mesma string.
|
dpvCmra |
Indica se o endereço é uma Agência de recebimento de e-mails comerciais (CMRA, na sigla em inglês), uma empresa privada que recebe e-mails de clientes. Retorna um único caractere.
|
dpvVacant |
Esse lugar está vazio? Retorna um único caractere.
|
dpvNoStat |
Este é um endereço sem estatísticas ou ativo? Nenhum endereço de estatística é um endereço que não está ocupado continuamente ou endereços que o USPS não atende. Retorna um único caractere.
|
carrierRoute |
O código do trajeto da operadora. Um código de quatro caracteres que consiste em um prefixo de uma letra e um indicador de rota de três dígitos. Prefixos:
|
carrierRouteIndicator |
Indicador de classificação da taxa de rota da transportadora. |
ewsNoMatch |
O endereço de entrega é correspondente, mas o arquivo EWS indica que uma correspondência exata estará disponível em breve. |
postOfficeCity |
Principal agência dos correios. |
postOfficeState |
Estado principal da agência dos correios. |
abbreviatedCity |
Cidade abreviada. |
fipsCountyCode |
Código de país do FIPS. |
county |
Nome do condado. |
elotNumber |
Número de linha de viagem (ELOT) aprimorado. |
elotFlag |
eLOT - Crescente/Crescente (A/D). |
lacsLinkReturnCode |
Código de retorno LACSLink. |
lacsLinkIndicator |
Indicador LACSLink. |
poBoxOnlyPostalCode |
CEP apenas na caixa postal. |
suitelinkFootnote |
Notas de rodapé que correspondem a um registro de rua ou de arranha-céu e informações da suíte. Se a correspondência com o nome da empresa for encontrada, o número secundário será retornado.
|
pmbDesignator |
Designador de unidade da PMB (Caixa de correio particular). |
pmbNumber |
Número PMB (Caixa postal particular); |
addressRecordType |
Tipo de registro de endereço que corresponde ao endereço de entrada.
|
defaultAddress |
Indicador de que um endereço padrão foi encontrado, mas há endereços mais específicos. |
errorMessage |
Mensagem de erro para recuperação de dados USPS. Isso é preenchido quando o processamento do USPS é suspenso devido à detecção de endereços criados artificialmente. Os campos de dados USPS podem não ser preenchidos quando esse erro está presente. |
cassProcessed |
Indicador de que a solicitação foi processada como CASS. |
Endereço usps
Representação do USPS de um endereço dos EUA.
Representação JSON |
---|
{ "firstAddressLine": string, "firm": string, "secondAddressLine": string, "urbanization": string, "cityStateZipAddressLine": string, "city": string, "state": string, "zipCode": string, "zipCodeExtension": string } |
Campos | |
---|---|
firstAddressLine |
Primeira linha de endereço. |
firm |
Nome da empresa. |
secondAddressLine |
Segunda linha de endereço. |
urbanization |
Nome de urbanização de Porto Rico. |
cityStateZipAddressLine |
Cidade + estado + código postal. |
city |
Nome da cidade. |
state |
Código de estado com duas letras. |
zipCode |
CEP, por exemplo, 10009. |
zipCodeExtension |
Extensão de código postal de quatro dígitos, por exemplo, 5023. |