Solicitud y respuesta de geocodificación inversa (búsqueda de direcciones)

Desarrolladores del Espacio Económico Europeo (EEE)

El término geocodificación generalmente hace referencia a la conversión de una dirección legible por humanos en una ubicación en un mapa. El proceso inverso, es decir, de convertir una ubicación en el mapa en una dirección legible por humanos, se conoce como geocodificación inversa.

Solicitudes de geocodificación inversa

Parámetros obligatorios

  • latlng: Indica las coordenadas de latitud y longitud que especifican la ubicación para la que deseas obtener la dirección más cercana legible por humanos.
  • key: Es la clave de API de tu aplicación. Esta clave identifica tu aplicación para administrar la cuota. Obtén información para obtener una clave.

Parámetros opcionales

Estos son los parámetros opcionales que puedes incluir en una solicitud de geocodificación inversa:

  • language: Es el idioma en el que se devolverán los resultados.
    • Consulta la lista de idiomas admitidos. Google suele actualizar los idiomas admitidos, por lo que es posible que esta lista no sea exhaustiva.
    • Si no se proporciona language, el geocodificador intenta usar el idioma preferido, según se especifica en el encabezado Accept-Language, o el idioma nativo del dominio desde el que se envía la solicitud.
    • El geocodificador 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 las direcciones en el idioma local, transliteradas a una escritura legible para 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, el geocodificador usa la coincidencia más cercana.
  • region: Es el código de región, que se indica como un valor ccTLD ("dominio de nivel superior") de dos caracteres. El parámetro también puede afectar los resultados según la legislación aplicable.
  • result_type: Es un filtro de uno o más tipos de direcciones, separados por una barra vertical (|). Si el parámetro contiene varios tipos de direcciones, la API devuelve todas las direcciones que coinciden con cualquiera de los tipos. Nota sobre el procesamiento: El parámetro result_type no restringe la búsqueda a los tipos de direcciones especificados. En cambio, el parámetro result_type actúa como un filtro posterior a la búsqueda: la API recupera todos los resultados para el latlng especificado y, luego, descarta aquellos que no coinciden con los tipos de dirección especificados. Se admiten los siguientes valores:

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

    El array types en el cuerpo de GeocodeResult en la respuesta indica el tipo de dirección. Entre los ejemplos de tipos de direcciones, se incluyen una dirección, un país o una entidad política. El array types en el campo AddressComponents del cuerpo de GeocodeResult 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.

    Los siguientes tipos se admiten y se devuelven en los arrays de tipo de dirección y de 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 Es una intersección principal, generalmente de dos rutas principales.
    political Es 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 pública de quinto orden 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 pública de sexto orden 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 pública de séptimo orden 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 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 Es una ubicación designada, generalmente un edificio o un conjunto de edificios con un nombre común.
    subpremise Indica una entidad direccionable por debajo del nivel de establecimiento, como un departamento, una unidad o una suite.
    plus_code Es 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). Visita https://plus.codes para obtener más información.
    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 Un componente natural destacado.
    airport Un aeropuerto.
    park Indica un parque con nombre.
    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).

  • location_type: Es un filtro de uno o más tipos de ubicación, separados por una barra vertical (|). Si el parámetro contiene varios tipos de ubicación, la API devuelve todas las direcciones que coinciden con cualquiera de los tipos. Nota sobre el procesamiento: El parámetro location_type no restringe la búsqueda a los tipos de ubicación especificados. En cambio, el parámetro location_type actúa como un filtro posterior a la búsqueda: la API recupera todos los resultados para el latlng especificado y, luego, descarta aquellos que no coinciden con los tipos de ubicación especificados. Se admiten los siguientes valores:
    • "ROOFTOP" devuelve solo las direcciones para las que Google tiene información de ubicación precisa hasta el nivel de dirección.
    • "RANGE_INTERPOLATED" devuelve solo las direcciones que reflejan una aproximación (generalmente en una ruta) interpolada entre dos puntos precisos (como intersecciones). Un rango interpolado suele indicar que no hay geocódigos exactos disponibles para una dirección.
    • "GEOMETRIC_CENTER" devuelve solo los centros geométricos de una ubicación, como una polilínea (por ejemplo, una calle) o un polígono (región).
    • "APPROXIMATE" devuelve solo las direcciones que se caracterizan como aproximadas.
  • extra_computations: Usa este parámetro para especificar las siguientes funciones adicionales en la respuesta: Para habilitar varias de estas funciones en la misma solicitud a la API, incluye el parámetro extra_computations en la solicitud para cada función, por ejemplo: 
    extra_computations=ADDRESS_DESCRIPTORS&extra_computations=BUILDING_AND_ENTRANCES

Si están presentes los filtros result_type y location_type, la API solo devuelve los resultados que coinciden con los valores de result_type y location_type. Si ninguno de los valores de filtro es aceptable, la API devuelve ZERO_RESULTS.

Ejemplo de geocodificación inversa

La siguiente consulta contiene el valor de latitud/longitud para una ubicación en Brooklyn:

https://maps.googleapis.com/maps/api/geocode/json?latlng=40.714224,-73.961452&key=YOUR_API_KEY

La consulta anterior devuelve el siguiente resultado:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "277",
               "short_name" : "277",
               "types" : [ "street_number" ]
            },
            {
               "long_name" : "Bedford Avenue",
               "short_name" : "Bedford Ave",
               "types" : [ "route" ]
            },
            {
               "long_name" : "Williamsburg",
               "short_name" : "Williamsburg",
               "types" : [ "neighborhood", "political" ]
            },
            {
               "long_name" : "Brooklyn",
               "short_name" : "Brooklyn",
               "types" : [ "sublocality", "political" ]
            },
            {
               "long_name" : "Kings",
               "short_name" : "Kings",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "New York",
               "short_name" : "NY",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United States",
               "short_name" : "US",
               "types" : [ "country", "political" ]
            },
            {
               "long_name" : "11211",
               "short_name" : "11211",
               "types" : [ "postal_code" ]
            }
         ],
         "formatted_address" : "277 Bedford Avenue, Brooklyn, NY 11211, USA",
         "geometry" : {
            "location" : {
               "lat" : 40.714232,
               "lng" : -73.9612889
            },
            "location_type" : "ROOFTOP",
            "viewport" : {
               "northeast" : {
                  "lat" : 40.7155809802915,
                  "lng" : -73.9599399197085
               },
               "southwest" : {
                  "lat" : 40.7128830197085,
                  "lng" : -73.96263788029151
               }
            }
         },
         "place_id" : "ChIJd8BlQ2BZwokRAFUEcm_qrcA",
         "types" : [ "street_address" ]
      },

  ... Additional <code>results[]</code> ...

Ten en cuenta que el geocodificador inverso devolvió más de un resultado. Los resultados de "formatted_address" 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 denotarse 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 devuelve cualquiera de estos tipos como resultados válidos.

La geocodificación inversa establece coincidencias con entidades políticas (países, provincias, ciudades y vecindarios), direcciones y códigos postales.

A continuación, se muestra la lista completa de los valores de formatted_address que devolvió la consulta anterior.

{
   "plus_code" : {
      "compound_code" : "P27Q+MCM New York, NY, USA",
      "global_code" : "87G8P27Q+MCM"
   },
   "results" : [
      {
         "formatted_address" : "277 Bedford Ave, Brooklyn, NY 11211, USA",
         ...
         "types" : [ "street_address" ]
      },
      {
         "formatted_address" : "279 Bedford Ave, Brooklyn, NY 11211, USA",
         ...
         "types" : [ "premise" ]
      },
      {
         "formatted_address" : "277 Bedford Ave, Brooklyn, NY 11211, USA",
         ...
         "types" : [ "establishment", "point_of_interest" ]
      },
      {
         "formatted_address" : "291-275 Bedford Ave, Brooklyn, NY 11211, USA",
         ...
         "types" : [ "route" ]
      },
      {
         "formatted_address" : "P27Q+MC New York, NY, USA",
         ...
         "types" : [ "plus_code" ]
      },
      {
         "formatted_address" : "South Williamsburg, Brooklyn, NY, USA",
         ...
         "types" : [ "neighborhood", "political" ]
      },
      {
         "formatted_address" : "Brooklyn, NY 11211, USA",
         ...
         "types" : [ "postal_code" ]
      },
      {
         "formatted_address" : "Williamsburg, Brooklyn, NY, USA",
         ...
         "types" : [ "neighborhood", "political" ]
      },
      {
         "formatted_address" : "Kings County, Brooklyn, NY, USA",
         ...
         "types" : [ "administrative_area_level_2", "political" ]
      },
      {
         "formatted_address" : "Brooklyn, NY, USA",
         ...
         "types" : [ "political", "sublocality", "sublocality_level_1" ]
      },
      {
         "formatted_address" : "New York, NY, USA",
         ...
         "types" : [ "locality", "political" ]
      },
      {
         "formatted_address" : "New York, USA",
         ...
         "types" : [ "administrative_area_level_1", "political" ]
      },
      {
         "formatted_address" : "United States",
         ...
         "types" : [ "country", "political" ]
      }
   ],
   "status" : "OK"
}

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. En general, la dirección más exacta es el resultado más prominente, como en este caso. Si deseas que coincida con un tipo de dirección específico, consulta la sección que aparece a continuación sobre cómo restringir los resultados por tipo. Por este motivo, la ubicación de los resultados en relación con los demás puede variar.

Geocodificación inversa filtrada por tipo

En el siguiente ejemplo, se filtran las direcciones que se devuelven para incluir solo aquellas con un tipo de ubicación ROOFTOP y un tipo de dirección street_address.

https://maps.googleapis.com/maps/api/geocode/json?latlng=40.714224,-73.961452
&location_type=ROOFTOP&result_type=street_address&key=YOUR_API_KEY

Nota: Estos filtros solo son válidos para la geocodificación inversa.

Respuestas de geocodificación inversa

El formato de la respuesta de geocodificación inversa es el mismo que el de la respuesta de geocodificación. Consulta Respuestas de Geocoding. A continuación se indican los códigos de estado posibles en una respuesta de geocodificación inversa.

Códigos de estado de la geocodificación inversa

El campo "status" del objeto de respuesta de Geocoding contiene el estado de la solicitud y puede incluir información de depuración para ayudarte a identificar por qué no funciona la geocodificación inversa. El campo "status" puede contener los siguientes valores:

  • "OK" indica que no se produjeron errores y que se devolvió al menos una dirección.
  • "ZERO_RESULTS" indica que la geocodificación inversa se realizó correctamente, pero no devolvió resultados. Esto puede ocurrir si se pasó un valor latlng en una ubicación remota al geocodificador.
  • "OVER_QUERY_LIMIT" indica que superaste tu cuota.
  • "REQUEST_DENIED" indica que se rechazó la solicitud. Es posible que la solicitud incluya un parámetro result_type o location_type, pero no una clave de API.
  • Por lo general, "INVALID_REQUEST" indica uno de los siguientes motivos:
    • Falta la consulta (address, components o latlng).
    • Se proporcionó un result_type o location_type no válido.
  • "UNKNOWN_ERROR" indica que no se pudo procesar la solicitud debido a un error del servidor. La solicitud podría completarse con éxito si realizas un nuevo intento.

Geocodificación inversa de Plus Codes

El campo plus_code de la respuesta de Geocoding contiene un Plus Code que se aproxima de la mejor manera a la latitud y la longitud consultadas. Además, en la mayoría de los casos, el array de resultados JSON contiene un resultado de geocodificación completo con un tipo plus_code y una dirección que contiene un Plus Code. Se garantiza que la distancia entre el Plus Code decodificado y el punto de solicitud sea inferior a 10 metros.