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 o método ValidateAddress (gRPC). Nesta documentação, usamos REST para os 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 do endereço chamando o método provideValidationFeedback (REST) ou ProvideValidationFeedback (gRPC). Para informações e exemplos, consulte Enviar feedback sobre a 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 omitido, a API deduzirá a região do endereço. No entanto, para ter o melhor desempenho, recomendamos que você inclua o regionCode, se souber. Para ver a lista de regiões compatíveis, consulte regiões compatíveis.
O comprimento total do campo address é limitado a 280 caracteres.

Ative o CASSTM ao validar um endereço

O Serviço postal dos Estados Unidos (USPS®, na sigla em inglês)¹ 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 o endereço mais atual e preciso.

Somente para as regiões "US" e "PR", é possível ativar o processamento de 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 da rua, além da cidade, do estado e do 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 da validação do endereço

Se a solicitação for bem-sucedida, o servidor vai 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 mais informações sobre as diferenças entre address e geocode, consulte Endereço x geocodificador.
Um campo verdict, do tipo Veredito, que contém a validação de endereço e o resultado de geocódigo.
Um campo metadata, do tipo AddressMetadata, que contém os metadados do endereço.
Um campo uspsData, do tipo USPSData, contendo os dados USPS do endereço. Esses dados estão disponíveis apenas 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 outra validação é necessária. Se a resposta indicar que parte do endereço é inválida, solicite que o usuário verifique e confirme a entrada de endereço.

{
  "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, execute 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 o 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 o 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 da primeira resposta no campo previousResponseId em todas as chamadas subsequentes para atualizações do endereço.

Tratamento de erros

A API Address Validation 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 marcas registradas a seguir são de propriedade do serviço postal dos Estados Unidos e são usadas com permissão: CASTM, CASSTM e CASS Certified. ━