Comienza a usar la versión 4 de la API de Geocoding

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.

Antes de comenzar: Para comenzar a utilizar la API de Geocoding, primero debes tener un proyecto con una cuenta de facturación y la API de Geocoding habilitada. Recomendamos crear varios propietarios de proyecto y administradores de facturación para que tu equipo siempre tenga a alguien disponible con estas funciones. Si deseas obtener más información, consulta el artículo sobre cómo configurar tu proyecto en la consola de Cloud.

La API de Geocoding v4 proporciona dos familias de funciones principales: la búsqueda de destinos para obtener atributos hiperlocales enriquecidos y la geocodificación básica (conversión de coordenadas a direcciones). ¿No sabes qué método usar? Consulta Cómo elegir un método de geocodificación.

• Buscar destinos (SearchDestinations): Recupera detalles enriquecidos de llegada para un destino, incluidas las entradas de edificios, los puntos de navegación con rutas, los contornos de edificios o terrenos, los subdestinos y los puntos de referencia cercanos.
• Geocodificación (GeocodeAddress): Convierte direcciones en coordenadas de latitud y longitud para colocar marcadores básicos o centrar un mapa.
• Geocodificación inversa (GeocodeLocation): Convierte coordenadas geográficas en una dirección legible por humanos.
• Geocodificación de lugares (GeocodePlace): Busca la dirección con formato y las coordenadas de un ID de lugar conocido.

Ejemplos de solicitudes y respuestas

Puedes acceder a la API de Geocoding a través de una interfaz HTTP. A continuación, se muestran ejemplos de guías de inicio rápido para Buscar destinos, geocodificación directa y geocodificación inversa.

Solicitud y respuesta de búsqueda de destinos (datos de llegada hiperlocales)

En el siguiente ejemplo, se envía una solicitud HTTP POST a SearchDestinations para "1600 Amphitheatre Parkway, Mountain View, CA". Ten en cuenta que SearchDestinations requiere un encabezado X-Goog-FieldMask que especifique los campos que se deben devolver:

curl -X POST -d '{
  "addressQuery": {
    "addressQuery": "1600 Amphitheatre Parkway, Mountain View, CA"
  }
}' \
-H 'Content-Type: application/json' \
-H 'X-Goog-FieldMask: destinations.primary.displayName,destinations.primary.formattedAddress,destinations.primary.location,destinations.primary.displayPolygon,destinations.entrances,destinations.navigationPoints,destinations.landmarks' \
-H "X-Goog-Api-Key: YOUR_API_KEY" \
"https://geocode.googleapis.com/v4/geocode/destinations"

A continuación, se muestra un ejemplo de respuesta de SearchDestinations con el polígono de la huella del edificio, las entradas preferidas, los puntos de navegación que se pueden usar para trazar rutas y los puntos de referencia cercanos:

{
  "destinations": [
    {
      "primary": {
        "displayName": { "text": "Googleplex", "languageCode": "en" },
        "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
        "location": { "latitude": 37.4220656, "longitude": -122.0840897 },
        "displayPolygon": {
          "type": "Polygon",
          "coordinates": [
            [
              [-122.084958, 37.422145],
              [-122.084112, 37.422610],
              [-122.083510, 37.421980],
              [-122.084958, 37.422145]
            ]
          ]
        }
      },
      "entrances": [
        {
          "location": { "latitude": 37.422189, "longitude": -122.084215 },
          "tags": ["PREFERRED"]
        }
      ],
      "navigationPoints": [
        {
          "navigationPointToken": "Eg...",
          "displayName": { "text": "Amphitheatre Pkwy Dropoff", "languageCode": "en" },
          "location": { "latitude": 37.421912, "longitude": -122.084301 },
          "travelModes": ["DRIVE"],
          "usages": ["DROPOFF", "PICKUP"]
        }
      ],
      "landmarks": [
        {
          "place": { "displayName": { "text": "Charleston Park", "languageCode": "en" } },
          "relationalDescription": { "text": "Adjacent to Charleston Park", "languageCode": "en" },
          "straightLineDistanceMeters": 85.4
        }
      ]
    }
  ]
}

Solicitud y respuesta de geocodificación (búsqueda de latitud y longitud)

En el siguiente ejemplo, se solicitan la latitud y la longitud de "1600 Amphitheatre Parkway, Mountain View, CA" y se especifica que el resultado debe estar en formato JSON.

curl -H "X-Goog-Api-Key: YOUR_API_KEY" \
"https://geocode.googleapis.com/v4/geocode/address/1600+Amphitheatre+Parkway,+Mountain+View,+CA"

Para probar esto, ingresa la URL en tu navegador web (asegúrate de reemplazar YOUR_API_KEY por tu clave de API real). En la respuesta se incluyen la latitud y longitud de la dirección.

Consulta la guía para desarrolladores para obtener más información sobre cómo crear URLs de solicitud de geocodificación, los parámetros disponibles y cómo interpretar la respuesta.

A continuación, se muestra un ejemplo de respuesta de geocodificación, en JSON:

{
  "results": [
    {
      "place": "//places.googleapis.com/places/ChIJ2Z2idB66j4ARI43TG-9RoCQ",
      "placeId": "ChIJ2Z2idB66j4ARI43TG-9RoCQ",
      "location": {
        "latitude": 37.4438238,
        "longitude": -122.0869895
      },
      "granularity": "ROOFTOP",
      "viewport": {
        "low": {
          "latitude": 37.4424748197085,
          "longitude": -122.0883384802915
        },
        "high": {
          "latitude": 37.445172780291493,
          "longitude": -122.08564051970852
        }
      },
      "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
      "postalAddress": {
        "regionCode": "US",
        "languageCode": "en",
        "postalCode": "94043-1351",
        "administrativeArea": "CA",
        "locality": "Mountain View",
        "addressLines": [
          "1600 Amphitheatre Pkwy"
        ]
      },
      "addressComponents": [
        {
          "longText": "1600",
          "shortText": "1600",
          "types": [
            "street_number"
          ]
        },
        {
          "longText": "Amphitheatre Parkway",
          "shortText": "Amphitheatre Pkwy",
          "types": [
            "route"
          ],
          "languageCode": "en"
        },
        {
          "longText": "Mountain View",
          "shortText": "Mountain View",
          "types": [
            "locality",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "Santa Clara County",
          "shortText": "Santa Clara County",
          "types": [
            "administrative_area_level_2",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "California",
          "shortText": "CA",
          "types": [
            "administrative_area_level_1",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "United States",
          "shortText": "US",
          "types": [
            "country",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "94043",
          "shortText": "94043",
          "types": [
            "postal_code"
          ]
        },
        {
          "longText": "1351",
          "shortText": "1351",
          "types": [
            "postal_code_suffix"
          ]
        }
      ],
      "types": [
        "premise",
        "street_address"
      ]
    }
  ]
}

Solicitud y respuesta de geocodificación inversa (búsqueda de dirección)

En el siguiente ejemplo, se solicita la dirección correspondiente a una latitud y longitud dadas en Brooklyn, NY, EE.UU. Se especifica que la salida debe tener un formato JSON.

https://geocode.googleapis.com/v4/geocode/location/37.4225508,-122.0846338?key=YOUR_API_KEY

Para probar esto, ingresa la URL en tu navegador web (asegúrate de reemplazar "YOUR_API_KEY" por tu clave de API real). La respuesta incluye una dirección legible por humanos para la ubicación de latitud y longitud.

Consulta la guía para desarrolladores para obtener más información sobre cómo crear URLs de solicitud de geocodificación inversa, los parámetros disponibles y cómo interpretar la respuesta.

A continuación, se muestra un ejemplo de respuesta de geocodificación inversa, en JSON:

{
  "results": [
    {
      "place": "//places.googleapis.com/places/ChIJHRNUiQK6j4ARJ__Hrbt6qsE",
      "placeId": "ChIJHRNUiQK6j4ARJ__Hrbt6qsE",
      "location": {
        "latitude": 37.4225657,
        "longitude": -122.08465439999999
      },
      "granularity": "ROOFTOP",
      "viewport": {
        "low": {
          "latitude": 37.421214719708509,
          "longitude": -122.08603273029148
        },
        "high": {
          "latitude": 37.423912680291508,
          "longitude": -122.0833347697085
        }
      },
      "bounds": {
        "low": {
          "latitude": 37.4225178,
          "longitude": -122.08484599999998
        },
        "high": {
          "latitude": 37.422609600000008,
          "longitude": -122.0845215
        }
      },
      "formattedAddress": "Google Building 40, 1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
      "postalAddress": {
        "regionCode": "US",
        "languageCode": "en",
        "postalCode": "94043",
        "administrativeArea": "CA",
        "locality": "Mountain View",
        "addressLines": [
          "Google Building 40",
          "1600 Amphitheatre Pkwy"
        ]
      },
      "addressComponents": [
        {
          "longText": "Google Building 40",
          "shortText": "Google Building 40",
          "types": [
            "premise"
          ],
          "languageCode": "en"
        },
        {
          "longText": "1600",
          "shortText": "1600",
          "types": [
            "street_number"
          ]
        },
        {
          "longText": "Amphitheatre Parkway",
          "shortText": "Amphitheatre Pkwy",
          "types": [
            "route"
          ],
          "languageCode": "en"
        },
        {
          "longText": "Mountain View",
          "shortText": "Mountain View",
          "types": [
            "locality",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "Santa Clara County",
          "shortText": "Santa Clara County",
          "types": [
            "administrative_area_level_2",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "California",
          "shortText": "CA",
          "types": [
            "administrative_area_level_1",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "United States",
          "shortText": "US",
          "types": [
            "country",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "94043",
          "shortText": "94043",
          "types": [
            "postal_code"
          ]
        }
      ],
      "types": [
        "street_address",
        "subpremise"
      ]
    },
    ... Additional results truncated in this example[] ...
}

Autenticación, cuotas, precios y políticas

Autenticación

Para usar la API de Geocoding, primero debes habilitarla y obtener las credenciales de autenticación adecuadas. Para obtener más información, consulta Cómo comenzar a utilizar Google Maps Platform.

Cuotas y precios

Revisa la página de uso y facturación para obtener detalles sobre las cuotas y los precios establecidos para la API de Geocoding.

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 Visualiza y administra las cuotas y selecciona API de Geocoding como el servicio.

Advertencia: Debido a los riesgos de seguridad, no debes llamar a los métodos de la API de Geocoding v4 directamente desde JavaScript del cliente. Si lo haces en contra de las recomendaciones, ten en cuenta que solicitar cuotas más altas aumenta el impacto potencial del abuso de las claves de API. Consulta Consideraciones de seguridad.

Políticas

El uso de la API de Geocoding debe cumplir con las políticas de la API.