Cómo revertir la geocodificación de una ubicación

Desarrolladores del Espacio Económico Europeo (EEE)

La geocodificación inversa traduce una ubicación en el mapa en una dirección legible por humanos. Representas la ubicación del mapa con las coordenadas de latitud y longitud de la ubicación.

Cuando realizas la geocodificación inversa de una ubicación, la respuesta contiene lo siguiente:

Esta API devuelve diferentes tipos de direcciones, desde la dirección más específica hasta entidades políticas menos específicas, como vecindarios, ciudades, condados y estados. La dirección más exacta suele ser el primer resultado. Si deseas que coincida con un tipo específico de dirección, usa el parámetro types.

Solicitud de geocodificación inversa

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

https://geocode.googleapis.com/v4/geocode/location/LATITUDE,LONGITUDE

O como un conjunto estructurado de coordenadas de latitud y longitud representadas por parámetros de consulta:

https://geocode.googleapis.com/v4/geocode/location?location.latitude=LATITUDE&location.longitude=LONGITUDE

Por lo general, usas el formato estructurado cuando procesas componentes de ubicació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 o la máscara de campo, en encabezados como parte de la solicitud GET. Por ejemplo:

Pasa una cadena de ubicación no estructurada

Una ubicación no estructurada es una ubicación con formato de cadena de coordenadas de latitud y longitud separadas por comas:

https://geocode.googleapis.com/v4/geocode/location/37.4225508,-122.0846338?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/location/37.4225508,-122.0846338"

Cómo pasar una ubicación estructurada

Especifica la ubicación estructurada con el parámetro de consulta location, de tipo LatLng. El objeto LatLng te permite especificar la latitud y la longitud como parámetros de consulta independientes:

https://geocode.googleapis.com/v4/geocode/location?location.latitude=37.4225508&location.longitude=-122.0846338&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 inversa:

  • 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.location: Se usa solo con GeocodeLocation para la geocodificación inversa.

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 la 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 inversa

La geocodificación inversa devuelve un objeto GeocodeLocationResponse que contiene lo siguiente:

  • Es el array results de objetos GeocodeResult que representa el 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 geocodificador inverso devuelve más de un resultado en el array results. Los resultados no solo representan direcciones postales, sino que permiten hacer referencia a cualquier ubicación geográfica. Por ejemplo, cuando se geocodifica un punto en la ciudad de Chicago, dicha ubicación puede etiquetarse como una dirección, como una ciudad (Chicago), como un estado (Illinois) o como un país (Estados Unidos). Todas son "direcciones" para el geocodificador. El geocodificador inverso devuelve cualquiera de estos tipos como resultados válidos.

  • El campo plusCode, de tipo PlusCode, contiene el Plus Code que mejor se aproxima a la latitud y la longitud de la solicitud. Además, cada elemento del array results contiene un Plus Code. La distancia entre el Plus Code decodificado y el punto de solicitud es inferior a 10 metros.

    Nota: La API no siempre devuelve Plus Codes.

El objeto JSON completo tiene el siguiente formato:

{
  "results": [
    {
      "place": "//places.googleapis.com/places/ChIJV-FZF7i7j4ARo4ZOUoecZFU",
      "placeId": "ChIJV-FZF7i7j4ARo4ZOUoecZFU",
      "location": {
        "latitude": 37.422588300000008,
        "longitude": -122.0846489
      },
      "granularity": "ROOFTOP",
      "viewport": {
        "low": {
          "latitude": 37.421239319708512,
          "longitude": -122.0859978802915
        },
        "high": {
          "latitude": 37.423937280291511,
          "longitude": -122.08329991970851
        }
      },
      "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
      "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": [
        "street_address"
      ],
      "plusCode": {
        "globalCode": "849VCW83+PM",
        "compoundCode": "CW83+PM Mountain View, CA, USA"
      }
    },
    {
      "place": "//places.googleapis.com/places/ChIJj61dQgK6j4AR4GeTYWZsKWw",
      "placeId": "ChIJj61dQgK6j4AR4GeTYWZsKWw",
      "location": {
        "latitude": 37.4220541,
        "longitude": -122.08532419999999
      },
      "granularity": "ROOFTOP",
      "viewport": {
        "low": {
          "latitude": 37.4207051197085,
          "longitude": -122.08667318029148
        },
        "high": {
          "latitude": 37.423403080291493,
          "longitude": -122.08397521970851
        }
      },
      "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
      "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"
      ],
      "plusCode": {
        "globalCode": "849VCWC7+RV",
        "compoundCode": "CWC7+RV Mountain View, CA, USA"
      }
    },
   ...
  ],
  "plusCode": {
    "globalCode": "849VCWF8+24H",
    "compoundCode": "CWF8+24H Mountain View, CA, USA"
  }
}

Parámetros obligatorios

  • ubicación

    Son las coordenadas de latitud y longitud que especifican dónde deseas obtener la dirección más cercana legible por humanos.

Parámetros opcionales

  • 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.

  • nivel de detalle

    Uno o más niveles de detalle de la ubicación, especificados como parámetros de consulta independientes, según lo define Granularity. Si especificas varios parámetros granularity, la API devuelve todas las direcciones que coinciden con cualquiera de los niveles de detalle.

    El parámetro granularity no restringe la búsqueda a los niveles de detalle de ubicación especificados. En cambio, granularity actúa como un filtro posterior a la búsqueda. La API recupera todos los resultados para el location especificado y, luego, descarta aquellos que no coinciden con los niveles de detalle de ubicación especificados.

    Si especificas types y granularity, la API solo devuelve los resultados que coinciden con ambos. Por ejemplo:

    https://geocode.googleapis.com/v4/geocode/location/37.4225508,-122.0846338?granularity=ROOFTOP&granularity=GEOMETRIC_CENTER&key=API_KEY

  • máquinas activas

    Uno o más tipos de direcciones, especificados como parámetros de consulta independientes. Los valores posibles se extraen de la tabla Tipos de dirección y tipos de componentes de dirección de la página Tipos de lugar (nueva). Si especificas varios parámetros types, la API devuelve todas las direcciones que coinciden con cualquiera de los tipos.

    El parámetro types no restringe la búsqueda a los tipos de direcciones especificados. En cambio, types actúa como un filtro posterior a la búsqueda. La API recupera todos los resultados de la ubicación especificada y, luego, descarta aquellos que no coinciden con los tipos de dirección especificados.

    Si especificas types y granularity, la API solo devuelve los resultados que coinciden con ambos. Por ejemplo:

    https://geocode.googleapis.com/v4/geocode/location/37.4225508,-122.0846338?types=administrative_area_level_2&types=locality&key=API_KEY

  • 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á los campos 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/location/37.4225508,-122.0846338"
    La respuesta es la siguiente: 
    {
  "results": [
    {
      "placeId": "ChIJHRNUiQK6j4ARJ__Hrbt6qsE"
    },
    {
      "placeId": "ChIJj38IfwK6j4ARNcyPDnEGa9g"
    },
    {
      "placeId": "ChIJ1yjFJ1-7j4ARG_RVqFD1h7k"
    },
    {
      "placeId": "ChIJ09H2YwK6j4ARoF7qfCBxhB8"
    },
    ...
  ]
}

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