Package google.maps.addressvalidation.v1

Índice

Validação de endereço

O serviço para validar endereços.

Feedback de validação

rpc ProvideValidationFeedback(ProvideValidationFeedbackRequest) returns (ProvideValidationFeedbackResponse)

Feedback sobre o resultado da sequência de tentativas de validação. Essa deve ser a última chamada feita após uma sequência de chamadas de validação para o mesmo endereço e deve ser chamada quando a transação for concluída. Só deve ser enviado uma vez para a sequência de ValidateAddress solicitações necessárias para validar totalmente um endereço.
ValidateAddress

rpc ValidateAddress(ValidateAddressRequest) returns (ValidateAddressResponse)

Valida um endereço.

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.

Campos
formatted_address

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.
postal_address

PostalAddress

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

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. 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.
missing_component_types[]

string

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 formatted_address, postal_address ou address_components. Um exemplo pode ser ['street_number', 'route'] para uma entrada como "Boulder, Colorado, 80301, EUA". A lista de tipos possíveis pode ser encontrada aqui.
unconfirmed_component_types[]

string

Os tipos dos componentes que estão presentes no address_components, mas não foram confirmados como corretos. Esse campo é fornecido para fins de conveniência: o conteúdo dele é equivalente a iterar pelo address_components para encontrar os tipos de todos os componentes em que confirmation_level não é CONFIRMED ou a sinalização inferred não está definida como true. A lista de tipos possíveis pode ser encontrada aqui.
unresolved_tokens[]

string

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 ["123235253253"], já que isso não parece um número de rua válido.

AddressComponent

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

Campos
component_name

ComponentName

É o nome desse componente.
component_type

string

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.
confirmation_level

ConfirmationLevel

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

bool

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.
spell_corrected

bool

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

bool

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

bool

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.

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.

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.

Campos
business

bool

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

bool

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

bool

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

Nome do componente

Um wrapper para o nome do componente.

Campos
text

string

O texto do nome. Por exemplo, "5th Avenue" para um nome de rua ou "1253" para um número de rua.
language_code

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 um número de rua.

Geocodificação

Contém informações sobre o local em que a entrada foi geocodificada.

Campos
location

LatLng

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.
plus_code

PlusCode

O código plus correspondente ao location.
bounds

Viewport

Os limites do local geocodificado.
feature_size_meters

float

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.
place_id

string

O ID de local do lugar para o qual esta entrada é geocodificada.

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

string

Os tipos de lugar para os quais a entrada foi geocodificada. Por exemplo, ['locality', 'political']. A lista completa dos tipos pode ser encontrada neste link.

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.

Campos
global_code

string

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).
compound_code

string

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.

ProvideValidationFeedbackRequest

A solicitação para enviar feedback de validação.

Campos
conclusion

ValidationConclusion

Obrigatório. O resultado da sequência de tentativas de validação.

Se este campo for definido como VALIDATION_CONCLUSION_UNSPECIFIED, será retornado um erro INVALID_ARGUMENT.
response_id

string

Obrigatório. O ID da resposta a que este feedback se destina. Este deve ser o [response_id][google.maps.addressvalidation.v1.ValidateAddressRequest.response_id] da primeira resposta em uma série de tentativas de validação de endereço.

Conclusão de validação

Os possíveis resultados finais da sequência de solicitações de validação de endereço necessárias para validar um endereço.

Enums
VALIDATION_CONCLUSION_UNSPECIFIED Esse valor não é usado. Se o campo ProvideValidationFeedbackRequest.conclusion estiver definido como VALIDATION_CONCLUSION_UNSPECIFIED, um erro INVALID_ARGUMENT será retornado.
VALIDATED_VERSION_USED A versão do endereço retornado pela Address Validation API foi usada para a transação.
USER_VERSION_USED A versão do endereço fornecido pelo usuário foi usada para a transação
UNVALIDATED_VERSION_USED Uma versão do endereço que foi inserida após a última tentativa de validação, mas que não foi revalidada, foi usada para a transação.
UNUSED A transação foi abandonada e o endereço não foi usado.

ProvideValidationFeedbackResponse

A resposta para feedback de validação.

A resposta ficará vazia se o feedback for enviado.

Endereço usps

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

Campos
first_address_line

string

Primeira linha de endereço.
firm

string

Nome da empresa.
second_address_line

string

Segunda linha de endereço.
urbanization

string

Nome de urbanização de Porto Rico.
city_state_zip_address_line

string

Cidade + estado + código postal.
city

string

Nome da cidade.
state

string

Código de estado com duas letras.
zip_code

string

CEP, por exemplo, 10009.
zip_code_extension

string

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

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.

Campos
standardized_address

UspsAddress

Endereço padronizado da USPS.
delivery_point_code

string

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

string

O dígito de verificação do ponto de entrega. Esse número é adicionado ao final do código de entrega entrega_mail. A soma de todos os dígitos do delivery_point_barcode, delivery_point_check_digit, código postal e CEP+4 juntos resulta em um número divisível por 10.
dpv_confirmation

string

Os valores possíveis para confirmação do DPV. Retorna um único caractere.

  • Y: o endereço foi confirmado para DPV para números primários e secundários.
  • N: falha ao confirmar o DPV nas informações primárias e secundárias.
  • S: o endereço foi confirmado para o número principal, e as informações do número secundário não estavam confirmadas.
  • D: o endereço DPV foi confirmado apenas para o número principal, e as informações de número secundário estavam ausentes.
dpv_footnote

string

As 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 corresponde ao arquivo ZIP+4
  • A1: o endereço de entrada não corresponde ao arquivo ZIP+4
  • BB: corresponde ao DPV (todos os componentes)
  • CC: o número secundário não corresponde (presente, mas inválido)
  • N1: o endereço no arranha-céu não tem um número secundário
  • M1: número principal ausente
  • M3: o número principal é inválido
  • P1: o número da caixa RR ou HC da entrada está ausente
  • P3: o número da caixa postal, RR ou HC da entrada é inválido
  • F1: o endereço de entrada corresponde 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 DPV confirmado com informações de PMB
  • R1: endereço DPV confirmado sem informações de PMB
  • R7: registro de rota da operadora R777 ou R779
dpv_cmra

string

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.

  • Y: o endereço é um CMRA
  • N: o endereço não é um CMRA
dpv_vacant

string

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

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

string

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.

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

string

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:

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

string

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

bool

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

string

Principal agência dos correios.
post_office_state

string

Estado principal da agência dos correios.
abbreviated_city

string

Cidade abreviada.
fips_county_code

string

Código de país do FIPS.
county

string

Nome do condado.
elot_number

string

Número de linha de viagem (ELOT) aprimorado.
elot_flag

string

eLOT - Crescente/Crescente (A/D).
po_box_only_postal_code

bool

CEP apenas na caixa postal.
pmb_designator

string

Designador de unidade da PMB (Caixa de correio particular).
pmb_number

string

Número PMB (Caixa postal particular);
address_record_type

string

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

  • F: FIRM. É a correspondência com um registro de empresa, que é o nível mais alto de correspondência disponível para um endereço.
  • G: ENTREGA GERAL. Corresponde a um registro de entrega geral.
  • H: Construção / Apartamento. Corresponde a um registro de edifício ou apartamento.
  • P: CAIXA POSTAGEM OFICIAL. Esta é uma correspondência a uma caixa postal.
  • R: RURAL ROUTE ou HIGHWAY CONTRACT: é uma correspondência com um registro de Rodovia Rural ou Contrato de Rodovia, ambos podem ter intervalos de números de caixa associados.
  • S: REGISTRO DE RUA: é uma correspondência de um registro de rua que contém um intervalo de números principal válido.
default_address

bool

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

string

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.
cass_processed

bool

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

ValidateAddressRequest

A solicitação para validar um endereço.

Campos
address

PostalAddress

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

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 language_code no endereço de entrada é reservado para usos futuros e é ignorado hoje. O resultado do endereço validado será preenchido com base no idioma de preferência para o endereço fornecido, conforme identificado pelo sistema.

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

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 que o usuário fizer após a validação inicial precisarem ser revalidadas), cada solicitação de acompanhamento precisará preencher esse campo com response_id desde a primeira resposta na sequência de validação.
enable_usps_cass

bool

Ativa o modo compatível com CAPS de USPS. 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 CAPS de Porto Rico em endereços em Porto Rico, é necessário fornecer um google.type.PostalAddress.region_code do address como "PR", ou um google.type.PostalAddress.administrative_area do address como "Porto Rico" (sem distinção entre maiúsculas e 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 nome e o número da rua, e a segunda contém a cidade, o estado e o CEP.

ValidateAddressResponse

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

Campos
result

ValidationResult

O resultado da validação do endereço.
response_id

string

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

ValidationResult

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

Campos
verdict

Verdict

Sinalizações gerais do veredito
address

Address

Informações sobre o endereço propriamente dito em oposição ao geocódigo.
geocode

Geocode

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

AddressMetadata

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

UspsData

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

Veredito

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

Campos
input_granularity

Granularity

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 validation_granularity abaixo.

Por exemplo, se o endereço de entrada incluir um número específico de apartamento, o input_granularity 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 se o número do apartamento for inválido, o validation_granularity provavelmente será PREMISE ou inferior.
validation_granularity

Granularity

O nível de granularidade para a qual a API pode validar totalmente o endereço. Por exemplo, um validation_granularity de PREMISE indica que todos os componentes de endereço no nível de PREMISE ou mais aproximados podem ser validados.

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

Granularity

Informações sobre a granularidade da geocode. Isso pode ser entendido como o significado semântico da localização aproximada ou refinada do local geocodificado.

Às vezes, pode ser diferente do validation_granularity acima. Por exemplo, nosso banco de dados pode registrar a existência de um número de apartamento, mas não tem um local preciso para o apartamento dentro de um grande complexo de apartamentos. Nesse caso, validation_granularity será SUB_PREMISE, mas geocode_granularity será PREMISE.
address_complete

bool

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 missing_component_types, unresolved_tokens ou unexpected para mais detalhes.
has_unconfirmed_components

bool

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

bool

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

bool

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

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.