Esta página foi traduzida pela API Cloud Translation.

Validar um endereço

Para validar um endereço usando a API Address Validation, chame o método validateAddress (REST) ou ValidateAddress (gRPC). Nesta documentação, usamos o REST nos exemplos, mas a abordagem é semelhante ao gRPC.

Depois de validar um endereço, é possível retornar informações ao Google sobre o resultado da validação de endereço chamando o método provideValidationFeedback (REST) ou ProvideValidationFeedback (gRPC). Para informações e exemplos, consulte Enviar feedback de validação de endereço.

Solicitação de validação de endereço

Valide um endereço enviando uma solicitação POST para o método validateAddress:

https://addressvalidation.googleapis.com/v1:validateAddress?key=YOUR_API_KEY

Transmita um corpo JSON para a solicitação que define o endereço a ser validado:

curl -X POST -d '{
  "address": {
    "regionCode": "US",
    "locality": "Mountain View",
    "addressLines": ["1600 Amphitheatre Pkwy"]
  }
}' \
-H 'Content-Type: application/json' \
"https://addressvalidation.googleapis.com/v1:validateAddress?key=YOUR_API_KEY"

O campo address no corpo da solicitação, do tipo PostalAddress, precisa conter pelo menos uma entrada em addressLines.

O campo regionCode é opcional. Se omitida, a API deduzirá a região a partir do endereço. No entanto, para um melhor desempenho, recomendamos incluir regionCode, se você souber. Para a lista de regiões compatíveis, consulte as regiões compatíveis.
O tamanho total do campo address é limitado a 280 caracteres.

Como opção, ative o CASSTM ao validar um endereço

O Serviço Postal dos Estados Unidos¹ mantém o Sistema de suporte de precisão de codificação (CASSTM, na sigla em inglês) para oferecer suporte e certificar provedores de validação de endereço. Um serviço CASS CertifiedTM, como a API Address Validation, foi confirmado pela capacidade de preencher informações ausentes de um endereço, padronizá-lo e atualizá-lo para fornecer a você o endereço mais atual e mais preciso.

Somente para as regiões "US" e "PR", é possível ativar o processamento CASS definindo enableUspsCass como true no corpo da solicitação.

Para melhores resultados ao usar o CASS, forneça um endereço que inclua a rua e o número, junto com a cidade, o estado e o CEP:

{
  "address": {
    "regionCode": "US",
    "locality": "Mountain View",
    "administrativeArea": "CA",
    "postalCode": "94043",
    "addressLines": ["1600 Amphitheatre Pkwy"]
  },
  "enableUspsCass": true
}

Também é possível especificar o endereço completo como duas strings na matriz addressLines:

{
  "address": {
    "regionCode": "US",
    "addressLines": ["1600 Amphitheatre Pkwy", "Mountain View, CA, 94043"]
  },
  "enableUspsCass": true
}

Resposta para validação de endereço

Se a solicitação for bem-sucedida, o servidor responderá com um código de status HTTP 200 OK e um corpo de resposta contendo informações sobre o endereço validado.

O campo result da resposta contém um objeto ValidationResult. Esse objeto inclui:

Um campo address, do tipo Address, contendo informações detalhadas sobre o endereço.
Um campo geocode, do tipo Geocode, contendo informações de geocódigo para o endereço.

Observação: para informações sobre as diferenças entre address e geocode, consulte Endereço x geocódigo.
Um campo verdict, do tipo Verdict, contendo o resultado da validação de endereço e do geocódigo.
Um campo metadata, do tipo AddressMetadata, contendo os metadados do endereço.
Um campo uspsData, do tipo USPSData, que contém os dados do USPS do endereço. Esses dados só estão disponíveis para endereços nos Estados Unidos e em Porto Rico.

Como a resposta a seguir contém addressComplete definido como true, a resposta indica que esse endereço é totalmente válido, portanto, nenhuma validação adicional é necessária. Se a resposta indicar que parte do endereço é inválida, solicite ao usuário que verifique e confirme a entrada.

{
  "result": {
    "verdict": {
      "inputGranularity": "PREMISE",
      "validationGranularity": "PREMISE",
      "geocodeGranularity": "PREMISE",
      "addressComplete": true,
      "hasInferredComponents": true
    },
    "address": {
      "formattedAddress": "1600 Amphitheatre Parkway, Mountain View, CA 94043-1351, USA",
      "postalAddress": {
        "regionCode": "US",
        "languageCode": "en",
        "postalCode": "94043-1351",
        "administrativeArea": "CA",
        "locality": "Mountain View",
        "addressLines": [
          "1600 Amphitheatre Pkwy"
        ]
      },
      "addressComponents": [
        {
          "componentName": {
            "text": "1600",
            "languageCode": "en"
          },
          "componentType": "street_number",
          "confirmationLevel": "CONFIRMED"
        },
        {
          "componentName": {
            "text": "Amphitheatre Parkway",
            "languageCode": "en"
          },
          "componentType": "route",
          "confirmationLevel": "CONFIRMED"
        },
        {
          "componentName": {
            "text": "Mountain View",
            "languageCode": "en"
          },
          "componentType": "locality",
          "confirmationLevel": "CONFIRMED"
        },
        {
          "componentName": {
            "text": "USA",
            "languageCode": "en"
          },
          "componentType": "country",
          "confirmationLevel": "CONFIRMED"
        },
        {
          "componentName": {
            "text": "94043"
          },
          "componentType": "postal_code",
          "confirmationLevel": "CONFIRMED",
          "inferred": true
        },
        {
          "componentName": {
            "text": "CA",
            "languageCode": "en"
          },
          "componentType": "administrative_area_level_1",
          "confirmationLevel": "CONFIRMED",
          "inferred": true
        },
        {
          "componentName": {
            "text": "1351"
          },
          "componentType": "postal_code_suffix",
          "confirmationLevel": "CONFIRMED",
          "inferred": true
        }
      ]
    },
    "geocode": {
      "location": {
        "latitude": 37.4223878,
        "longitude": -122.0841877
      },
      "plusCode": {
        "globalCode": "849VCWC8+X8"
      },
      "bounds": {
        "low": {
          "latitude": 37.4220699,
          "longitude": -122.084958
        },
        "high": {
          "latitude": 37.4226618,
          "longitude": -122.0829302
        }
      },
      "featureSizeMeters": 116.538734,
      "placeId": "ChIJj38IfwK6j4ARNcyPDnEGa9g",
      "placeTypes": [
        "premise"
      ]
    },
    "metadata": {
      "business": false,
      "poBox": false
    },
    "uspsData": {
      "standardizedAddress": {
        "firstAddressLine": "1600 AMPHITHEATRE PKWY",
        "cityStateZipAddressLine": "MOUNTAIN VIEW CA 94043-1351",
        "city": "MOUNTAIN VIEW",
        "state": "CA",
        "zipCode": "94043",
        "zipCodeExtension": "1351"
      },
      "deliveryPointCode": "00",
      "deliveryPointCheckDigit": "0",
      "dpvConfirmation": "Y",
      "dpvFootnote": "AABB",
      "dpvCmra": "N",
      "dpvVacant": "N",
      "dpvNoStat": "Y",
      "carrierRoute": "C909",
      "carrierRouteIndicator": "D",
      "postOfficeCity": "MOUNTAIN VIEW",
      "postOfficeState": "CA",
      "fipsCountyCode": "085",
      "county": "SANTA CLARA",
      "elotNumber": "0103",
      "elotFlag": "A",
      "addressRecordType": "S"
    }
  },
  "responseId": "de22bed8-7f52-44cb-8526-faceac57150a"
}

Validar um endereço atualizado

Em alguns casos, pode ser necessário fazer várias chamadas à API Address Validation para um único endereço. Por exemplo, o usuário pode fazer mudanças ou correções no endereço depois de ver os resultados da primeira validação. Em seguida, realize uma segunda validação no endereço atualizado.

Cada chamada da API de validação de endereço retorna um valor exclusivo no campo responseId da resposta. Se um endereço que você está tentando validar precisar ser revalidado, transmita responseId da primeira resposta de validação no campo previousResponseId para todas as solicitações de acompanhamento para a API Address Validation.

Ao incluir o campo previousResponseId na nova solicitação, você nos ajuda a melhorar a precisão geral da API.

Por exemplo, a resposta mostrada acima inclui o campo responseId:

  "responseId": "de22bed8-7f52-44cb-8526-faceac57150a"

Em seguida, revalide o endereço com uma alteração no número da rua de 1600 para 1500. Ao revalidar o endereço, inclua o campo previousResponseId com o valor de responseId da primeira resposta:

{
  "address": {
    "regionCode" : "US",
    "locality" : "Mountain View",
    "addressLines" : ["1500 Amphitheatre Pkwy"]
  },
  "previousResponseId": "de22bed8-7f52-44cb-8526-faceac57150a"
}

Para uma solicitação usando CASS:

{
  "address": {
    "regionCode" : "US",
    "locality" : "Mountain View",
    "addressLines" : ["1500 Amphitheatre Pkwy"]
  },
  "previousResponseId": "de22bed8-7f52-44cb-8526-faceac57150a",
  "enableUspsCass": true

}

Os resultados de cada chamada subsequente retornam um novo valor no campo responseId. No entanto, continue transmitindo o valor de responseId na primeira resposta no campo previousResponseId em todas as chamadas subsequentes para atualizações do endereço.

Tratamento de erros

A Address Validation API retorna mensagens de erro como parte da resposta a uma chamada de método. Por exemplo, se você omitir a chave de API da solicitação, o método retornará:

{
  "error": {
    "code": 403,
    "message": "The request is missing a valid API key.",
    "status": "PERMISSION_DENIED"
  }
}

Se você omitir um parâmetro de corpo obrigatório, como addressLines, o método retornará:

{
  "error": {
    "code": 400,
    "message": "Address lines missing from request.",
    "status": "INVALID_ARGUMENT"
  }
}

Para mais informações sobre erros e tratamento de erros, consulte Erros.

A Plataforma Google Maps é um Licenciado não exclusivo do Serviço Postal dos Estados Unidos. As seguintes marcas registradas pertencem ao Serviço Postal dos Estados Unidos e é usada com permissão: CATETM, CASSTM e SSN.