Package google.maps.addressvalidation.v1

Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.

Índice

Validación de direcciones

El servicio para validar direcciones.

Proporcionar comentarios de validación

rpc ProvideValidationFeedback(ProvideValidationFeedbackRequest) returns (ProvideValidationFeedbackResponse)

Comentarios sobre el resultado de la secuencia de intentos de validación. Esta debe ser la última llamada realizada después de una secuencia de llamadas de validación para la misma dirección y debe llamarse una vez que finalice la transacción. Solo se debe enviar una vez para la secuencia de solicitudes ValidateAddress necesarias a fin de validar una dirección por completo.

Validar dirección

rpc ValidateAddress(ValidateAddressRequest) returns (ValidateAddressResponse)

Valida una dirección.

Address

Detalles de la dirección analizada desde la entrada.

Campos
formatted_address

string

La dirección corregida, con formato de una sola línea, según las reglas de formato de dirección de la región donde se encuentra la dirección.

postal_address

PostalAddress

La dirección validada que se representa como una dirección postal.

address_components[]

AddressComponent

Lista sin ordenar. Los componentes individuales de la dirección con la dirección formateada y corregida, junto con la información de validación. Esto proporciona información sobre el estado de validación de los componentes individuales.

Los componentes de la dirección no están ordenados de una manera en particular. No hagas suposiciones sobre el orden de los componentes de dirección en la lista.

missing_component_types[]

string

Los tipos de componentes que se esperaba que estuvieran presentes en una dirección de correo con el formato correcto, pero no se encontraron en la entrada Y no se pudieron inferir. Los componentes de este tipo no están presentes en formatted_address, postal_address ni address_components. Un ejemplo podría ser ['street_number', 'route'] para una entrada como "Boulder, Colorado, 80301, EE.UU.". Puede encontrar la lista de tipos posibles aquí.

unconfirmed_component_types[]

string

Son los tipos de componentes que están presentes en el address_components, pero no se pudo confirmar que sean correctos. Este campo se proporciona para mayor comodidad: su contenido es equivalente a la iteración a través de address_components a fin de encontrar los tipos de todos los componentes en los que confirmation_level no es CONFIRMED o la marca inferred no se establece en true. Puede encontrar la lista de tipos posibles aquí.

unresolved_tokens[]

string

Cualquier token en la entrada que no se pudo resolver. Puede ser una entrada que no se reconoció como una parte válida de una dirección (por ejemplo, en una entrada como "123235253253 Main St, San Francisco, CA, 94105"), los tokens sin resolver pueden parecer ["123235253253"], ya que no parece un número válido de calle.

Componente de dirección

Representa un componente de dirección, como una calle, una ciudad o un estado.

Campos
component_name

ComponentName

El nombre de este componente.

component_type

string

El tipo del componente de la dirección. Consulta la Tabla 2: Tipos adicionales que muestra el servicio Places para obtener una lista de los tipos posibles.

confirmation_level

ConfirmationLevel

Indica el nivel de certeza de que el componente es correcto.

inferred

bool

Indica que el componente no era parte de la entrada, pero lo inferimos para la ubicación de la dirección y creemos que debe proporcionarse para una dirección completa.

spell_corrected

bool

Indica que la ortografía del nombre del componente se corrigió de una forma secundaria, por ejemplo, al cambiar dos caracteres que aparecían en el orden incorrecto. Esto indica un cambio estético.

replaced

bool

Indica que el nombre del componente se reemplazó por otro completamente diferente; por ejemplo, si se reemplazó un código postal incorrecto por uno correcto para la dirección. Este no es un cambio estético; el componente de entrada se cambió por uno diferente.

unexpected

bool

Indica un componente de dirección que no se espera que esté en una dirección postal para la región dada. Solo la conservamos porque formaba parte de la entrada.

Nivel de confirmación

Los diferentes valores posibles para los niveles de confirmación

Enumeradores
CONFIRMATION_LEVEL_UNSPECIFIED Valor predeterminado Este valor no se usa.
CONFIRMED Pudimos verificar que este componente existe y tiene sentido en el contexto del resto de la dirección.
UNCONFIRMED_BUT_PLAUSIBLE No se pudo confirmar este componente, pero es posible que exista. Por ejemplo, un número de una calle dentro de un intervalo válido de números conocidos en una calle donde no se conocen números de casa específicos.
UNCONFIRMED_AND_SUSPICIOUS No se confirmó este componente, y es probable que sea incorrecto. Por ejemplo, un barrio que no coincide con el resto de la dirección.

Metadatos de dirección

Los metadatos de la dirección. No se garantiza que metadata se propague por completo en cada dirección que se envíe a la API de Address Validation.

Campos
business

bool

Indica que esta es la dirección de una empresa. Si no se establece, indica que el valor es desconocido.

po_box

bool

Indica que la dirección de un apartado postal. Si no se establece, indica que el valor es desconocido.

residential

bool

Indica que esta es la dirección de una residencia. Si no se establece, indica que el valor es desconocido.

Nombre del componente

Un wrapper para el nombre del componente.

Campos
text

string

El texto del nombre. Por ejemplo, "5th Avenue" para el nombre de una calle o "1253" para el número de una calle.

language_code

string

El código de idioma BCP-47. Esto no estará presente si el nombre del componente no está asociado a un idioma, como un número de calle.

Geocodificación

Contiene información sobre el lugar en el cual se realizó la geocodificación.

Campos
location

LatLng

La ubicación geográfica de la entrada.

Se prefiere el uso de id. de sitio en lugar de direcciones, coordenadas de latitud y longitud o códigos plus. El uso de coordenadas al calcular o calcular las indicaciones en automóvil siempre implicará el ajuste del punto en la ruta más cercana a dichas coordenadas. Es posible que no sea una ruta que conduzca de forma rápida o segura al destino y que no esté cerca de un access point que dirija a la propiedad. Además, cuando una ubicación tiene codificación geográfica inversa, no hay garantía de que la dirección que se muestre coincida con la original.

plus_code

PlusCode

El código plus correspondiente al location

bounds

Viewport

Los límites del lugar geocodificado.

feature_size_meters

float

El tamaño del lugar geocodificado en metros. Esta es otra medida del grosor de la ubicación geocodificada, pero en tamaño físico y no en significado semántico.

place_id

string

El PlaceID del lugar al que se ingresa este código geográfico.

Para obtener más información sobre los IDs de lugar, consulta este vínculo.

place_types[]

string

Los tipos de sitios a los que se geocodificó la entrada. Por ejemplo, ['locality', 'political']. La lista completa de tipos se puede encontrar aquí.

PlusCode

El código plus (http://plus.codes) es una referencia de ubicación con dos formatos: código global que define un rectángulo de 14mx14m (1/8000 de un grado) o más pequeño y un código compuesto que reemplaza el prefijo por una ubicación de referencia.

Campos
global_code

string

Código global (completa) del lugar, como "9FWM33GV+HQ", que representa un área de 1/8000 por 1/8000 grados (~14 por 14 metros).

compound_code

string

El código compuesto del lugar, como "33GV+HQ, Ramberg, Noruega", que contiene el sufijo del código global y reemplaza el prefijo con un nombre con formato de una entidad de referencia.

Proporcionar opiniónFeedback

La solicitud para enviar comentarios de validación.

Campos
conclusion

ValidationConclusion

Obligatorio. El resultado de la secuencia de intentos de validación.

Si este campo se establece como VALIDATION_CONCLUSION_UNSPECIFIED, se mostrará un error INVALID_ARGUMENT.

response_id

string

Obligatorio. Es el ID de la respuesta a la que corresponde este comentario. Este debería ser el [response_id][google.maps.addressvalidation.v1.ValidateAddressRequest.response_id] de la primera respuesta en una serie de intentos de validación de dirección.

Conclusión de validación

Los posibles resultados finales de la secuencia de solicitudes de validación de dirección que se necesitan para validar una dirección.

Enumeradores
VALIDATION_CONCLUSION_UNSPECIFIED Este valor no se usa. Si el campo ProvideValidationFeedbackRequest.conclusion se configura como VALIDATION_CONCLUSION_UNSPECIFIED, se mostrará un error INVALID_ARGUMENT.
VALIDATED_VERSION_USED La versión de la dirección que mostró la API de Address Validation se usó para la transacción.
USER_VERSION_USED La versión de la dirección que proporcionó el usuario se usó para realizar la transacción
UNVALIDATED_VERSION_USED Se usó una versión de la dirección que se ingresó después del último intento de validación, pero que no se volvió a validar.
UNUSED Se abandonó la transacción y no se usó la dirección.

Proporcionar respuestas de comentarios de validación

La respuesta para los comentarios de validación.

La respuesta estará vacía si los comentarios se envían correctamente.

Dirección USB

Representación en USPS de una dirección de EE.UU.

Campos
first_address_line

string

Primera línea de dirección.

firm

string

Nombre de empresa.

second_address_line

string

Segunda línea de dirección.

urbanization

string

Nombre de la urbanización puertorriqueña.

city_state_zip_address_line

string

Ciudad + estado + código postal

city

string

Nombre de la ciudad.

state

string

Código de estado de 2 letras.

zip_code

string

Código postal, p.ej. 10009.

zip_code_extension

string

Extensión de código postal de 4 dígitos, p.ej., 5023.

Datos

Los datos USPS para la dirección. No se garantiza que uspsData se propague por completo en cada dirección de EE.UU. o PR que se envíe a la API de Address Validation. Se recomienda integrar los campos de dirección alternativa en la respuesta si usas uspsData como parte principal de la respuesta.

Campos
standardized_address

UspsAddress

Dirección estandarizada del USPS.

delivery_point_code

string

Código de punto de entrega de 2 dígitos

delivery_point_check_digit

string

Es el dígito de control del punto de entrega. Este número se agrega al final del código de entrega de punto de barras para los correos electrónicos escaneados de forma mecánica. Si sumas todos los dígitos del código de barras de entrega, el código de verificación del punto de entrega, el código postal y el código postal +4, se obtiene un número que se puede dividir por 10.

dpv_confirmation

string

Los valores posibles para la confirmación del DPV. Muestra un solo carácter.

  • Y: La dirección se confirmó con un DPV para el número principal y el secundario.
  • N: No se pudo confirmar la información del DPV sobre el número principal y secundario.
  • S: La dirección se confirmó con el DPV solo para el número principal, y la información del número secundario estaba presente, sin confirmar.
  • D: Se confirmó la dirección a través del DPV solo para el número principal, y faltaba la información del número secundario.
dpv_footnote

string

Son las notas al pie de la validación del punto de entrega. Se pueden unir varias notas al pie en la misma string.

  • AA: La dirección de entrada coincide con el archivo ZIP+4.
  • A1: La dirección de entrada no coincide con el archivo ZIP + 4
  • BB: coincide con el DPV (todos los componentes)
  • CC: Número secundario no coincidente (presente, pero no válido)
  • N1: Falta el número secundario de la dirección de rascacielos
  • M1: Falta el número principal
  • M3: El número principal no es válido.
  • P1: Falta la dirección RR o el número de casilla de ayuda del dispositivo de entrada
  • P3: La dirección de entrada, la RR o el número del Centro de ayuda no son válidas
  • F1: La dirección de entrada debe coincidir con una dirección militar.
  • G1: La dirección de entrada coincide con una dirección de entrega general
  • U1: La dirección de entrada coincide con un código postal único.
  • PB: La dirección de entrada coincide con el registro de PBSA.
  • RR: Dirección confirmada del DPV con información de PMB
  • R1: Dirección confirmada de DPV sin información de PMB
  • R7: registro R777 o R779 de la empresa de transporte
dpv_cmra

string

Indica si la dirección es una CMRA (comercio receptora de correo comercial): una empresa privada que recibe correos para clientes. Muestra un solo carácter.

  • Y: La dirección es una CMRA.
  • N: La dirección no es una CMRA.
dpv_vacant

string

¿Este lugar está vacante? Muestra un solo carácter.

  • Y: La dirección está vacía
  • N: La dirección no está vacía.
dpv_no_stat

string

¿La dirección no es estadística o la dirección está activa? Ninguna dirección estadística es aquella que no está ocupada continuamente o que no funciona el USPS. Muestra un solo carácter.

  • Y: La dirección no está activa.
  • N: La dirección está activa
carrier_route

string

El código de ruta del proveedor. Un código de cuatro caracteres, que consta de un prefijo de una letra y un designador de ruta de tres dígitos.

Prefijos:

  • C: Ruta del operador (o ruta de la ciudad)
  • R: Ruta rural
  • H: Ruta de contrato de autopista
  • B: Sección del apartado postal
  • G: Unidad de entrega general
carrier_route_indicator

string

Indicador de orden de la tarifa de la ruta de transporte,

ews_no_match

bool

La dirección de entrega debe coincidir, pero el archivo EWS indica que una coincidencia exacta estará disponible pronto.

post_office_city

string

Ciudad de oficina postal principal.

post_office_state

string

Estado de la oficina de correo principal

abbreviated_city

string

Ciudad abreviada

fips_county_code

string

Código de condado del FIPS.

county

string

Nombre del condado.

elot_number

string

Número de línea de viaje mejorada (eLOT)

elot_flag

string

eLOT Ascendente/Descendente (A/D).

po_box_only_postal_code

bool

Código postal solo para el apartado postal.

pmb_designator

string

Designador de unidad de PMB (buzón de correo privado).

pmb_number

string

Número de PMB (buzón de correo privado)

address_record_type

string

Tipo de registro de dirección que coincide con la dirección de entrada.

  • F: FIRM. Esta es una coincidencia con un registro de empresa, que es el mejor nivel de coincidencia disponible para una dirección.
  • G: ENTREGA GENERAL. Esta información coincide con un registro de publicación general.
  • H: EDICIÓN/DEPARTAMENTO Esta es una coincidencia con el registro de un edificio o departamento.
  • P: CAJA POSTAL. Esta corresponde a una casilla postal.
  • R: RUTA RURAL o CONTRATO PARA ALTAS LUGARES: Esta es una coincidencia con una ruta rural o un registro de contrato de autopista, que pueden tener rangos de números de caja asociados.
  • S: STREET RECORD: Es una coincidencia con un registro de Street View que contiene un rango de números primarios válido.
default_address

bool

Indicador de que se encontró una dirección predeterminada, pero existen direcciones más específicas.

error_message

string

Mensaje de error para la recuperación de datos del USPS. Esto se propaga cuando se suspende el procesamiento de USPS debido a la detección de direcciones creadas de forma artificial.

Es posible que los campos de datos del USPS no se propaguen cuando se produce este error.

cass_processed

bool

Indicador de que la solicitud se procesó mediante CASS.

ValidarSolicitud

La solicitud para validar una dirección.

Campos
address

PostalAddress

Obligatorio. La dirección que se valida. Las direcciones sin formato deben enviarse a través de address_lines.

La longitud total de los campos en esta entrada no debe exceder los 280 caracteres.

Puede encontrar las regiones admitidas en las Preguntas frecuentes.

El valor language_code en la dirección de entrada está reservado para usos futuros y se ignora hoy. El resultado de la dirección validada se propagará en función del idioma preferido de la dirección determinada, como lo identifica el sistema.

La API de Address Validation ignora los valores en recipients y organization. Los valores de esos campos se descartarán y no se mostrarán. No las configures.

previous_response_id

string

Este campo debe estar vacío para la primera solicitud de validación de dirección. Si se necesitan más solicitudes para validar por completo una sola dirección (por ejemplo, si los cambios que realiza el usuario después de la validación inicial deben volver a validarse), cada solicitud de seguimiento debe propagar este campo con la response_id de la primera respuesta en la secuencia de validación.

enable_usps_cass

bool

Habilita el modo compatible con USPS CASS. Esto afecta solo el campo google.maps.addressvalidation.v1.ValidationResult.usps_data de google.maps.addressvalidation.v1.ValidationResult. Nota: En el caso de las solicitudes compatibles con el USPS CASS para direcciones en Puerto Rico, se debe proporcionar una google.type.PostalAddress.region_code de address como "PR", o una google.type.PostalAddress.administrative_area de la address como "Puerto Rico" (distinción entre mayúsculas y minúsculas) o "PR".

Se recomienda usar una address con componentes o, como alternativa, especificar al menos dos google.type.PostalAddress.address_lines, donde la primera línea contenga el nombre y el número de la calle, y la segunda, la ciudad, el estado y el código postal.

ValidateAddressResponse.

Es la respuesta a una solicitud de validación de dirección.

Campos
result

ValidationResult

El resultado de la validación de la dirección.

response_id

string

El UUID que identifica esta respuesta. Si es necesario volver a validar la dirección, este UUID debe acompañar la solicitud nueva.

ValidationResult

El resultado de la validación de una dirección.

Campos
verdict

Verdict

Veredictos generales

address

Address

Información sobre la dirección en sí y no sobre el geocódigo.

geocode

Geocode

Información sobre la ubicación y el lugar al que se codificó la dirección.

metadata

AddressMetadata

Otra información relevante sobre la entrega. No se garantiza que metadata se propague por completo en cada dirección que se envíe a la API de Address Validation.

usps_data

UspsData

Marcas de entrega adicionales proporcionadas por USPS. Solo se proporciona en las regiones US y PR.

Veredicto

Descripción general de los resultados de validación de la dirección y la codificación geográfica.

Campos
input_granularity

Granularity

El nivel de detalle de la dirección input. Es el resultado del análisis de la dirección de entrada y no proporciona indicadores de validación. Consulta validation_granularity para obtener más detalles sobre los indicadores de validación.

Por ejemplo, si la dirección de entrada incluye un número de departamento específico, la input_granularity será SUB_PREMISE. Si no podemos hacer coincidir el número de departamento en las bases de datos o el número de departamento no es válido, es probable que el validation_granularity sea PREMISE o inferior.

validation_granularity

Granularity

Nivel de detalle al que la API puede validar por completo la dirección. Por ejemplo, un validation_granularity de PREMISE indica que se pueden validar todos los componentes de la dirección en el nivel de PREMISE o más generales.

El resultado de la validación del componente por dirección se encuentra en google.maps.addressvalidation.v1.Address.address_components.

geocode_granularity

Granularity

Información sobre el nivel de detalle de geocode. Esto se puede interpretar como el significado semántico de qué tan aproximada o precisa es la ubicación geocodificada.

En ocasiones, puede diferir de la validation_granularity anterior. Por ejemplo, nuestra base de datos podría registrar la existencia de un número de apartamento, pero no tener una ubicación precisa para el departamento dentro de un gran complejo de departamentos. En ese caso, el validation_granularity será SUB_PREMISE, pero el geocode_granularity será PREMISE.

address_complete

bool

La dirección se considera completa si no hay tokens sin resolver, no hay componentes de dirección inesperados o faltantes. Consulta los campos missing_component_types, unresolved_tokens o unexpected para obtener más detalles.

has_unconfirmed_components

bool

Al menos un componente de la dirección no se puede categorizar ni validar. Consulta google.maps.addressvalidation.v1.Address.address_components para obtener más información.

has_inferred_components

bool

Se infirió al menos un componente de dirección (se agregó) que no estaba en la entrada. Consulta google.maps.addressvalidation.v1.Address.address_components para obtener más detalles.

has_replaced_components

bool

Se reemplazó al menos un componente de dirección. Consulta google.maps.addressvalidation.v1.Address.address_components para obtener más información.

Nivel de detalle

los diferentes niveles de detalle que puede tener una dirección o un geocódigo. Cuando se utilizan para indicar el nivel de detalle de una dirección, estos valores indican el nivel de detalle con el que la dirección identifica un destino de correo postal. Por ejemplo, una dirección como "Calle Principal 123, Redwood City, CA, 94061" identifica un PREMISE, mientras que "Redwood City, CA, 94061" identifica un LOCALITY. Sin embargo, si no podemos encontrar un geocódigo para "Calle principal 123" en Redwood City, el geocódigo que se muestra puede tener un nivel de detalle LOCALITY aunque la dirección sea más detallada.

Enumeradores
GRANULARITY_UNSPECIFIED Valor predeterminado Este valor no se usa.
SUB_PREMISE Resultado debajo del edificio, como un departamento.
PREMISE Resultado a nivel del edificio
PREMISE_PROXIMITY Un geocódigo que debe estar muy cerca de la ubicación de la dirección en el nivel del edificio. Solo se usa para geocódigos y no para direcciones.
BLOCK La dirección o codificación geográfica indica un bloque. Solo se usa en regiones con direcciones a nivel de bloque, como Japón.
ROUTE El geocódigo o la dirección son detallados en la ruta, como una calle, una ruta o una autopista.
OTHER Todas las demás granularidades, que se agrupan en intervalos porque no se pueden entregar.