Enviar uma solicitação de validação de 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 REST nos exemplos, mas a abordagem é semelhante à do gRPC.

Depois de validar um endereço, é possível retornar informações ao Google sobre o resultado da validação chamando o método provideValidationFeedback (REST) ou ProvideValidationFeedback (gRPC). Veja informações e exemplos em 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 ao 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 inferirá a região a partir do endereço. No entanto, para um melhor desempenho, recomendamos que você inclua o regionCode, se souber. Consulte a lista de regiões compatíveis.

• O tamanho total do campo address é limitado a 280 caracteres.

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

O United States Postal Service® (USPS®)¹ mantém o Coding Accuracy Support System (CASSTM) para oferecer suporte e certificar provedores de validação de endereço. Um serviço CASS CertifiedTM, como a API Address Validation, foi confirmado por sua capacidade de preencher informações ausentes em um endereço, padronizá-las e atualizá-las para fornecer o endereço mais atual e preciso.

Somente para as regiões "US" e "PR", você tem a opção de ativar o processamento de CASS configurando enableUspsCass como true no corpo da solicitação.

Para melhores resultados ao usar CASS, forneça um endereço que inclua o número da rua e a 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
}

Você também pode 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 de validação de 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 Endereço, contendo informações detalhadas sobre o endereço.

• Um campo geocode, do tipo Geocode, contendo informações de geocodificação do endereço.

• Um campo verdict, do tipo Verdict, contendo a validação do endereço e o resultado do geocódigo.

• Um campo metadata, do tipo AddressMetadata, contendo os metadados do endereço.

• Um campo uspsData, do tipo USPSData, contendo os dados do USPS do endereço. Esses dados estão disponíveis apenas para endereços nos Estados Unidos e Porto Rico.

Como a resposta a seguir contém addressComplete definido como true, ela indica que o endereço é totalmente válido. Portanto, nenhuma outra validação é necessária. Se a resposta indicar que alguma parte do endereço é inválida, solicite que o usuário verifique e confirme a entrada do 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 alterações ou correções no endereço depois de ver os resultados da primeira validação. Em seguida, faça uma segunda validação no endereço atualizado.

Cada chamada da API Address Validation 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, você quer revalidar 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 que usa 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 de atualizações para o 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.