- Solicitação HTTP
- Corpo da solicitação
- Corpo da resposta
- PostalAddress
- LanguageOptions
- ValidationResult
- Veredito
- Granularidade
- Endereço
- AddressComponent
- ComponentName
- ConfirmationLevel
- Geocódigo
- 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 pelo O comprimento total dos campos nesta entrada não pode exceder 280 caracteres. As regiões compatíveis podem ser encontradas aqui. O valor A API Address Validation ignora os valores em |
previousResponseId |
Esse 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 mudanças feitas pelo usuário após a validação inicial precisarem ser revalidadas), cada solicitação de acompanhamento vai precisar preencher esse campo com o |
enableUspsCass |
Ativa o modo compatível com USPS CASS. Isso afeta apenas o campo É recomendável usar um |
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 mais informações na resposta. |
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 ( |
Campos | |
---|---|
result |
O resultado da validação de endereço. |
responseId |
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 inserção / 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 receber 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 |
A revisão de esquema do |
regionCode |
Opcional. Código regional CLDR do país/região do endereço. Para mais detalhes, consulte 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 da região não for fornecido, ele será inferido com base no endereço. Para ter 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 |
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 correspondente. |
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 esse campo. A API Address Validation não o usa atualmente. No momento, a API não rejeitará solicitações com esse campo definido, mas as informações serão descartadas e não serão retornadas na resposta. |
organization |
Evite definir esse campo. A API Address Validation não o usa atualmente. No momento, a API não rejeitará solicitações com esse campo definido, mas 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 mais informações na resposta.
Representação JSON |
---|
{ "returnEnglishLatinAddress": boolean } |
Campos | |
---|---|
returnEnglishLatinAddress |
Prévia: retornar um |
ValidationResult
O resultado da validação de um endereço.
Representação JSON |
---|
{ "verdict": { object ( |
Campos | |
---|---|
verdict |
Sinalizações gerais de vereditos |
address |
Informações sobre o endereço em si, não sobre o geocódigo. |
geocode |
Informações sobre o local e o local em que o endereço foi geocodificado. |
metadata |
Outras informações relevantes para a capacidade de entrega. Não é garantido que o |
uspsData |
Sinalizações de entrega extras fornecidas pela USPS. Fornecido somente nas regiões |
englishLatinAddress |
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. Se parte do endereço não tiver uma tradução em inglês, o serviço a retornará em um idioma alternativo que use script latino. Clique aqui para saber como o idioma alternativo é selecionado. Se parte do endereço não tiver traduções ou transliterações para um idioma que use alfabeto latino, o serviço retornará essa parte no idioma local associado ao endereço. Você ativou essa saída usando a sinalização Observação: os campos |
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 ( |
Campos | |
---|---|
inputGranularity |
A granularidade do endereço de input. Esse é o resultado da análise do endereço de entrada e não fornece nenhum sinal de validação. Para sinais de validação, consulte Por exemplo, se o endereço de entrada incluir um número de apartamento específico, |
validationGranularity |
O nível de granularidade para o qual a API pode validate totalmente o endereço. Por exemplo, um O resultado da validação de componente por endereço pode ser encontrado em |
geocodeGranularity |
Informações sobre a granularidade da De vez em quando, esse valor pode ser diferente do |
addressComplete |
O endereço é considerado completo se não houver tokens não resolvidos nem componentes de endereço inesperados ou ausentes. Consulte os campos |
hasUnconfirmedComponents |
Pelo menos um componente de endereço não pode ser categorizado ou validado. Consulte |
hasInferredComponents |
Pelo menos um componente de endereço foi inferido (adicionado) que 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 código geográfico pode ter. Quando usados para indicar a granularidade de um address, esses valores indicam a granularidade do endereço que identifica um destino de correspondência. Por exemplo, um endereço como "123 Main Street, Redwood City, CA, 94061" identifica um PREMISE
, enquanto "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 poderá ter a granularidade de 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 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 de bloco, como o Japão. |
ROUTE |
O geocódigo ou endereço é granular para o trajeto, como uma rua, estrada ou rodovia. |
OTHER |
Todas as outras granularidades, que são 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 do endereço com erros ortográficos, a substituição de 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 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. Ela fornece 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[] |
Os tipos de componentes que deveriam estar presentes em um endereço de correspondência formatado corretamente, mas não foram encontrados na entrada E que não puderam ser inferidos. Os componentes desse tipo não estão presentes em |
unconfirmedComponentTypes[] |
Os tipos dos componentes que estão presentes na |
unresolvedTokens[] |
Quaisquer tokens na entrada que não puderam ser resolvidos. Pode ser 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 |
AddressComponent
Representa um componente de endereço, como uma 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: outros tipos retornados pelo serviço Places para conferir uma lista dos 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 a localização do endereço e acreditamos que ele deve ser fornecido para um endereço completo. |
spellCorrected |
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 de ortografia comuns, como ao alterar "Amphitheater Pkwy" para "Amphitheatre Pkwy". |
replaced |
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. Essa não é uma mudança estética, o componente de entrada mudou para outro. |
unexpected |
Indica um componente de endereço que não está presente em um endereço postal da região especificada. Ela foi retida apenas porque fazia parte da entrada. |
ComponentName
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. Este atributo 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 |
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 o componente, mas é plausível que ele exista. Por exemplo, um número de rua dentro de um intervalo válido conhecido de números em uma rua em que os números de casas específicos 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 em que a entrada foi geocodificada.
Representação JSON |
---|
{ "location": { object ( |
Campos | |
---|---|
location |
O local geocodificado da entrada. É preferível usar IDs de lugar em vez de endereços, coordenadas de latitude/longitude ou Plus Codes. O uso de coordenadas ao definir rotas ou calcular rotas sempre fará com que o ponto seja direcionado para a estrada mais próxima dessas coordenadas. Esta não pode ser uma estrada que levará de forma rápida ou segura ao destino e pode não 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 |
O Plus Code correspondente ao |
bounds |
Os limites do lugar geocodificado. |
featureSizeMeters |
O tamanho do local geocodificado, em metros. Essa é outra medida da precisão da localização geocodificada, mas em tamanho físico, e não em significado semântico. |
placeId |
O PlaceID do lugar ao qual esta entrada é geocodificada. Para mais informações sobre IDs de lugares, clique aqui. |
placeTypes[] |
O(s) tipo(s) de lugar para o qual 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 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 |
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: um código global que define um retângulo menor que 14mx14m (1/8000o) e o código composto, que substitui o prefixo por um local de referência.
Representação JSON |
---|
{ "globalCode": string, "compoundCode": string } |
Campos | |
---|---|
globalCode |
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 |
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 precisam variar entre -90 e 90 graus, inclusive, e os limites de longitude, entre -180 e 180 graus, inclusive. Vários casos incluem:
Se
low
=high
, a janela de visualização consistirá 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 ehigh.longitude
= 180 graus, a janela de visualização vai incluir todas as longitudes.Se
low.longitude
= 180 graus ehigh.longitude
= -180 graus, o intervalo de longitude vai ficar vazio.Se
low.latitude
>high.latitude
, o intervalo de latitude vai 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 a cidade de 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 inferior da janela de visualização. |
high |
Obrigatório. O ponto mais alto da janela de visualização. |
AddressMetadata
Os metadados do endereço. Não é garantido que o metadata
seja 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. |
UspsData
Os dados do USPS para o endereço. Não é garantido que o uspsData
seja totalmente preenchido para cada endereço dos EUA ou PR enviado à API Address Validation. Recomenda-se 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 ( |
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 de "delivery_point_barcode" no caso de e-mails verificados automaticamente. 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 |
Os valores possíveis para confirmação de DPV. Retorna um único caractere ou não retorna nenhum valor.
|
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 comercial (CMRA, na sigla em inglês), uma empresa particular que recebe e-mails para 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 não é ocupado continuamente ou endereços que a USPS não atende. Retorna um único caractere.
|
dpvNoStatReasonCode |
Indica o tipo NoStat. Retorna um código de motivo como int.
|
dpvDrop |
A sinalização indica que os e-mails são entregues a um único recepcionável em um site. Retorna um único caractere.
|
dpvThrowback |
Indica que correspondência não é entregue no endereço. Retorna um único caractere.
|
dpvNonDeliveryDays |
A sinalização indica que a entrega de e-mails não é realizada todos os dias da semana. Retorna um único caractere.
|
dpvNonDeliveryDaysValues |
Número inteiro que identifica os dias de não entrega. Ele pode ser interrogado usando flags de bit: 0x40 – Domingo é um dia de não entrega 0x20 – Segunda-feira é um dia de não exibição 0x10 – Terça é um dia de não exibição 0x08 – Quarta-feira é um dia de não entrega 0x04 – Quinta é um dia de não entrega 0x02 – Sábado é um dia de não exibição – Sábado é um dia de não entrega 0x02 |
dpvNoSecureLocation |
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.
|
dpvPbsa |
Indica que o endereço corresponde ao registro do PBSA. Retorna um único caractere.
|
dpvDoorNotAccessible |
A sinalização indica os endereços onde a USPS não pode bater em uma porta para entregar correspondências. Retorna um único caractere.
|
dpvEnhancedDeliveryCode |
Indica que mais de um código de retorno DPV é válido para o endereço. Retorna um único caractere.
|
carrierRoute |
O código de rota da operadora. Um código de quatro caracteres que consiste em um prefixo de uma letra e um indicador de trajeto de três dígitos. Prefixos:
|
carrierRouteIndicator |
Indicador de classificação da taxa de rota da transportadora. |
ewsNoMatch |
O endereço de entrega é compatível, mas o arquivo EWS indica que uma correspondência exata estará disponível em breve. |
postOfficeCity |
Principal cidade dos correios. |
postOfficeState |
Estado da agência dos correios principal. |
abbreviatedCity |
Cidade abreviada. |
fipsCountyCode |
Código do condado do FIPS. |
county |
Nome do condado. |
elotNumber |
Número da linha de viagem avançada (eLOT). |
elotFlag |
eLOT Bandeira Crescente/Descendente (A/D). |
lacsLinkReturnCode |
Código de devolução de LACSLink. |
lacsLinkIndicator |
Indicador LACSLink. |
poBoxOnlyPostalCode |
CEP apenas na caixa postal. |
suitelinkFootnote |
Notas de rodapé que correspondem a um registro de rua ou arranha-céu com informações de conjuntos. Se o nome da empresa for correspondente, o número secundário será retornado.
|
pmbDesignator |
Designador da unidade de PMB (Private Mail Box). |
pmbNumber |
número do PMB (Private Mail Box); |
addressRecordType |
Tipo do registro do endereço que corresponde ao endereço de entrada.
|
defaultAddress |
Indicador de que um endereço padrão foi encontrado, mas existem endereços mais específicos. |
errorMessage |
Mensagem de erro para recuperação de dados USPS. Ele é preenchido quando o processamento da USPS é suspenso devido à detecção de endereços criados artificialmente. Os campos de dados do USPS podem não ser preenchidos quando esse erro estiver presente. |
cassProcessed |
Indicador de que a solicitação foi processada pelo CASS. |
UspsAddress
Representação da 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 da urbanização porto-riquenha. |
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 CEP de quatro dígitos, por exemplo, 5023. |