Migra de Geocoding v3 a v4

Desarrolladores del Espacio Económico Europeo (EEE)

Si tu dirección de facturación se encuentra en el Espacio Económico Europeo, a partir del 8 de julio de 2025, se aplicarán las Condiciones del Servicio de Google Maps Platform para el EEE al uso que hagas de los Servicios. La funcionalidad varía según la región. Obtén más información.

La API de Geocoding v4 presenta varios extremos nuevos que reemplazan la funcionalidad de la versión 3 de la API. En esta guía, se muestra cómo migrar tu app para usar los nuevos extremos de la versión 4.

Puedes usar tus claves de API existentes con los nuevos extremos de la versión 4. Sin embargo, si solicitaste un aumento de la cuota en la versión 3 de la API, debes solicitar un aumento en las nuevas APIs de la versión 4. No hay una ruta de migración para los usuarios de JavaScript.

Nota: Durante la versión preliminar, los métodos de la API de Geocoding v4 están limitados a 25 consultas por segundo (QPS). Para obtener información sobre cómo solicitar una cuota más alta, consulta Cómo ver y administrar cuotas y selecciona API de Geocoding como el servicio.

Migra desde la API de Geocoding v3

Si usas Geocoding para geocodificar direcciones, debes migrar al extremo de la versión 4 Geocode an address, que acepta una solicitud GET.

La API de v4 cambia los nombres, la estructura y la compatibilidad con varios parámetros. Te recomendamos que uses una máscara de campo para especificar los campos que deseas que se muestren en la respuesta.

Advertencia: En todos los extremos de la versión 4, los nombres de los campos se formatean con camel case en minúsculas (p.ej., addressComponents), a diferencia de los extremos de la versión 3, que usaban snake case (p.ej., address_components). Las respuestas de RPC siguen usando snake case en la versión 4, al igual que en la versión 3.

Cambios en los parámetros de la solicitud

Parámetro de la versión 3	Parámetro de v4	Notas
address, components	address	La dirección no estructurada (v3 de address) ahora se pasa en la ruta de URL. Los filtros de componentes (v3 components) ahora se pasan como parámetros de búsqueda address.*.
bounds	locationBias.rectangle	Se cambió el nombre y la estructura a objeto.
language	languageCode	Se cambió el nombre.
region	regionCode	Se cambió el nombre.
extra_computations	Eliminado

Cambios en los campos de respuesta

Campo de v3	Campo v4	Notas
status, error_message	Eliminado	La versión 4 usa códigos de estado HTTP y cuerpos de error.
results.address_components.long_name/results.address_components.short_name	results.addressComponents.longText/results.addressComponents.shortText	Se cambió el nombre.
results.geometry.location_type	results.granularity	Se cambió el nombre.
results.geometry.location	results.location	Nombres de los campos: lat/lng -> latitude/longitude
results.geometry.viewport	results.viewport	Nombres de los campos: northeast/southwest -> high/low
results.postcode_localities	results.postalCodeLocalities	Se cambió el nombre. Ahora se devuelve para una o más localidades (se requiere la versión 3 > 1).
results.partial_match	Eliminado
Nuevo	results.addressComponents.languageCode	Es el idioma del componente de dirección específico.
Nuevo	results.bounds	Límites explícitos con high/low.
Nuevo	results.place	Es el nombre del recurso del lugar.
Nuevo	results.postalAddress	Objeto PostalAddress estructurado.

Migra desde la API de Geocoding inversa v3

Si usas la geocodificación inversa para convertir coordenadas en direcciones, debes migrar al extremo de la versión 4 Geocode inversa una ubicación, que acepta una solicitud GET.

La API de v4 cambia los nombres, la estructura y la compatibilidad con varios parámetros. Te recomendamos que uses una máscara de campo para especificar los campos que deseas que se muestren en la respuesta.

Advertencia: En todos los extremos de la versión 4, los nombres de los campos se formatean con camel case en minúsculas (p.ej., addressComponents), a diferencia de los extremos de la versión 3, que usaban snake case (p.ej., address_components). Las respuestas de RPC siguen usando snake case en la versión 4, al igual que en la versión 3.

Cambios en los parámetros de la solicitud

Parámetro de la versión 3	Parámetro de v4	Notas
language	languageCode	Se cambió el nombre.
region	regionCode	Se cambió el nombre.
result_type	types	Se cambió el nombre; usa parámetros de consulta repetidos.
location_type	granularity	Se cambió el nombre; usa parámetros de consulta repetidos.
extra_computations	Eliminado

Cambios en los campos de respuesta

Campo de v3	Campo v4	Notas
status, error_message	Eliminado	La versión 4 usa códigos de estado HTTP y cuerpos de error.
results.address_components.long_name/results.address_components.short_name	results.addressComponents.longText/results.addressComponents.shortText	Se cambió el nombre.
results.geometry.location_type	results.granularity	Se cambió el nombre.
results.geometry.location	results.location	Nombres de los campos: lat/lng -> latitude/longitude
results.geometry.viewport	results.viewport	Nombres de los campos: northeast/southwest -> high/low
Nuevo	results.addressComponents.languageCode	Es el idioma del componente de dirección específico.
Nuevo	results.bounds	Límites explícitos con high/low.
Nuevo	results.place	Es el nombre del recurso del lugar.
Nuevo	results.postalAddress	Objeto PostalAddress estructurado.

Migra desde la API de Place Geocoding v3

Si usas place_id para obtener la dirección de un ID de lugar específico con la versión 3 de la API de Geocoding, debes migrar al extremo Place Geocoding de la versión 4, que acepta una solicitud GET.

La API de v4 cambia los nombres, la estructura y la compatibilidad con varios parámetros. Te recomendamos que uses una máscara de campo para especificar los campos que deseas que se muestren en la respuesta.

Advertencia: En todos los extremos de la versión 4, los nombres de los campos se formatean con camel case en minúsculas (p.ej., addressComponents), a diferencia de los extremos de la versión 3, que usaban snake case (p.ej., address_components). Las respuestas de RPC siguen usando snake case en la versión 4, al igual que en la versión 3.

Cambios en los parámetros de la solicitud

Parámetro de la versión 3	Parámetro de v4	Notas
place_id	Campo place en el proto de solicitud	El ID de lugar ahora se proporciona como un parámetro de ruta places/{place}, por ejemplo: https://geocode.googleapis.com/v4beta/geocode/places/ChIJj61dQgK6j4AR4GeTYWZsKWw. Este campo se asigna al campo de lugar en la solicitud subyacente.
language	languageCode	Se cambió el nombre.
region	regionCode	Se cambió el nombre.

Cambios en los campos de respuesta

Campo de v3	Campo v4	Notas
status, error_message	Eliminado	La versión 4 usa códigos de estado HTTP y cuerpos de error.
results	(root)	La versión 4 devuelve un solo objeto de resultado, no un array results.
results.address_components.long_name/results.address_components.short_name	addressComponents.longText/addressComponents.shortText	Se cambió el nombre.
results.geometry.location_type	granularity	Se cambió el nombre.
results.geometry.location	location	Nombres de los campos: lat/lng -> latitude/longitude
results.geometry.viewport	viewport	Nombres de los campos: northeast/southwest -> high/low
results.postcode_localities	postalCodeLocalities	Se cambió el nombre. Ahora se devuelve para una o más localidades (se requiere la versión 3 > 1).
Nuevo	addressComponents.languageCode	Es el idioma del componente de dirección específico.
Nuevo	bounds	Límites explícitos con high/low.
Nuevo	place	Es el nombre del recurso del lugar.
Nuevo	postalAddress	Objeto PostalAddress estructurado.

Migra de los datos hiperlocales de Geocoding a los destinos

Las siguientes funciones de la API de Geocoding v3 se reemplazan por el extremo SearchDestinations de la API de Geocoding v4:

• Entradas
• Puntos de navegación
• Esquemas de edificios
• Terrenos

Si usabas la API de Geocoding v3 para las funciones anteriores, usa este documento para obtener ayuda y usar el extremo de SearchDestinations en su lugar para obtener estas funciones. En este documento, se explica en qué parte de la respuesta de la API de SearchDestinations se encuentran estas funciones y las diferencias en la forma en que se representan en las respuestas de la API entre la API de Geocoding v3 y el extremo de SearchDestinations de la API de Geocoding v4.

Entradas

Para obtener las entradas asociadas a un destination, usa el campo destination.entrances.

Ten en cuenta que el formato de un entrance es ligeramente diferente del formato de entrada en la API de Geocoding v3. Cada entrada en destination.entrances tiene los siguientes campos:

• displayName: Es un nuevo campo opcional que tendrá un nombre legible para la entrada, por ejemplo, "Puerta B".
• location: Es una ubicación de tipo LatLng, que es diferente del formato que se usa en la API de Geocoding v3.
• tags: Es igual que el campo tags de las entradas de la API de Geocoding v3.
• place: Es análogo al campo buildingPlaceId de las entradas de la API de Geocoding v3. Sin embargo, el ID de lugar en este campo podría ser para un lugar de cualquier tipo, no necesariamente solo un edificio.

Puntos de navegación

Para obtener los puntos de navegación asociados con un destination, usa el campo destination.navigationPoints.

Ten en cuenta que el formato de un navigationPoint es ligeramente diferente del formato de punto de navegación en la API de Geocoding v3. Cada punto de navegación en destination.navigationPoints tiene los siguientes campos:

• displayName: Es un nuevo campo opcional que tendrá un nombre legible para el punto de navegación, por ejemplo, “5th Ave”.
• location: Es una ubicación de tipo LatLng, que es diferente del formato que se usa en la API de Geocoding v3.
• travelModes: Es similar al campo restrictedTravelModes de los puntos de navegación de la versión 3 de la API de Geocoding. Los valores de enumeración posibles son los mismos. La única diferencia es que este campo ahora representa los modos de viaje aceptables para el punto de navegación, en lugar de los modos de viaje restringidos.
• usage: Es un campo nuevo que contiene los casos de uso admitidos por el punto de navegación. Ten en cuenta que la mayoría de los puntos de navegación tendrán un uso de UNKNOWN, pero eso no significa necesariamente que el uso del punto de navegación esté restringido de alguna manera.

Esquemas de edificios

Para obtener los contornos de los edificios asociados a un objeto destination, debes usar el campo displayPolygon de los objetos placeView en el objeto destination que representan edificios. Para cada placeView, puedes verificar si es un edificio con el campo placeView.structureType. Si el tipo de estructura es BUILDING, puedes obtener el esquema del campo placeView.displayPolygon. El objeto placeView también tendrá campos adicionales para el edificio que no estaban en la API de Geocoding v3.

Nota: ¿Solo buscas el polígono del edificio en una ubicación determinada? Puedes usar el parámetro placeFilter en tu solicitud para limitar los resultados. Para devolver solo los resultados de la compilación, establece structureType en "BUILDING" dentro de placeFilter. Si tu prioridad es obtener un polígono (incluso para ubicaciones sin direcciones precisas), establece addressability en "ANY" en placeFilter para devolver el polígono más preciso disponible.

Ejemplo

{
  "locationQuery": {
    "location": {
      "latitude": 37.4224,
      "longitude": -122.0841
    },
    "placeFilter": {
      "structureType": "BUILDING",
      "addressability": "ANY"
    }
  }
}
  

Un objeto destination puede tener un objeto placeView que represente un edificio en los siguientes campos:

• destination.primary: Es el lugar principal del destino.
• destination.containingPlaces: Es un campo repetido que puede contener lugares más grandes que "contienen" el lugar principal. Por ejemplo, si el lugar principal es un subpremise, containingPlaces suele contener el placeView que representa el edificio.
• destination.subDestinations: Es un campo repetido que puede contener subdestinos del lugar principal. Por ejemplo, las unidades de departamentos individuales de un edificio. Por lo general, este campo no tendrá un placeView que represente un edificio.

Ten en cuenta que el formato de placeView.displayPolygon coincide con el formato de contorno de edificio en la API de Geocodificación v3, que es el formato GeoJSON, con el formato RFC 7946.

Terrenos

Al igual que con los esquemas de edificios, para obtener los terrenos asociados a un destination, debes usar el campo displayPolygon de los objetos placeView en el destination que representan terrenos. Para cada placeView, puedes verificar si es un motivo con el campo placeView.structureType. Si el tipo de estructura es GROUNDS, puedes obtener el esquema del campo placeView.displayPolygon. El objeto placeView también tendrá campos adicionales para los motivos que no estaban en la API de Geocoding v3.

Un objeto destination puede tener un objeto placeView que represente un motivo en los siguientes campos:

• destination.primary
• destination.containingPlaces
• destination.subDestinations

Ten en cuenta que el formato de placeView.displayPolygon coincide con el formato de esquema de terrenos en la API de Geocoding v3, que es el formato GeoJSON, con el formato RFC 7946.

Usa una máscara de campo para solicitar estas funciones

El extremo SearchDestinations requiere una máscara de campo, como se explica en Cómo elegir los campos que se devolverán. La máscara de campo se puede establecer en * para devolver todos los campos, o bien puedes establecerla en los campos específicos que deseas recibir. Por ejemplo, la siguiente solicitud a la API establece la máscara de campo para recibir todos los campos necesarios para obtener las entradas, los puntos de navegación, los esquemas de edificios y los terrenos de un destino:

curl -X POST -d '{"place": "places/ChIJG3kh4hq6j4AR_XuFQnV0_t8"}' \
  -H "X-Goog-Api-Key: API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Goog-FieldMask: destinations.entrances,destinations.navigationPoints,destinations.primary,destinations.containingPlaces,destinations.subDestinations" \
  https://geocode.googleapis.com/v4alpha/geocode/destinations