Geocodifica una dirección

Desarrolladores del Espacio Económico Europeo (EEE)

La geocodificación convierte una dirección en una ubicación en un mapa. Cuando codificas geográficamente una dirección, la respuesta contiene lo siguiente:

  • ID de lugar de la ubicación
  • Coordenadas de latitud y longitud de la ubicación
  • El código plus 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/v4beta/geocode/address/ADDRESS_STRING

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

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

Por lo general, se usa el formato estructurado cuando se procesan los componentes de dirección capturados en un formulario HTML.

Pasa todos los demás parámetros como parámetros de URL o, para 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 de Plus Code. Por ejemplo, el siguiente ejemplo pasa la cadena de dirección codificada como URL "1600 Amphitheatre Parkway, Mountain View, CA":

https://geocode.googleapis.com/v4beta/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/v4beta/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/v4beta/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 la URL con el signo "#" como %2FE:

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

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

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

Cómo pasar una dirección estructurada

Especifica una dirección estructurada con el parámetro de consulta address, del 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/v4beta/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/v4beta/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, el token de OAuth debe tener asignado el alcance correcto. La API de Geocoding admite los siguientes alcances para usar con el geocodificación directa:

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

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

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.

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: Es la dirección o el Plus Code que deseas geocodificar. Especifica las direcciones de acuerdo con el formato utilizado por el servicio nacional de correos 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 en %20. Por ejemplo, pasa la dirección "24 Sussex Drive Ottawa ON" de la siguiente manera: 
    24%20Sussex%20Drive%20Ottawa%20ON
     Formatea los códigos Plus como se muestra a continuación. Los signos más se codifican como URL en %2B y los espacios se codifican como URL en %20:
    • Un código global se compone de 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, USA" como CWC8%2BR9%20Mountain%20View%20CA%20USA.

Parámetros opcionales

  • locationBias

    Especifica un área de búsqueda como un objeto Viewport. Esta ubicación sirve como sesgo, lo que significa que se pueden devolver resultados alrededor de la ubicación especificada, incluidos los resultados cerca del área, pero fuera de ella.

    Especifica la región como un Viewport rectangular. Un rectángulo es una ventana gráfica de latitud y longitud, representada como dos puntos bajos y altos diagonalmente opuestos. 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 entre -90 y 90 grados inclusive, y los límites de longitud deben estar 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, la ventana gráfica 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 completar 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 una ventana gráfica 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

    Idioma en el que se mostrarán los resultados.

    • Consulta la lista de idiomas admitidos. Google actualiza con frecuencia los idiomas admitidos, por lo que es posible que esta lista no sea exhaustiva.
    • Si no se proporciona languageCode, la API usará en de forma predeterminada. Si especificas un código de idioma no válido, la API devuelve 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 de calles en el idioma local, transliteradas a un alfabeto legible para el usuario si es necesario, y observa 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 un nombre no está 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 devolver y en el orden en que se devuelven. 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 de 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.

Ajuste de la ubicación

Usa el parámetro locationBias para indicarle al servicio Geocoding que anteponga 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 suroeste y noreste de este cuadro delimitador.

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

https://geocode.googleapis.com/v4beta/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 se agrega un parámetro locationBias que define un cuadro delimitador alrededor de la parte noreste de EE.UU., este geocódigo solo devolverá la ciudad de Washington D.C.:

https://geocode.googleapis.com/v4beta/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 la región

En una solicitud de geocodificación, puedes indicarle al servicio Geocoding que muestre 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 el sesgo regional. La mayoría de los códigos de CLDR son idénticos a los códigos de 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/v4beta/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/v4beta/geocode/address/Toledo?regionCode=es&key=API_KEY