Cómo geocodificar un lugar

Desarrolladores del Espacio Económico Europeo (EEE)

La geocodificación de lugares te permite recuperar una dirección a partir de un ID de lugar.

Los IDs de lugar identifican de forma única un lugar en la base de datos de Google Places y en Google Maps. Recupera los IDs de lugar cuando geocodificas una dirección. También puedes recuperar un ID de lugar de muchas otras APIs, como Place Details (nuevo), Text Search (nuevo) y Nearby Search (nuevo).

Solicitudes de codificación geográfica de lugares

Una solicitud de place geocoding es una solicitud HTTP GET con el siguiente formato:

https://geocode.googleapis.com/v4/geocode/places/PLACE_ID

Aquí, PLACE_ID contiene el ID del lugar de la ubicación de interés.

Pasa todos los demás parámetros como parámetros de URL o, para parámetros como la clave de API o la máscara de campo, en encabezados como parte de la solicitud GET. Por ejemplo:

https://geocode.googleapis.com/v4/geocode/places/ChIJj61dQgK6j4AR4GeTYWZsKWw?key=API_KEY

O en un comando curl:

curl -X GET -H 'Content-Type: application/json' \
-H "X-Goog-Api-Key: API_KEY" \
"https://geocode.googleapis.com/v4/geocode/places/ChIJj61dQgK6j4AR4GeTYWZsKWw"

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 permiso correcto. La API de Geocoding admite los siguientes alcances para usar con la geocodificación de lugares:

  • 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.place — Úsalo solo con GeocodePlace para la geocodificación de lugares.

También puedes usar el alcance general https://www.googleapis.com/auth/cloud-platform para todos los métodos de la API de Geocoding. Este 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 métodos.

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

Respuestas de codificación geográfica de lugares

La geocodificación de lugares devuelve un objeto GeocodeResult que representa el lugar correspondiente al ID de 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 las tablas A y B de la página Place Types (nuevo).
  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 en la página Tipos de lugar (nuevo).

El objeto JSON completo tiene el siguiente formato:

{
  "place": "//places.googleapis.com/places/ChIJj61dQgK6j4AR4GeTYWZsKWw",
  "placeId": "ChIJj61dQgK6j4AR4GeTYWZsKWw",
  "location": {
    "latitude": 37.4220541,
    "longitude": -122.08532419999999
  },
  "granularity": "ROOFTOP",
  "viewport": {
    "low": {
      "latitude": 37.4209489697085,
      "longitude": -122.08846930000001
    },
    "high": {
      "latitude": 37.4236469302915,
      "longitude": -122.0829156
    }
  },
  "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"
    },
    {
      "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": [
    "establishment",
    "point_of_interest"
  ]
}

Parámetros obligatorios

  • place: Es el ID del lugar para el que deseas obtener la dirección legible por humanos. El ID de lugar es un identificador único que se puede usar con otras APIs de Google. Por ejemplo, puedes usar el placeID que devuelve la API de Roads para obtener la dirección de un punto ajustado. Para obtener más información sobre los IDs de lugar, consulta IDs de lugar.

Parámetros opcionales

  • languageCode

    Es el 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 una escritura 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 regional 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.

  • FieldMask

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

    curl -X GET -H 'Content-Type: application/json' \
-H 'X-Goog-FieldMask: formattedAddress' \
-H "X-Goog-Api-Key: API_KEY" \
"https://geocode.googleapis.com/v4/geocode/places/ChIJj61dQgK6j4AR4GeTYWZsKWw"
    La respuesta es: 
    {
  "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA"
}

    Consulta Cómo elegir los campos que se mostrarán para obtener más detalles.