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

Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.

El término geocodificación generalmente hace referencia a la conversión de una dirección en lenguaje natural en una ubicación en un mapa. El proceso de hacer lo contrario, que consiste en traducir una ubicación en el mapa en una dirección en lenguaje natural, se conoce como codificación geográfica inversa.

Solicitudes de geocodificación inversa

Parámetros obligatorios

  • latlng: Las coordenadas de latitud y longitud que especifican la ubicación para la que deseas que la dirección más cercana sea legible.
  • key: la clave de API de tu aplicación. Esta clave identifica tu aplicación a los fines de la administración de la cuota. Obtén información sobre cómo obtener una clave.

Parámetros opcionales

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

  • language: el idioma en el que se muestran los resultados.
    • Consulta la lista de idiomas admitidos. Google suele actualizar los idiomas admitidos, por lo que es posible que esta lista no sea completa.
    • Si no se proporciona el language, el geocodificador intenta usar el idioma preferido especificado en el encabezado Accept-Language o el idioma nativo del dominio desde el que se envió la solicitud.
    • El geocodificador hace todo lo posible para proporcionar una dirección legible tanto para los usuarios como para los usuarios locales. Para lograr ese objetivo, muestra las direcciones en el idioma local, transliteradas en una secuencia de comandos que el usuario puede leer, si es necesario, y observan el idioma preferido. Todas las demás direcciones se muestran en el idioma preferido. Todos los componentes de dirección se muestran en el mismo idioma, que se selecciona desde el primer componente.
    • Si un nombre no está disponible en el idioma preferido, el geocodificador usa la coincidencia más cercana.
  • region: Es el código de región, especificado como un valor ccTLD (“dominio de nivel superior”) de dos caracteres. El parámetro también puede afectar los resultados según la ley aplicable.
  • result_type: Es un filtro de uno o más tipos de dirección, separados por una barra vertical (|). Si el parámetro contiene varios tipos de direcciones, la API muestra 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 dirección especificados. En su lugar, result_type funciona como un filtro posterior a la búsqueda: la API recupera todos los resultados del latlng especificado y, luego, descarta los resultados que no coinciden con los tipos de dirección especificados. Se admiten los siguientes valores:
    • street_address: Indica una dirección precisa.
    • route: Indica una ruta con nombre (como "US 101").
    • intersection: Indica una intersección principal, generalmente de dos rutas principales.
    • political: Indica 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 rango más alto que muestra el geocodificador.
    • administrative_area_level_1: Indica una entidad civil de primer rango 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 están basados en diferentes indicadores y datos de ubicación.
    • administrative_area_level_2: Indica una entidad civil de segundo rango 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 civil 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 civil 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 civil 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 civil 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 civil 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 integrada en una ciudad o un 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 civil. Los números más altos indican áreas geográficas más pequeñas.
    • neighborhood: Indica un área residencial con nombre.
    • premise: Indica una ubicación determinada, generalmente un edificio o un conjunto de edificios con un nombre común.
    • subpremise: Indica una entidad de primer rango por debajo de una ubicación determinada, generalmente, un edificio único dentro de un conjunto de edificios con un nombre común.
    • plus_code: Indica una referencia de una ubicación codificada, derivada de las coordenadas de latitud y 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 información.
    • postal_code: Indica un código postal, tal como se usa en las direcciones postales dentro del país.
    • natural_feature: Indica una formación natural destacada.
    • airport: Indica un aeropuerto.
    • park: Indica un parque determinado.
    • point_of_interest: Indica un lugar de interés determinado. Por lo general, estos "lugares de interés" son entidades locales destacadas que no concuerdan fácilmente con otras categorías, como "Edificio Empire State" o "Torre Eiffel".
  • location_type: Un filtro para 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 muestra 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 su lugar, 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 los resultados que no coinciden con los tipos de ubicación especificados. Se admiten los siguientes valores:
    • "ROOFTOP" solo muestra las direcciones para las que Google tiene información de ubicación precisa hasta la precisión de la dirección.
    • "RANGE_INTERPOLATED" solo muestra las direcciones que reflejan una aproximación (generalmente en una ruta) interpolada entre dos puntos precisos (como intersecciones). Por lo general, un rango interpolado indica que no hay geocódigos exactos disponibles para una dirección.
    • "GEOMETRIC_CENTER" solo muestra centros geométricos de una ubicación, como una polilínea (por ejemplo, una calle) o un polígono (región).
    • "APPROXIMATE" solo muestra las direcciones que se caracterizan por ser aproximadas.

Si los filtros result_type y location_type están presentes, la API muestra solo los resultados que coinciden con los valores result_type y location_type. Si ninguno de los valores de filtro es aceptable, la API muestra 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 "formatted_address" no son solo direcciones postales, sino cualquier forma de asignar nombres geográficos a una ubicación. Por ejemplo, cuando se realiza la geocodificación de un punto en la ciudad de Chicago, el punto geocodificado puede indicarse como una dirección, como la ciudad (Chicago), como el estado (Illinois) o como un país (Estados Unidos). Todas son direcciones al geocodificador. El geocodificador inverso muestra cualquiera de estos tipos como resultados válidos.

El geocodificador inverso establece coincidencias con entidades políticas (países, provincias, ciudades y barrios), direcciones y códigos postales.

A continuación, se muestra la lista completa de los valores de formatted_address que muestra 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 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 resultado más prominente, como en este caso. Si quieres que coincida un tipo de dirección específico, consulta la siguiente sección sobre cómo restringir resultados por tipo. Debido a esto, la ubicación de los resultados puede variar entre sí.

Geocodificación inversa filtrada por tipo

En el siguiente ejemplo, se filtran las direcciones que se muestran para incluir solo aquellas con un tipo de ubicación de 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 codificación geográfica inversa.

Respuestas de geocodificación inversa

El formato de la respuesta de geocodificación inversa es el mismo que el de la respuesta de Geocoding. Consulta Respuestas de geocodificación. 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" dentro del objeto de respuesta de Geocoding contiene el estado de la solicitud y puede contener 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 mostró al menos una dirección.
  • "ZERO_RESULTS" indica que se realizó correctamente la geocodificación inversa, pero no mostró resultados. Esto puede ocurrir si se pasa un valor latlng al geocodificador en una ubicación remota.
  • "OVER_QUERY_LIMIT" indica que superaste tu cuota.
  • "REQUEST_DENIED" indica que se rechazó la solicitud. Posiblemente porque la solicitud incluye un parámetro result_type o location_type, pero no incluye una clave de API.
  • "INVALID_REQUEST" suele indicar una de las siguientes opciones:
    • 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 puede ser exitosa si realizas un nuevo intento.

Códigos plus de geocodificación inversa

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