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

Desarrolladores del Espacio Económico Europeo (EEE)

La geocodificación inversa convierte una ubicación del mapa en una dirección legible por humanos. La ubicación del mapa se representa con las coordenadas de latitud y longitud de la ubicación.

Cuando geocodificas una ubicación de forma inversa, la respuesta contiene lo siguiente:

Esta API muestra 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. Por lo general, la dirección más exacta es el primer resultado. Si deseas buscar coincidencias con un tipo específico de dirección, usa el types parámetro.

Solicitud de geocodificación inversa

Una solicitud de geocodificación inversa es una solicitud HTTP GET. 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 búsqueda:

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

Por lo general, se usa el formato estructurado cuando se procesan los 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 los encabezados como parte de la solicitud GET. Por ejemplo:

Cómo pasar una cadena de ubicación no estructurada

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

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

Para especificar la ubicación estructurada, usa el location parámetro de búsqueda, de tipo LatLng. El objeto LatLng te permite especificar la latitud y la longitud como parámetros de búsqueda separados:

https://geocode.googleapis.com/v4/geocode/location?location.latitude=37.4225508&location.longitude=-122.0846338&key=API_KEY

Cómo usar 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 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 alcance general https://www.googleapis.com/auth/cloud-platform para todos los métodos 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 métodos.

Para obtener más información y ejemplos, consulta Cómo usar OAuth.

Respuesta de geocodificación inversa

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

  • El array results de GeocodeResult objetos que representa el lugar.

    El geocodificador inverso muestra 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 las direcciones corresponden al geocodificador. El geocodificador inverso muestra 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.

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

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

Parámetros opcionales

  • languageCode

    El idioma en el que se muestran los resultados.

    • Consulta la lista de idiomas disponibles. Google actualiza con frecuencia los idiomas admitidos, por lo que es posible que esta lista no sea completa.
    • Si no se proporciona languageCode, la API usa en de forma predeterminada. Si especificas un código de idioma no válido, la API muestra un INVALID_ARGUMENT error.
    • La API hace todo lo posible para proporcionar una dirección que sea legible para el usuario y los habitantes locales. Para lograr ese objetivo, muestra direcciones en el idioma local, transliteradas a una secuencia de comandos legible por el usuario si es necesario, respetando el idioma preferido. Todas las demás direcciones se muestran en el idioma preferido. Todos los componentes de la dirección se muestran en el mismo idioma, que se elige 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 mostrar y 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

    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, geocodificación inversa o 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 ley aplicable.

  • nivel de detalle

    Uno o más niveles de detalle de la ubicación, especificados como parámetros de búsqueda separados, según lo define Granularity. Si especificas varios parámetros granularity, la API muestra 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 la ubicación especificados. En cambio, granularity actúa como un filtro posterior a la búsqueda. La API recupera todos los resultados para la location especificada y, luego, descarta los resultados que no coinciden con los niveles de detalle de la ubicación especificados.

    Si especificas types y granularity, la API muestra solo 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 búsqueda separados. Si especificas varios types parámetros, la API muestra 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 para la ubicación especificada y, luego, descarta los resultados que no coinciden con los tipos de direcciones especificados.

    Si especificas types y granularity, la API muestra solo 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

    Se admiten los siguientes valores:

    Tipos de dirección y tipos de componentes de dirección

    El array types en el cuerpo GeocodeResult de la respuesta indica el tipo de dirección. Algunos ejemplos de tipos de direcciones incluyen una dirección, un país o una entidad política. El types array en el AddressComponents campo del GeocodeResult cuerpo indica el tipo de cada parte de la dirección. Los ejemplos incluyen el número de una calle o el país.

    Las direcciones pueden tener múltiples tipos. Los tipos se pueden considerar "etiquetas". Por ejemplo, muchas ciudades están etiquetadas con los tipos political y locality.

    Se admiten y muestran los siguientes tipos en los arrays de tipo de dirección y tipo de componente de dirección:

    Tipo de dirección Descripción
    street_address Una dirección precisa.
    route Una ruta designada (como "US 101").
    intersection Una intersección principal, generalmente de dos rutas principales.
    political Una entidad política. Generalmente, este tipo indica un polígono de alguna administración pública.
    country Indica la entidad política nacional y, por lo general, es el tipo de orden más alto que muestra el geocodificador.
    administrative_area_level_1 Indica una entidad pública de primer orden por debajo del nivel de país. En Estados Unidos, estos niveles administrativos son los estados. No todos los países poseen estos niveles administrativos. En la mayoría de los casos, los nombres cortos de administrative_area_level_1 coincidirán considerablemente con las subdivisiones de ISO 3166-2 y otras listas conocidas; sin embargo, no podemos garantizarlo debido a que nuestros resultados de geocodificación se basan en diferentes indicadores y datos de ubicación.
    administrative_area_level_2 Indica una entidad pública de segundo orden por debajo del nivel de país. En Estados Unidos, estos niveles administrativos son los condados. No todos los países poseen estos niveles administrativos.
    administrative_area_level_3 Indica una entidad civil de tercer rango por debajo del nivel de país. Este tipo indica una división política inferior. No todos los países poseen estos niveles administrativos.
    administrative_area_level_4 Indica una entidad civil de cuarto rango por debajo del nivel de país. Este tipo indica una división política inferior. No todos los países poseen estos niveles administrativos.
    administrative_area_level_5 Indica una entidad civil de quinto rango por debajo del nivel de país. Este tipo indica una división política inferior. No todos los países poseen estos niveles administrativos.
    administrative_area_level_6 Indica una entidad civil de sexto rango por debajo del nivel de país. Este tipo indica una división política inferior. No todos los países poseen estos niveles administrativos.
    administrative_area_level_7 Indica una entidad civil de séptimo rango por debajo del nivel de país. Este tipo indica una división política inferior. No todos los países poseen estos niveles administrativos.
    colloquial_area Indica un nombre alternativo de uso general para la entidad.
    locality Indica una entidad política constituida como ciudad o pueblo.
    sublocality Indica una entidad civil de primer rango por debajo de una localidad. Algunas ubicaciones pueden recibir uno de los tipos adicionales sublocality_level_1 a sublocality_level_5. Cada nivel de sublocalidad es una entidad pública. Los números más altos indican un área geográfica más pequeña.
    neighborhood Indica un área residencial con nombre.
    premise Indica una ubicación designada, generalmente un edificio o un conjunto de edificios con un nombre común.
    subpremise Indica una entidad localizable por debajo del nivel de la propiedad, como un apartamento, una unidad o una suite.
    plus_code Indica una referencia de ubicación codificada, derivada de la latitud y la longitud. Los Plus Codes se pueden usar como reemplazo de las direcciones en los lugares donde estas no existen (donde los edificios no están numerados o las calles no tienen nombre). Consulta https://plus.codes para obtener más detalles.
    postal_code Indica un código postal, tal como se usa para identificar una dirección de correo postal dentro del país.
    natural_feature Indica un componente natural destacado.
    airport Un aeropuerto.
    park Indica un parque designado.
    point_of_interest Indica un lugar de interés designado. Por lo general, estos "lugares de interés" son entidades locales destacadas que no encajan con facilidad en otras categorías, como "Edificio Empire State" o "Torre Eiffel".

    Una lista vacía de tipos indica que no hay tipos conocidos para el componente de dirección específico (por ejemplo, Lieu-dit en Francia).

  • FieldMask

    Crea una máscara de campo de respuesta para especificar los campos que se deben mostrar 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 mostrará solo 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 Cómo elegir los campos que se mostrarán para obtener más detalles.