Para validar una dirección con la API de Address Validation, llama al método validateAddress (REST) o al método ValidateAddress (gRPC). En esta documentación, se usa REST para sus ejemplos, pero el enfoque es similar con gRPC.
Después de validar una dirección, puedes mostrar información a Google sobre el resultado de su validación. Para ello, llama al método provideValidationFeedback (REST) o al método ProvideValidationFeedback (gRPC). Para obtener información y ejemplos, consulta Cómo proporcionar comentarios de validación de direcciones.
Solicitud de validación de dirección
Para validar una dirección, envía una solicitud POST al método validateAddress:
https://addressvalidation.googleapis.com/v1:validateAddress?key=YOUR_API_KEY
Pasa un cuerpo de JSON a la solicitud que define la dirección que se validará:
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"
El campo address en el cuerpo de la solicitud, del tipo PostalAddress, debe contener al menos una entrada en addressLines.
El campo
regionCodees opcional. Si se omite, la API infiere la región a partir de la dirección. Sin embargo, para obtener un mejor rendimiento, te recomendamos que incluyas elregionCodesi lo sabes. Para obtener la lista de regiones admitidas, consulta las regiones compatibles.La longitud total del campo
addressestá limitada a 280 caracteres.
De manera opcional, habilita CASSTM cuando se valida una dirección
El Servicio Postal de Estados Unidos® (USPS®)1 mantiene el Sistema de Asistencia de Precisión de la Codificación (CASSTM) para brindar asistencia y certificar a los proveedores de validación de direcciones. Se confirmó que un servicio CASS CertifiedTM, como la API de Address Validation, es su capacidad de completar la información que falta en una dirección, estandarizarla y actualizarla para brindarte la dirección más actualizada y precisa.
Solo para las regiones “US” y “PR”, puedes habilitar de manera opcional el procesamiento de CASS si configuras enableUspsCass como true en el cuerpo de la solicitud.
Para obtener mejores resultados cuando uses CASS, proporciona una dirección que incluya la calle y el número de la calle junto con la ciudad, el estado y el código postal:
{
"address": {
"regionCode": "US",
"locality": "Mountain View",
"administrativeArea": "CA",
"postalCode": "94043",
"addressLines": ["1600 Amphitheatre Pkwy"]
},
"enableUspsCass": true
}
También puedes especificar la dirección completa como dos strings en el array addressLines:
{
"address": {
"regionCode": "US",
"addressLines": ["1600 Amphitheatre Pkwy", "Mountain View, CA, 94043"]
},
"enableUspsCass": true
}
Respuesta de validación de la dirección
Si la solicitud se realiza correctamente, el servidor responde con un código de estado HTTP 200 OK y un cuerpo de respuesta que contiene información sobre la dirección validada.
El campo result de la respuesta contiene un objeto ValidationResult. En este objeto, se incluye lo siguiente:
Un campo
address, del tipo Address, que contiene información detallada sobre la dirección.Un campo
geocode, del tipo Geocode, que contiene información geográfica de la direcciónUn campo
verdict, del tipo Veredicto, que contiene la validación de la dirección y el resultado del geocódigo.Un campo
metadata, del tipo AddressMetadata, que contiene los metadatos de la dirección.Un campo
uspsData, del tipo USPSData, que contiene los datos de USPS para la dirección Estos datos solo están disponibles para direcciones de Estados Unidos y Puerto Rico.
Debido a que la siguiente respuesta contiene addressComplete configurado como true, la respuesta indica que esta dirección es completamente válida, por lo que no se requiere más validación. Si la respuesta indica que alguna parte de la dirección no es válida, pídele al usuario que compruebe y confirme su entrada de dirección.
{
"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"
}
Valida una dirección actualizada
En algunos casos, es posible que debas realizar varias llamadas a la API de Address Validation para una sola dirección. Por ejemplo, el usuario podría realizar cambios o correcciones en su dirección después de ver los resultados de la primera validación. Luego, realizas una segunda validación en la dirección actualizada.
Cada llamada a la API de Address Validation muestra un valor único en el campo responseId de la respuesta. Si una dirección que intentas validar debe volver a validarse, pasa el responseId de la primera respuesta de validación en el campo previousResponseId para todas las solicitudes de seguimiento a la API de Address Validation.
Si incluyes el campo previousResponseId en la solicitud nueva, puedes ayudarnos a mejorar la precisión general de la API.
Por ejemplo, la respuesta que se muestra arriba incluye el campo responseId:
"responseId": "de22bed8-7f52-44cb-8526-faceac57150a"
Luego, deseas volver a validar la dirección con un cambio en el número de calle de 1600 a 1500. Cuando vuelvas a validar la dirección, incluye el campo previousResponseId con el valor de responseId de la primera respuesta:
{
"address": {
"regionCode" : "US",
"locality" : "Mountain View",
"addressLines" : ["1500 Amphitheatre Pkwy"]
},
"previousResponseId": "de22bed8-7f52-44cb-8526-faceac57150a"
}
Para una solicitud que usa CASS:
{
"address": {
"regionCode" : "US",
"locality" : "Mountain View",
"addressLines" : ["1500 Amphitheatre Pkwy"]
},
"previousResponseId": "de22bed8-7f52-44cb-8526-faceac57150a",
"enableUspsCass": true
}
Los resultados de cada llamada posterior muestran un valor nuevo en el campo responseId. Sin embargo, continúa pasando el valor de responseId de la primera respuesta en el campo previousResponseId en todas las llamadas posteriores de actualizaciones a la dirección.
Manejo de errores
La API de Address Validation muestra mensajes de error como parte de la respuesta a una llamada de método. Por ejemplo, si omites la clave de API de la solicitud, el método mostrará lo siguiente:
{
"error": {
"code": 403,
"message": "The request is missing a valid API key.",
"status": "PERMISSION_DENIED"
}
}
Si omites un parámetro del cuerpo obligatorio, como addressLines, el método mostrará lo siguiente:
{
"error": {
"code": 400,
"message": "Address lines missing from request.",
"status": "INVALID_ARGUMENT"
}
}
Para obtener más información sobre errores y manejo de errores, consulta Errores.
-
Google Maps Platform es un licenciatario no exclusivo del Servicio Postal de los Estados Unidos®. Las siguientes marcas son propiedad del Servicio Postal de Estados Unidos® y se usan con permiso: United States Postal Service®, CASSTM, CASS CertifiedTM. pasar