Geocodifica una dirección

Desarrolladores del Espacio Económico Europeo (EEE)

La geocodificación traduce una dirección en una ubicación en un mapa. Cuando geocodificas una dirección, la respuesta contiene lo siguiente:

  • Es el ID de lugar de la ubicación.
  • Coordenadas de latitud y longitud de la ubicación
  • El Plus Code de la ubicación
  • Detalles de la dirección expandidos

Solicitud de geocodificación

Una solicitud de geocodificación es una solicitud HTTP GET. Puedes especificar la dirección como una cadena no estructurada:

https://geocode.googleapis.com/v4/geocode/address/ADDRESS_STRING

O como un conjunto estructurado de componentes de dirección representados por parámetros de consulta:

https://geocode.googleapis.com/v4/geocode/address?STRUCTURED_ADDRESS

Por lo general, usas el formato estructurado cuando procesas componentes de dirección capturados en un formulario HTML.

Pasa todos los demás parámetros como parámetros de URL o, en el caso de parámetros como la clave de API y la máscara de campo, en encabezados como parte de la solicitud GET.

Pasa una cadena de dirección no estructurada

Una dirección no estructurada es una dirección con formato de cadena o un Plus Code. La geocodificación de direcciones no resuelve las coordenadas de latitud y longitud, ni otras cadenas no estructuradas que no representen una dirección o un Plus Code. No se admiten las solicitudes que usan esas cadenas y pueden generar respuestas de error o un comportamiento no especificado. Estos son algunos ejemplos de consultas no admitidas:

Tipo de consulta Ejemplo
Coordenadas de latitud y longitud En su lugar, usa la geocodificación inversa. "37.422131,-122.084801"
Demasiados conceptos o restricciones, como los nombres de varios lugares, rutas o ciudades en una sola búsqueda "Market Street San Francisco San Jose Airport"
Elementos de la dirección postal que no se representan en Google Maps "C/O John Smith 123 Main Street"
"P.O. Box 13 San Francisco"
Nombres de empresas, cadenas o categorías combinados con ubicaciones en las que estas entidades no están disponibles "Tesco cerca de Dallas, Texas"
Consultas ambiguas con varias interpretaciones "Charger drop-off"
Nombres históricos que ya no se usan "Middlesex, Reino Unido"
Elementos o intención no geoespaciales "¿Cuántos barcos hay en el puerto de Ventura?"
Nombres no oficiales o personalizados "The Jenga"
"The Helter Skelter"

Por ejemplo, en el siguiente ejemplo, se pasa la cadena de dirección codificada en URL "1600 Amphitheatre Parkway, Mountain View, CA":

https://geocode.googleapis.com/v4/geocode/address/1600+Amphitheatre+Parkway,+Mountain+View,+CA?key=API_KEY

Observa que el carácter "+" de la URL se convierte en un espacio.

También puedes realizar la solicitud con un comando curl:

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

Las direcciones pueden contener muchos tipos de caracteres especiales. Por ejemplo, una "/" como en "7/1 King St, Concord West". Codifica la URL "/" como %2F:

https://geocode.googleapis.com/v4/geocode/address/7%2F1+King+St,+Concord+West
?key=API_KEY

Otro ejemplo común es el carácter "#", como en "9500 W Bryn Mawr Ave #650, Rosemont". Codifica el carácter "#" en la URL como %2FE:

https://geocode.googleapis.com/v4/geocode/address/9500+W+Bryn+Mawr+Ave+%23650,+Rosemont?key=API_KEY

En el siguiente ejemplo, especificas una cadena de dirección no estructurada como el Plus Code 849VCWC8+R4. Asegúrate de codificar en formato de URL el carácter "+" como %2B:

https://geocode.googleapis.com/v4/geocode/address/849VCWC8%2BR4?key=API_KEY

Pasa una dirección estructurada

Especifica una dirección estructurada con el parámetro de consulta address, de tipo PostalAddress. El objeto PostalAddress te permite especificar algunos o todos los componentes de la dirección en la solicitud como parámetros de consulta individuales.

Por ejemplo, para especificar solo el código postal de la dirección, usa PostalAddress.postalCode:

https://geocode.googleapis.com/v4/geocode/address?address.postalCode=01062&key=API_KEY

Para especificar varios componentes de dirección, como los que se capturan en un formulario HTML, usa varios parámetros de consulta:

https://geocode.googleapis.com/v4/geocode/address?address.addressLines=1600+Amphithreater+Pkwy&address.locality=Mountain+View&address.administrativeArea=CA&key=API_KEY

Usa OAuth para realizar una solicitud

La API de Geocoding v4 admite OAuth 2.0 para la autenticación. Para usar OAuth con la API de Geocoding, se debe asignar el permiso correcto al token de OAuth. La API de Geocoding admite los siguientes permisos para usar con la geocodificación directa:

  • https://www.googleapis.com/auth/maps-platform.geocode — Se usa con todos los métodos de la API de Geocoding.
  • https://www.googleapis.com/auth/maps-platform.geocode.address — Se usa solo con GeocodeAddress para la geocodificación directa.

Además, puedes usar el permiso general https://www.googleapis.com/auth/cloud-platform para todos los métodos de la API de Geocoding. Ese permiso es útil durante el desarrollo, pero no en producción, ya que es un permiso general que permite el acceso a todos los métodos.

Para obtener más información y ejemplos, consulta Usa OAuth.

Respuesta de geocodificación

La geocodificación devuelve un objeto GeocodeAddressResponse que contiene el array results de objetos GeocodeResult. Cada objeto GeocodeResult representa un solo lugar.

Las respuestas de la API de Geocoding incluyen arrays types en dos lugares principales dentro de GeocodeResult:

  1. GeocodeResult.types: Este array indica los tipos generales del resultado. Los valores posibles se extraen de los tipos de lugares que usa la API de Places. Para obtener más información, consulta las tablas A y B de tipos de lugares.
  2. GeocodeResult.addressComponents[].types: Cada componente de dirección tiene un array types que indica el tipo de esa parte específica de la dirección. Estos valores se extraen de la tabla Tipos de dirección y tipos de componentes de dirección que usa la API de Places.

El objeto JSON completo tiene el siguiente formato:

{
  "results": [
    {
      "place": "//places.googleapis.com/places/ChIJF4Yf2Ry7j4AR__1AkytDyAE",
      "placeId": "ChIJF4Yf2Ry7j4AR__1AkytDyAE",
      "location": {
        "latitude": 37.422010799999995,
        "longitude": -122.08474779999999
      },
      "granularity": "ROOFTOP",
      "viewport": {
        "low": {
          "latitude": 37.420656719708511,
          "longitude": -122.08547523029148
        },
        "high": {
          "latitude": 37.4233546802915,
          "longitude": -122.0827772697085
        }
      },
      "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
      "postalAddress": {
        "regionCode": "US",
        "languageCode": "en",
        "postalCode": "94043",
        "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"
        },
        ...
      ],
      "types": [
        "street_address"
      ],
      "plusCode": {
        "globalCode": "849VCWC8+R4",
        "compoundCode": "CWC8+R4 Mountain View, CA, USA"
      }
    }
  ]
}

Parámetros obligatorios

  • address: Indica la dirección o el Plus Code que deseas geocodificar. Nota: La geocodificación de direcciones no resuelve las coordenadas de latitud y longitud ni otras cadenas no estructuradas que no representen una dirección o un Plus Code. Consulta Cómo pasar una cadena de dirección no estructurada para obtener más detalles y ejemplos de consultas no admitidas. Especifica las direcciones de acuerdo con el formato que usa el servicio postal nacional del país en cuestión. Se deben evitar los elementos de dirección adicionales, como los nombres de las empresas y los números de unidad, suite o piso. Los elementos de la dirección deben estar delimitados por espacios codificados como URL como %20. Por ejemplo, pasa la dirección "24 Sussex Drive Ottawa ON" de la siguiente manera: 
    24%20Sussex%20Drive%20Ottawa%20ON
     Asigna el formato que se muestra a continuación a los Plus Codes. Los signos más se codifican como %2B y los espacios, como %20:
    • Un código global es un código de área de 4 caracteres y un código local de 6 caracteres o más. Por ejemplo, codifica "849VCWC8+R9" como 849VCWC8%2BR9.
    • Un código compuesto es un código local de 6 caracteres o más con una ubicación explícita. Por ejemplo, codifica "CWC8+R9 Mountain View, CA, EE.UU." como CWC8%2BR9%20Mountain%20View%20CA%20USA.

Parámetros opcionales

  • locationBias

    Especifica un área para buscar como un Viewport. Esta ubicación funciona como un sesgo, lo que significa que se pueden mostrar resultados alrededor de la ubicación especificada, incluidos los resultados cercanos, pero fuera del área.

    Especifica la región como un Viewport rectangular. Un rectángulo es un viewport de latitud y longitud, representado como dos puntos diagonalmente opuestos, uno bajo y otro alto. El punto bajo marca la esquina suroeste del rectángulo, y el punto alto representa la esquina noreste del rectángulo.

    Un viewport se considera una región cerrada, lo que significa que incluye su límite. Los límites de latitud deben estar comprendidos entre -90 y 90 grados, inclusive, y los límites de longitud deben estar comprendidos entre -180 y 180 grados, inclusive:

    • Si low = high, el viewport consta de ese único punto.
    • Si low.longitude > high.longitude, el rango de longitud se invierte (el viewport cruza la línea de longitud de 180 grados).
    • Si low.longitude = -180 grados y high.longitude = 180 grados, el viewport incluye todas las longitudes.
    • Si low.longitude = 180 grados y high.longitude = -180 grados, el rango de longitud está vacío.
    • Si low.latitude > high.latitude, el rango de latitud está vacío.

    Se deben propagar los valores bajo y alto, y el cuadro representado no puede estar vacío. Un viewport vacío genera un error.

    Por ejemplo, esta cadena de consulta define un viewport que encierra por completo la ciudad de Nueva York:

    ?locationBias.rectangle.low.latitude=40.477398&locationBias.rectangle.low.longitude=-74.259087&locationBias.rectangle.high.latitude=40.91618&locationBias.rectangle.high.longitude=-73.70018

  • languageCode

    Es el idioma en el que se devolverán los resultados.

    • Consulta la lista de idiomas disponibles. Google suele actualizar los idiomas admitidos, por lo que es posible que esta lista no sea exhaustiva.
    • Si no se proporciona languageCode, la API usa de forma predeterminada el idioma y la escritura locales de la ubicación. Si especificas un código de idioma no válido, la API mostrará un error INVALID_ARGUMENT.
    • La API hace todo lo posible para proporcionar una dirección que sea legible tanto para el usuario como para los residentes locales. Para lograr ese objetivo, devuelve direcciones en el idioma local, transliteradas a una escritura legible por el usuario si es necesario, respetando el idioma preferido. Todas las demás direcciones se devuelven en el idioma preferido. Todos los componentes de la dirección se devuelven en el mismo idioma, que se elige a partir del primer componente.
    • Si no hay un nombre disponible en el idioma preferido, la API usa la coincidencia más cercana.
    • El idioma preferido tiene una pequeña influencia en el conjunto de resultados que la API elige mostrar y en el orden en que se muestran. El geocodificador interpreta las abreviaturas de manera diferente según el idioma, como las abreviaturas de los tipos de calles o los sinónimos que pueden ser válidos en un idioma, pero no en otro.

  • regionCode

    Es el código de región como un valor de código CLDR de dos caracteres. No hay un valor predeterminado. La mayoría de los códigos CLDR son idénticos a los códigos ISO 3166-1.

    Cuando se geocodifica una dirección, geocodificación directa, este parámetro puede influir en los resultados del servicio para la región especificada, pero no los restringe por completo. Cuando se geocodifica una ubicación o un lugar, ya sea con la geocodificación inversa o la geocodificación de lugares, este parámetro se puede usar para dar formato a la dirección. En todos los casos, este parámetro puede afectar los resultados según la legislación aplicable.

  • FieldMask

    Crea una máscara de campo de respuesta para especificar los campos que se deben devolver en la respuesta. Pasa la máscara de campo de respuesta al método con el parámetro de URL $fields o fields, o con el encabezado HTTP X-Goog-FieldMask. Por ejemplo, la siguiente solicitud solo devolverá el campo placeID de la respuesta.

    curl -X GET -H 'Content-Type: application/json' \
-H 'X-Goog-FieldMask: results.placeId' \
-H "X-Goog-Api-Key: API_KEY" \
https://geocode.googleapis.com/v4/geocode/address/1600+Amphitheatre+Parkway,+Mountain+View,+CA
    La respuesta es la siguiente: 
    {
  "results": [
    {
      "placeId": "ChIJiSSC8QK6j4AR98Thup8mqTc"
    }
  ]
}

    Consulta Elige los campos que se mostrarán para obtener más detalles.

  • esfuerzo

    Experimental: El parámetro effort es experimental. Forma solicitudes HTTP con el canal /v4alpha/. Más información sobre los canales de etapas de lanzamiento.

    Especifica la cantidad de procesamiento Effort que se aplicará cuando se resuelva la dirección. Esto te permite controlar la compensación entre la velocidad de respuesta y la exactitud de la resolución de direcciones:

    • EFFORT_UNSPECIFIED: Es el valor predeterminado. Se comporta de la misma manera que el esfuerzo LOW.
    • LOW: Optimiza para obtener los tiempos de respuesta más rápidos. No realiza búsquedas extendidas ni elimina ambigüedades en direcciones difíciles.
    • MEDIUM: Equilibra la velocidad y la precisión. La mayoría de las solicitudes se devuelven con una latencia baja estándar. En el caso de direcciones ambiguas o difíciles, el servicio aplica un procesamiento adicional para mejorar la precisión, lo que puede tardar hasta unos segundos. Se recomienda para flujos de trabajo interactivos en los que los usuarios pueden tolerar una breve pausa.
    • HIGH: Maximiza la exactitud de la resolución de direcciones para direcciones incompletas, informales o complejas. Los tiempos de respuesta pueden ser mucho más largos. Se recomienda para flujos de trabajo de envío de logística, por lotes o en segundo plano.

    Por ejemplo, en la siguiente solicitud, se usa effort=MEDIUM:

    curl -X GET -H 'Content-Type: application/json' \
-H "X-Goog-Api-Key: API_KEY" \
"https://geocode.googleapis.com/v4alpha/geocode/address/where+the+warriors+play,+sf?effort=MEDIUM"

    Consulta Geocodifica con mayor exactitud para obtener más detalles sobre las expectativas de latencia, los límites de frecuencia y los patrones de integración recomendados.

Sesgo de ubicación

Usa el parámetro locationBias para indicarle al servicio de Geocoding que priorice los resultados dentro de un viewport determinado (expresado como un cuadro delimitador). El parámetro locationBias define las coordenadas de latitud y longitud de las esquinas sudoeste y noreste de este cuadro delimitador.

Por ejemplo, una solicitud de geocodificación para la dirección "Washington" puede devolver resultados para Washington, D.C. y para el estado de Washington, EE.UU.:

https://geocode.googleapis.com/v4/geocode/address/Washington?key=API_KEY

La respuesta tiene el siguiente formato:

{
  "results": [
    {
      "place": "//places.googleapis.com/places/ChIJW-T2Wt7Gt4kRKl2I1CJFUsI",
      "placeId": "ChIJW-T2Wt7Gt4kRKl2I1CJFUsI",
      "location": {
        "latitude": 38.9071923,
        "longitude": -77.0368707
      },
      "granularity": "APPROXIMATE",
      "viewport": {
        "low": {
          "latitude": 38.7916449,
          "longitude": -77.119759
        },
        "high": {
          "latitude": 38.9958641,
          "longitude": -76.909393
        }
      },
      "bounds": {
        "low": {
          "latitude": 38.7916449,
          "longitude": -77.119759
        },
        "high": {
          "latitude": 38.9958641,
          "longitude": -76.909393
        }
      },
      "formattedAddress": "Washington, DC, USA",
      "addressComponents": [
        {
          "longText": "Washington",
          "shortText": "Washington",
          "types": [
            "locality",
            "political"
          ],
          "languageCode": "en"
        },
        ...
      ],
      "types": [
        "locality",
        "political"
      ]
    },
    {
      "place": "//places.googleapis.com/places/ChIJ-bDD5__lhVQRuvNfbGh4QpQ",
      "placeId": "ChIJ-bDD5__lhVQRuvNfbGh4QpQ",
      "location": {
        "latitude": 47.7510741,
        "longitude": -120.7401386
      },
      "granularity": "APPROXIMATE",
      "viewport": {
        "low": {
          "latitude": 45.543541,
          "longitude": -124.84897389999999
        },
        "high": {
          "latitude": 49.0024945,
          "longitude": -116.91607109999998
        }
      },
      "bounds": {
        "low": {
          "latitude": 45.543541,
          "longitude": -124.84897389999999
        },
        "high": {
          "latitude": 49.0024442,
          "longitude": -116.91607109999998
        }
      },
      "formattedAddress": "Washington, USA",
      "addressComponents": [
        {
          "longText": "Washington",
          "shortText": "WA",
          "types": [
            "administrative_area_level_1",
            "political"
          ],
          "languageCode": "en"
        },
      ...
      ],
      "types": [
        "administrative_area_level_1",
        "political"
      ]
    }
  ]
}

Sin embargo, si agregas un parámetro locationBias que defina un cuadro delimitador alrededor de la parte noreste de EE.UU., se obtiene como resultado un geocódigo que muestra solo la ciudad de Washington, D.C.:

https://geocode.googleapis.com/v4/geocode/address/Washington?locationBias.rectangle.low.latitude=36.47&locationBias.rectangle.low.longitude=-84.72&locationBias.rectangle.high.latitude=43.39&locationBias.rectangle.high.longitude=-65.90&key=API_KEY

Personalización de regiones

En una solicitud de geocodificación, puedes indicar al servicio Geocoding que devuelva resultados personalizados para una región en particular con el parámetro regionCode. Este parámetro toma un valor de código CLDR de dos caracteres que especifica la preferencia de región. La mayoría de los códigos CLDR son idénticos a los códigos ISO 3166-1.

No hay un valor predeterminado para regionCode. Por ejemplo, un geocódigo de "Toledo" devuelve resultados para EE.UU. y España:

https://geocode.googleapis.com/v4/geocode/address/Toledo?key=API_KEY

Respuesta:

{
  "results": [
    {
      "place": "//places.googleapis.com/places/ChIJeU4e_C2HO4gRRcM6RZ_IPHw",
      "placeId": "ChIJeU4e_C2HO4gRRcM6RZ_IPHw",
      "location": {
        "latitude": 41.652805199999996,
        "longitude": -83.5378674
      },
      "granularity": "APPROXIMATE",
      "viewport": {
        "low": {
          "latitude": 41.579513,
          "longitude": -83.6944089
        },
        "high": {
          "latitude": 41.733036,
          "longitude": -83.4493851
        }
      },
      "bounds": {
        "low": {
          "latitude": 41.579513,
          "longitude": -83.6944089
        },
        "high": {
          "latitude": 41.733036,
          "longitude": -83.4493851
        }
      },
      "formattedAddress": "Toledo, OH, USA",
      "addressComponents": [
        {
          "longText": "Toledo",
          "shortText": "Toledo",
          "types": [
            "locality",
            "political"
          ],
          "languageCode": "en"
        },
        ...
      ],
      "types": [
        "locality",
        "political"
      ]
    },
    {
      "place": "//places.googleapis.com/places/ChIJkwyrlqwLag0RiQIn2fdIshM",
      "placeId": "ChIJkwyrlqwLag0RiQIn2fdIshM",
      "location": {
        "latitude": 39.8628296,
        "longitude": -4.0273067
      },
      "granularity": "APPROXIMATE",
      "viewport": {
        "low": {
          "latitude": 39.8116682,
          "longitude": -4.179933
        },
        "high": {
          "latitude": 39.9251319,
          "longitude": -3.8148935
        }
      },
      "bounds": {
        "low": {
          "latitude": 39.8116682,
          "longitude": -4.179933
        },
        "high": {
          "latitude": 39.9251319,
          "longitude": -3.8148935
        }
      },
      "formattedAddress": "Toledo, España",
      "addressComponents": [
        {
          "longText": "Toledo",
          "shortText": "Toledo",
          "types": [
            "administrative_area_level_4",
            "political"
          ],
          "languageCode": "es"
        },
        ...
      ],
      "types": [
        "administrative_area_level_4",
        "political"
      ]
    },
    ...
  ]
}

Una solicitud de geocodificación para "Toledo" con regionCode=es (España) solo devuelve resultados de España:

https://geocode.googleapis.com/v4/geocode/address/Toledo?regionCode=es&key=API_KEY