Solicitud y respuesta de geocodificación

Solicitud

Una solicitud a la API de Geocoding debe respetar la siguiente forma:

https://maps.googleapis.com/maps/api/geocode/outputFormat?parameters

donde outputFormat puede ser cualquiera de los siguientes valores:

• json (recomendado) indica el formato de salida en JavaScript Object Notation (JSON).
• xml indica el formato de salida como XML.

Se requiere HTTPS.

Nota: Las URLs deben estar codificadas correctamente para ser válidas y tienen un límite de 16,384 caracteres en todos los servicios web. Ten en cuenta este límite cuando construyas tus URLs. Ten en cuenta que los diferentes navegadores, proxies y servidores también pueden tener límites de caracteres diferentes para las URLs.

Algunos parámetros son obligatorios y otros opcionales. Como es norma en las URLs, los parámetros se separan con el carácter et (&).

En el resto de esta página, se describen la geocodificación y la geocodificación inversa por separado, ya que hay diferentes parámetros disponibles para cada tipo de solicitud.

Parámetros de geocodificación (búsqueda de latitud/longitud)

Todos los caracteres reservados (por ejemplo, el signo más "+") deben estar codificados en URL.

Parámetros obligatorios en una solicitud de geocodificación:

• address: Indica la dirección o el Plus Code que deseas geocodificar. Especifica las direcciones de acuerdo con el formato que utiliza el servicio nacional de correos del país en cuestión. Se deben evitar elementos de dirección adicionales, como nombres de empresas y números de unidad, habitación o piso. Los elementos de la dirección deben estar delimitados por espacios (se muestran aquí como escapados de URL a %20):

  address=24%20Sussex%20Drive%20Ottawa%20ON

  Formatea los códigos plus tal como se muestra aquí (para utilizarlos en la dirección URL, los signos más se convierten (se escapan) en %2B y los espacios en %20):
  • Un código global es un código de área de 4 caracteres y un código local de 6 caracteres o más (849VCWC8+R9 es 849VCWC8%2BR9).
  • Un código compuesto se compone de un código local de 6 caracteres o más con una ubicación explícita (CWC8+R9 Mountain View, CA, EE.UU. se convierte en CWC8%2BR9%20Mountain%20View%20CA%20USA).
  
  --OR--
  components: Es un filtro de componentes con elementos separados por una barra vertical (|). El filtro de componentes también se acepta como parámetro opcional si se proporciona un address. Cada elemento del filtro de componentes consta de un par component:value y restringe por completo los resultados del geocodificador. Obtén más información sobre el filtrado de componentes a continuación.
• key: Es la clave de API de tu aplicación. Esa clave identifica tu aplicación a los fines de la administración de la cuota. Descubre cómo obtener una clave.

Consulta las preguntas frecuentes para obtener orientación adicional.

Parámetros opcionales en una solicitud de geocodificación:

• bounds: Es el cuadro de límite del viewport dentro del que se personalizan resultados de geocódigos de forma más prominente. Este parámetro solo afectará, pero no restringirá por completo, los resultados del geocodificador. (Para obtener más información, consulta Restricción de viewports a continuación).
• language: Es el idioma en el que se mostrarán los resultados.
  • Consulta la lista de idiomas compatibles. Google actualiza con frecuencia los idiomas admitidos, por lo que es posible que esta lista no sea completa.
  • Si no se proporciona language, el geocodificador intentará 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 que sea legible para el usuario y los locales. Para lograr ese objetivo, muestra las direcciones en el idioma local, transliteradas a una secuencia de comandos legible por el usuario si es necesario y que respeta el idioma preferido. Todas las demás direcciones se muestran en el idioma preferido. Los componentes de la dirección se muestran en el mismo idioma, que se selecciona a partir del primer componente.
  • Si un nombre no está disponible en el idioma preferido, el geocodificador 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 el que se muestran. El geocodificador interpreta las abreviaturas de manera diferente según el idioma; por ejemplo, las abreviaturas para los tipos de calle o los sinónimos que pueden ser válidos en un idioma, pero no en otro. Por ejemplo, utca y tér son sinónimos de calle y plaza, respectivamente, en húngaro.
• region: Es el código regional, que se especifica como un valor ccTLD ("dominio de nivel superior") de dos caracteres. Este parámetro solo afecta los resultados del geocodificador, pero no los restringe por completo. (Para obtener más información, consulta Personalización de la región a continuación). El parámetro también puede afectar los resultados según la ley aplicable.
• components: Es un filtro de componentes con elementos separados por una canalización (|). El filtro de componentes es obligatorio si la solicitud no incluye un address. Cada elemento del filtro de componentes consiste en un par component:value y restringe por completo los resultados del geocodificador. Obtén más información sobre el filtrado de componentes a continuación.
• extra_computations: Usa este parámetro para especificar las siguientes funciones adicionales en la respuesta:
  • ADDRESS_DESCRIPTORS: Consulta los descriptores de direcciones para obtener más información.
  • BUILDING_AND_ENTRANCES: Consulta los esquemas de entradas y edificios para obtener más detalles.
  Para habilitar varias de estas funciones para la misma solicitud a la API, incluye el parámetro extra_computations en la solicitud de cada función, por ejemplo:

  extra_computations=ADDRESS_DESCRIPTORS&extra_computations=BUILDING_AND_ENTRANCES

Respuestas

Las respuestas de Geocoding se muestran en el formato indicado por la marca output dentro de la solicitud de URL, o en formato JSON de forma predeterminada.

En este ejemplo, la API de Geocoding solicita una respuesta json para una consulta en la dirección "1600 Amphitheatre Parkway, Mountain View, CA".

En esta solicitud, se muestra el uso de la marca output JSON:

https://maps.googleapis.com/maps/api/geocode/json?address=1600+Amphitheatre+Parkway,+Mountain+View,+CA&key=YOUR_API_KEY

En esta solicitud, se muestra el uso de la marca output de XML:

https://maps.googleapis.com/maps/api/geocode/xml?address=1600+Amphitheatre+Parkway,+Mountain+View,+CA&key=YOUR_API_KEY

Selecciona las pestañas que se indican a continuación para ver las respuestas JSON y XML de ejemplo.

JSON

{
    "results": [
        {
            "address_components": [
                {
                    "long_name": "1600",
                    "short_name": "1600",
                    "types": [
                        "street_number"
                    ]
                },
                {
                    "long_name": "Amphitheatre Parkway",
                    "short_name": "Amphitheatre Pkwy",
                    "types": [
                        "route"
                    ]
                },
                {
                    "long_name": "Mountain View",
                    "short_name": "Mountain View",
                    "types": [
                        "locality",
                        "political"
                    ]
                },
                {
                    "long_name": "Santa Clara County",
                    "short_name": "Santa Clara County",
                    "types": [
                        "administrative_area_level_2",
                        "political"
                    ]
                },
                {
                    "long_name": "California",
                    "short_name": "CA",
                    "types": [
                        "administrative_area_level_1",
                        "political"
                    ]
                },
                {
                    "long_name": "United States",
                    "short_name": "US",
                    "types": [
                        "country",
                        "political"
                    ]
                },
                {
                    "long_name": "94043",
                    "short_name": "94043",
                    "types": [
                        "postal_code"
                    ]
                },
                {
                    "long_name": "1351",
                    "short_name": "1351",
                    "types": [
                        "postal_code_suffix"
                    ]
                }
            ],
            "formatted_address": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
            "geometry": {
                "location": {
                    "lat": 37.4222804,
                    "lng": -122.0843428
                },
                "location_type": "ROOFTOP",
                "viewport": {
                    "northeast": {
                        "lat": 37.4237349802915,
                        "lng": -122.083183169709
                    },
                    "southwest": {
                        "lat": 37.4210370197085,
                        "lng": -122.085881130292
                    }
                }
            },
            "place_id": "ChIJRxcAvRO7j4AR6hm6tys8yA8",
            "plus_code": {
                "compound_code": "CWC8+W7 Mountain View, CA",
                "global_code": "849VCWC8+W7"
            },
            "types": [
                "street_address"
            ]
        }
    ],
    "status": "OK"
}

Ten en cuenta que una respuesta JSON contiene dos elementos principales:

• "status" contiene metadatos sobre la solicitud. Consulta los códigos de estado a continuación.
• "results" contiene una matriz de información sobre direcciones geocodificadas e información sobre geometría.

Por lo general, para las búsquedas de direcciones solo se devuelve una entrada en el array "results", aunque el geocodificador puede devolver varios resultados cuando las consultas de direcciones sean ambiguas.

XML

<GeocodeResponse>
    <status>OK</status>
    <result>
        <type>street_address</type>
        <formatted_address>1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA</formatted_address>
        <address_component>
            <long_name>1600</long_name>
            <short_name>1600</short_name>
            <type>street_number</type>
        </address_component>
        <address_component>
            <long_name>Amphitheatre Parkway</long_name>
            <short_name>Amphitheatre Pkwy</short_name>
            <type>route</type>
        </address_component>
        <address_component>
            <long_name>Mountain View</long_name>
            <short_name>Mountain View</short_name>
            <type>locality</type>
            <type>political</type>
        </address_component>
        <address_component>
            <long_name>Santa Clara County</long_name>
            <short_name>Santa Clara County</short_name>
            <type>administrative_area_level_2</type>
            <type>political</type>
        </address_component>
        <address_component>
            <long_name>California</long_name>
            <short_name>CA</short_name>
            <type>administrative_area_level_1</type>
            <type>political</type>
        </address_component>
        <address_component>
            <long_name>United States</long_name>
            <short_name>US</short_name>
            <type>country</type>
            <type>political</type>
        </address_component>
        <address_component>
            <long_name>94043</long_name>
            <short_name>94043</short_name>
            <type>postal_code</type>
        </address_component>
        <geometry>
            <location>
                <lat>37.4224428</lat>
                <lng>-122.0842467</lng>
            </location>
            <location_type>ROOFTOP</location_type>
            <viewport>
                <southwest>
                    <lat>37.4212648</lat>
                    <lng>-122.0856069</lng>
                </southwest>
                <northeast>
                    <lat>37.4239628</lat>
                    <lng>-122.0829089</lng>
                </northeast>
            </viewport>
        </geometry>
        <place_id>ChIJeRpOeF67j4AR9ydy_PIzPuM</place_id>
        <plus_code>
            <global_code>849VCWC8+X8</global_code>
            <compound_code>CWC8+X8 Mountain View, CA</compound_code>
        </plus_code>
    </result>
</GeocodeResponse>

Ten en cuenta que una respuesta XML consiste en un solo <GeocodeResponse> y dos elementos de nivel superior:

• <status> contiene metadatos sobre la solicitud. Consulta los códigos de estado más abajo.
• Cero o más elementos <result>, cada uno con un conjunto de información sobre direcciones geocodificadas y datos geométricos.

La respuesta XML es considerablemente más larga que la respuesta JSON. Por ese motivo, te recomendamos que uses json como la marca de salida preferida, a menos que tu servicio requiera xml por algún motivo. Además, el procesamiento de árboles XML requiere cierto cuidado, ya que debes hacer referencia a los nodos y elementos adecuados. Consulta Cómo analizar XML con XPath a fin de obtener algunos patrones de diseño recomendados para el procesamiento del resultado.

En el resto de esta documentación, se usa la sintaxis JSON. En la mayoría de los casos, el formato de salida no importa para ilustrar conceptos o nombres de campos en la documentación. Sin embargo, ten en cuenta las siguientes diferencias leves:

• Los resultados XML se unen en un elemento raíz <GeocodeResponse>.
• JSON denota entradas con varios elementos mediante arrays en plural (types), mientras que XML las denota con varios elementos en singular (<type>).
• Los elementos en blanco se indican mediante arrays vacíos en JSON, pero mediante la ausencia de cualquiera de esos elementos en XML. Una respuesta que no genera resultados mostrará un array de results vacío en JSON, pero no mostrará elementos <result> en XML, por ejemplo.

Códigos de estado

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 localizar por qué no funciona la geocodificación. El campo "status" puede contener los siguientes valores:

• "OK" indica que no se produjeron errores, es decir, que la dirección se analizó correctamente y mostró al menos un geocódigo.
• "ZERO_RESULTS" indica que el geocódigo era correcto, pero no mostró resultados. Esto puede ocurrir si se pasó un valor address inexistente al geocodificador.
• OVER_DAILY_LIMIT indica cualquiera de las siguientes opciones:
  • Falta la clave de API o no es válida.
  • No se habilitó la facturación en tu cuenta.
  • Se superó un límite de uso autoimpuesto.
  • La forma de pago proporcionada ya no es válida (por ejemplo, si venció una tarjeta de crédito).

  Consulta las Preguntas frecuentes de Maps para obtener información sobre cómo solucionar este problema.

• "OVER_QUERY_LIMIT" indica que superaste tu cuota.
• "REQUEST_DENIED" indica que se rechazó tu solicitud.
• "INVALID_REQUEST" suele indicar que falta la consulta (address, components o latlng).
• "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.

Mensajes de error

Cuando el geocodificador muestra un código de estado distinto de OK, puede haber un campo error_message adicional en el objeto de respuesta de Geocoding. Este campo contiene información más detallada sobre los motivos del código de estado proporcionado.

Nota: No se garantiza que este campo aparezca siempre, y su contenido está sujeto a cambios.

Resultados

Cuando el geocodificador devuelve resultados, los ubica en un array results (JSON). Incluso si el geocodificador no muestra resultados (por ejemplo, si la dirección no existe), sigue mostrando un array results vacío. (Las respuestas XML consisten en cero o más elementos <result>).

Un resultado típico contiene los siguientes campos:

• El array types[] indica el tipo del resultado que se muestra. Este array contiene un conjunto de cero o más etiquetas que identifican el tipo de componente que se muestra en el resultado. Por ejemplo, un geocódigo de "Chicago" muestra "localidad", que indica que "Chicago" es una ciudad, y también "política", que indica que es una entidad política. Es posible que los componentes tengan un array de tipos vacío cuando no hay tipos conocidos para ese componente de dirección. La API puede agregar valores de tipo nuevos según sea necesario. Para obtener más información, consulta Tipos de direcciones y componentes de las direcciones.
• formatted_address es una cadena que contiene la dirección legible por humanos de esta ubicación.

  A menudo, esta dirección equivale a la dirección postal. Ten en cuenta que, en algunos países, como los que integran el Reino Unido, no se permite la distribución de direcciones postales verdaderas debido a restricciones de licencia.

  La dirección con formato está compuesta, de manera lógica, por uno o más componentes de dirección. Por ejemplo, la dirección "111 8th Avenue, New York, NY" consta de los siguientes componentes: "111" (número de la calle), "8th Avenue" (calle), "New York" (ciudad) y "NY" (estado de los EE.UU.).

  No analices la dirección con formato por vía programática. En cambio, utiliza los componentes individuales de la dirección, que la respuesta de la API incluye además del campo de dirección con formato.

• address_components[] es un array que contiene los componentes independientes que se aplican a esta dirección.

  Por lo general, cada componente de la dirección incluye los siguientes campos:

  • types[]: Es un array que indica el tipo de componente de la dirección. Consulta la lista de tipos admitidos.
  • long_name: Es la descripción textual completa o el nombre del componente de la dirección que muestra el geocodificador.
  • short_name: Es un nombre textual abreviado para el componente de la dirección si está disponible. Por ejemplo, un componente de dirección para el estado de Alaska puede tener un long_name de "Alaska" y un short_name de "AK" con la abreviatura postal de 2 letras.

  Ten en cuenta lo siguiente acerca del array address_components[]:

  • El array de componentes de dirección puede incluir más componentes que formatted_address.
  • El array no necesariamente incluye todas las entidades políticas que contienen una dirección, además de las incluidas en formatted_address. Para obtener datos sobre todas las entidades políticas que contienen una dirección específica, debes usar la geocodificación inversa, y pasar la latitud y la longitud de la dirección como parámetro a la solicitud.
  • No se garantiza que el formato de la respuesta permanezca igual entre las distintas solicitudes. En particular, la cantidad de address_components varía según la dirección solicitada y puede cambiar con el tiempo para la misma dirección. Un componente puede cambiar de posición en el array. El tipo de componente puede cambiar. Es posible que falte un componente en particular en una respuesta posterior.

  Para controlar el array de componentes, debes analizar la respuesta y seleccionar los valores adecuados a través de expresiones. Consulta la guía para analizar una respuesta.

• postcode_localities[] es un array que denota hasta 100 localidades incluidas en un código postal. Solo se presenta cuando el resultado es un código postal que contiene varias localidades.
• geometry contiene la siguiente información:
  • location contiene los valores de latitud y longitud geocodificados. Para las búsquedas de direcciones normales, este campo suele ser el más importante.

  • location_type almacena datos adicionales sobre la ubicación especificada. Actualmente, se admiten los siguientes valores:

    • "ROOFTOP" indica que el resultado que se muestra es un geocódigo preciso para el que tenemos información de ubicación precisa que puede delimitarse hasta la dirección.
    • "RANGE_INTERPOLATED" indica que el resultado que se muestra refleja una aproximación (generalmente en una ruta) interpolada entre dos puntos precisos (como intersecciones). Generalmente, se devuelven resultados interpolados cuando no se encuentran geocódigos exactos disponibles para una dirección.
    • "GEOMETRIC_CENTER" indica que el resultado que se muestra es el centro geométrico de un resultado, como una polilínea (por ejemplo, una calle) o un polígono (región).
    • "APPROXIMATE" indica que el resultado que se muestra es aproximado.
  • viewport contiene el viewport recomendado para mostrar el resultado que se muestra, especificado como dos valores de latitud y longitud que definen las esquinas southwest y northeast del cuadro de límite del viewport. Por lo general, el viewport se usa para enmarcar un resultado cuando se lo muestra a un usuario.
  • bounds (se muestra de manera opcional) abarca el cuadro de límite que puede contener por completo el resultado mostrado. Ten en cuenta que estos límites podrían no coincidir con el viewport recomendado. (Por ejemplo, San Francisco incluye las Islas Farallón, que técnicamente son parte de la ciudad, pero no se deben mostrar en el viewport).
• plus_code (consulta Código de ubicación abierto y Plus Codes) es una referencia de ubicación codificada, derivada de las coordenadas de latitud y longitud, que representa un área: 1/8,000 de un grado por 1/8,000 de un grado (alrededor de 14 m x 14 m en el ecuador) o menos. Los Plus Codes se pueden usar como reemplazo de las direcciones en lugares donde las direcciones no existen (donde los edificios no tienen número o las calles no tienen nombre). La API no siempre muestra códigos plus.

  Cuando el servicio muestra un Plus Code, el código tiene el formato de un código global y un código compuesto:

  • global_code es un código de área de 4 caracteres y un código local de 6 caracteres o más (849VCWC8+R9).
  • compound_code es un código local de 6 caracteres o más con una ubicación explícita (CWC8+R9, Mountain View, CA, EE.UU.). No analices este contenido de forma programática.
  Cuando está disponible, la API muestra el código global y el compuesto. Sin embargo, si el resultado corresponde a una ubicación remota (por ejemplo, un océano o un desierto), solo se puede mostrar el código global.

• partial_match indica que el geocodificador no mostró una concordancia exacta para la solicitud original, aunque sí encontró una coincidencia parcial para la dirección solicitada. Te recomendamos que examines la solicitud original para comprobar que no haya errores ortográficos y que la dirección no esté incompleta.

  Las coincidencias parciales generalmente ocurren cuando las direcciones que se pasan en la solicitud no existen en la localidad. También se pueden mostrar coincidencias parciales cuando una solicitud concuerda con dos o más ubicaciones en la misma localidad. Por ejemplo, "Hillpar St, Bristol, UK" mostrará una coincidencia parcial tanto para Henry Street como para Henrietta Street. Ten en cuenta que si una solicitud incluye una dirección con un componente que contiene errores ortográficos, el servicio de geocodificación puede sugerir una dirección alternativa. Las sugerencias propuestas de esta manera también se marcarán como una coincidencia parcial.

• place_id es un identificador único que se puede usar con otras APIs de Google. Por ejemplo, puedes usar el place_id en una solicitud a la API de Places para obtener detalles de una empresa local, como el número de teléfono, el horario de atención, las opiniones de los usuarios y mucho más. Consulta la descripción general del ID de lugar.

Tipos de direcciones y tipos de componentes de las direcciones

El array types[] en el resultado indica el tipo de dirección. Algunos ejemplos de tipos de dirección incluyen una dirección, un país o una entidad política. También hay un array types[] en el address_components[], que indica el tipo de cada parte de la dirección. Los ejemplos incluyen el número de una calle o el país. (A continuación, se proporciona una lista completa de tipos). 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.

El geocodificador admite y muestra los siguientes tipos en las matrices de tipo de dirección y de tipo de componente de dirección:

• street_address indica una dirección precisa.
• route indica una ruta designada (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 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 pública de tercer 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_4 indica una entidad pública de cuarto 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_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 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 pública de primer orden 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 direccionable debajo del nivel del establecimiento, como un departamento, una unidad o un 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). 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 indica un componente natural destacado.
• airport indica 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.

Además de lo anterior, los componentes de dirección pueden incluir los tipos que se indican aquí. Esta lista no es exhaustiva y está sujeta a cambios.

• floor indica el piso de la dirección de un edificio.
• establishment suele indicar un lugar que aún no se categorizó.
• landmark indica un lugar cercano que se usa como referencia para facilitar la navegación.
• point_of_interest indica un lugar de interés designado.
• parking indica un estacionamiento o una estructura de estacionamiento.
• post_box indica una casilla de correo postal específica.
• postal_town indica un grupo de áreas geográficas, como locality y sublocality, que se usan para las direcciones de correo postal en algunos países.
• room indica una habitación en una dirección de un edificio.
• street_number indica el número exacto de una calle.
• bus_station, train_station y transit_station indican la ubicación de una parada de autobús, tren o transporte público.

Nota: No se garantiza que la API de Geocoding muestre ningún componente en particular para una dirección dentro de nuestro conjunto de datos. Lo que podría considerarse una ciudad, como Brooklyn, podría no mostrarse como una localidad, sino como otro componente, en este caso, sublocality_level_1. Los componentes específicos que se muestran están sujetos a cambios sin previo aviso. Diseña tu código para que sea flexible si quieres extraer componentes de dirección de la respuesta.

Personalización de viewports

En una solicitud de Geocoding, puedes indicarle al servicio de Geocoding que priorice los resultados dentro de un viewport determinado (expresado como un cuadro delimitador). Puedes hacerlo en la URL de la solicitud configurando el parámetro bounds.

El parámetro bounds define las coordenadas de latitud y longitud de las esquinas suroeste y noreste de este cuadro delimitador con un carácter de barra vertical (|) para separar las coordenadas.

Nota: Esto solo agrega un sesgo hacia los resultados dentro del viewport y no garantiza que este contendrá todos los resultados o ninguno. Por lo general, el extremo de Autocomplete de la API de Places es más adecuado para consultas ambiguas y puede restringir los resultados a un área específica. El artículo sobre prácticas recomendadas de Geocoding proporciona orientación sobre qué extremo de API se ajusta mejor a cada caso de uso.

Por ejemplo, un geocódigo de "Washington" generalmente muestra el estado de Washington en EE.UU.:

Solicitud:

https://maps.googleapis.com/maps/api/geocode/json?address=Washington&key=YOUR_API_KEY

Respuesta:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "Washington",
               "short_name" : "WA",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United States",
               "short_name" : "US",
               "types" : [ "country", "political" ]
            }
         ],
         "formatted_address" : "Washington, USA",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 49.0024442,
                  "lng" : -116.91558
               },
               "southwest" : {
                  "lat" : 45.543541,
                  "lng" : -124.8489739
               }
            },
            "location" : {
               "lat" : 47.7510741,
               "lng" : -120.7401385
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 49.0024442,
                  "lng" : -116.91558
               },
               "southwest" : {
                  "lat" : 45.543541,
                  "lng" : -124.8489739
               }
            }
         },
         "place_id" : "ChIJ-bDD5__lhVQRuvNfbGh4QpQ",
         "types" : [ "administrative_area_level_1", "political" ]
      }
   ],
   "status" : "OK"
}

Sin embargo, cuando se agrega un argumento bounds que define un cuadro delimitador en la parte noreste de EE.UU., el resultado de este geocódigo muestra la ciudad de Washington, D.C.:

Solicitud:

https://maps.googleapis.com/maps/api/geocode/json?address=Washington&bounds=36.47,-84.72%7C43.39,-65.90&key=YOUR_API_KEY

Respuesta:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "Washington",
               "short_name" : "Washington",
               "types" : [ "locality", "political" ]
            },
            {
               "long_name" : "District of Columbia",
               "short_name" : "District of Columbia",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "District of Columbia",
               "short_name" : "DC",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United States",
               "short_name" : "US",
               "types" : [ "country", "political" ]
            }
         ],
         "formatted_address" : "Washington, DC, USA",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 38.9958641,
                  "lng" : -76.90939299999999
               },
               "southwest" : {
                  "lat" : 38.7916449,
                  "lng" : -77.119759
               }
            },
            "location" : {
               "lat" : 38.9071923,
               "lng" : -77.03687069999999
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 38.9958641,
                  "lng" : -76.90939299999999
               },
               "southwest" : {
                  "lat" : 38.7916449,
                  "lng" : -77.119759
               }
            }
         },
         "place_id" : "ChIJW-T2Wt7Gt4kRKl2I1CJFUsI",
         "types" : [ "locality", "political" ]
      }
   ],
   "status" : "OK"
}

Restricción por región

En una solicitud de Geocoding, puedes indicarle al servicio de geocodificación que muestre resultados personalizados para una región en particular mediante el parámetro region. Este parámetro toma un argumento ccTLD (dominio de nivel superior de código de país) que especifica el sesgo de la región. La mayoría de los códigos de ccTLD son idénticos a los códigos ISO 3166-1, con algunas excepciones notables. Por ejemplo, el ccTLD del Reino Unido es “uk” (.co.uk), mientras que su código ISO 3166-1 es “gb” (técnicamente para la entidad de “Reino Unido de Gran Bretaña e Irlanda del Norte”).

Se pueden restringir los resultados de la geocodificación para todos los dominios en los que se ejecute oficialmente la aplicación principal de Google Maps. Ten en cuenta que la personalización solo antepone los resultados correspondientes a un dominio específico. Si hay más resultados relevantes fuera de este dominio, es posible que se incluyan.

Por ejemplo, un geocódigo de "Toledo" muestra este resultado, ya que el dominio predeterminado para la API de Geocoding se establece en Estados Unidos. Solicitud:

https://maps.googleapis.com/maps/api/geocode/json?address=Toledo&key=YOUR_API_KEY

Respuesta:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "Toledo",
               "short_name" : "Toledo",
               "types" : [ "locality", "political" ]
            },
            {
               "long_name" : "Lucas County",
               "short_name" : "Lucas County",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "Ohio",
               "short_name" : "OH",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United States",
               "short_name" : "US",
               "types" : [ "country", "political" ]
            }
         ],
         "formatted_address" : "Toledo, OH, USA",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 41.732844,
                  "lng" : -83.454229
               },
               "southwest" : {
                  "lat" : 41.580266,
                  "lng" : -83.69423700000002
               }
            },
            "location" : {
               "lat" : 41.6639383,
               "lng" : -83.55521200000001
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 41.732844,
                  "lng" : -83.454229
               },
               "southwest" : {
                  "lat" : 41.580266,
                  "lng" : -83.69423700000002
               }
            }
         },
         "place_id" : "ChIJeU4e_C2HO4gRRcM6RZ_IPHw",
         "types" : [ "locality", "political" ]
      }
   ],
   "status" : "OK"
}

Una solicitud de geocodificación para "Toledo" con region=es (España) mostrará la ciudad española.

Solicitud:

https://maps.googleapis.com/maps/api/geocode/json?address=Toledo&region=es&key=YOUR_API_KEY

Respuesta:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "Toledo",
               "short_name" : "Toledo",
               "types" : [ "locality", "political" ]
            },
            {
               "long_name" : "Toledo",
               "short_name" : "TO",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "Castile-La Mancha",
               "short_name" : "CM",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "Spain",
               "short_name" : "ES",
               "types" : [ "country", "political" ]
            }
         ],
         "formatted_address" : "Toledo, Spain",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 39.88605099999999,
                  "lng" : -3.9192423
               },
               "southwest" : {
                  "lat" : 39.8383676,
                  "lng" : -4.0796176
               }
            },
            "location" : {
               "lat" : 39.8628316,
               "lng" : -4.027323099999999
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 39.88605099999999,
                  "lng" : -3.9192423
               },
               "southwest" : {
                  "lat" : 39.8383676,
                  "lng" : -4.0796176
               }
            }
         },
         "place_id" : "ChIJ8f21C60Lag0R_q11auhbf8Y",
         "types" : [ "locality", "political" ]
      }
   ],
   "status" : "OK"
}

Filtrado de componentes

En una respuesta de Geocoding, la API de Geocoding puede mostrar resultados de dirección restringidos a un área específica. Puedes especificar la restricción con el filtro components. Un filtro consiste en una lista de pares component:value separados por una barra vertical (|). Los valores de filtro admiten los mismos métodos de corrección ortográfica y de coincidencia parcial que otras solicitudes de Geocoding. Si el geocodificador encuentra una coincidencia parcial para un filtro de componentes, la respuesta contendrá un campo partial_match.

Entre los components que se pueden filtrar, se incluyen los siguientes:

• postal_code coincide con postal_code y postal_code_prefix.
• country establece coincidencias con un nombre de país o con un código de país ISO 3166-1 de dos letras. La API sigue el estándar ISO para definir los países, y el filtrado funciona mejor cuando se usa el código ISO correspondiente del país.
  Nota: Si recibes resultados inesperados con un código de país, verifica si el código utilizado incluye los países, los territorios dependientes y las áreas especiales de interés geográfico que deseas. Puedes encontrar información sobre el código en Wikipedia: Lista de códigos de país ISO 3166 o en la Plataforma de navegación en línea ISO.

Se puede usar el siguiente components para influir en los resultados, pero no se aplicará:

• route establece coincidencias con el nombre largo o corto de una ruta.
• locality establece coincidencias con los tipos locality y sublocality.
• administrative_area coincide con todos los administrative_area niveles.

Notas sobre el filtrado de componentes:

• No repitas estos filtros de componentes en las solicitudes, o la API mostrará Invalid_request: country, postal_code, route.
• Si la solicitud contiene filtros de componentes repetidos, la API evalúa esos filtros como Y, no como O.
• Los resultados son coherentes con Google Maps, que, en ocasiones, genera respuestas ZERO_RESULTS inesperadas. El uso de Place Autocomplete puede proporcionar mejores resultados en algunos casos de uso. Para obtener más información, consulta estas Preguntas frecuentes.
• Para cada componente de dirección, especifícalo en el parámetro address o en un filtro components, pero no en ambos. Especificar los mismos valores en ambos puede generar ZERO_RESULTS.

Un geocódigo para "High St, Hastings" con components=country:GB muestra un resultado en Hastings, Inglaterra, y no en Hastings-On-Hudson, EE.UU.

Solicitud:

https://maps.googleapis.com/maps/api/geocode/json?address=high+st+hasting&components=country:GB&key=YOUR_API_KEY

Respuesta:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "High Street",
               "short_name" : "High St",
               "types" : [ "route" ]
            },
            {
               "long_name" : "Hastings",
               "short_name" : "Hastings",
               "types" : [ "postal_town" ]
            },
            {
               "long_name" : "East Sussex",
               "short_name" : "East Sussex",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "England",
               "short_name" : "England",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United Kingdom",
               "short_name" : "GB",
               "types" : [ "country", "political" ]
            },
            {
               "long_name" : "TN34 3EY",
               "short_name" : "TN34 3EY",
               "types" : [ "postal_code" ]
            }
         ],
         "formatted_address" : "High St, Hastings TN34 3EY, UK",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 50.8601041,
                  "lng" : 0.5957329
               },
               "southwest" : {
                  "lat" : 50.8559061,
                  "lng" : 0.5906163
               }
            },
            "location" : {
               "lat" : 50.85830319999999,
               "lng" : 0.5924594
            },
            "location_type" : "GEOMETRIC_CENTER",
            "viewport" : {
               "northeast" : {
                  "lat" : 50.8601041,
                  "lng" : 0.5957329
               },
               "southwest" : {
                  "lat" : 50.8559061,
                  "lng" : 0.5906163
               }
            }
         },
         "partial_match" : true,
         "place_id" : "ChIJ-Ws929sa30cRKgsMNVkPyws",
         "types" : [ "route" ]
      }
   ],
   "status" : "OK"
}

Una solicitud de geocódigo para la localidad de "Santa Cruz" con components=country:ES mostrará Santa Cruz de Tenerife en las Islas Canarias, España.

Solicitud:

https://maps.googleapis.com/maps/api/geocode/json?components=locality:santa+cruz|country:ES&key=YOUR_API_KEY

Respuesta:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "Santa Cruz de Tenerife",
               "short_name" : "Santa Cruz de Tenerife",
               "types" : [ "locality", "political" ]
            },
            {
               "long_name" : "Santa Cruz de Tenerife",
               "short_name" : "TF",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "Canary Islands",
               "short_name" : "CN",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "Spain",
               "short_name" : "ES",
               "types" : [ "country", "political" ]
            }
         ],
         "formatted_address" : "Santa Cruz de Tenerife, Spain",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 28.487616,
                  "lng" : -16.2356646
               },
               "southwest" : {
                  "lat" : 28.4280248,
                  "lng" : -16.3370045
               }
            },
            "location" : {
               "lat" : 28.4636296,
               "lng" : -16.2518467
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 28.487616,
                  "lng" : -16.2356646
               },
               "southwest" : {
                  "lat" : 28.4280248,
                  "lng" : -16.3370045
               }
            }
         },
         "place_id" : "ChIJcUElzOzMQQwRLuV30nMUEUM",
         "types" : [ "locality", "political" ]
      }
   ],
   "status" : "OK"
}

El filtrado de componentes muestra una respuesta ZERO_RESULTS solo si proporcionas filtros que se excluyan entre sí.

Solicitud:

https://maps.googleapis.com/maps/api/geocode/json?components=administrative_area:TX|country:FR&key=YOUR_API_KEY

Respuesta:

{
   "results" : [],
   "status" : "ZERO_RESULTS"
}

Puedes hacer consultas válidas sin el parámetro de dirección con el filtro components. (Cuando se geocodifica una dirección completa, se requiere el parámetro address si la solicitud contiene los nombres y números de los edificios).

Solicitud:

https://maps.googleapis.com/maps/api/geocode/json?components=route:Annankatu|administrative_area:Helsinki|country:Finland&key=YOUR_API_KEY

Respuesta:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "Annankatu",
               "short_name" : "Annankatu",
               "types" : [ "route" ]
            },
            {
               "long_name" : "Helsinki",
               "short_name" : "HKI",
               "types" : [ "locality", "political" ]
            },
            {
               "long_name" : "Finland",
               "short_name" : "FI",
               "types" : [ "country", "political" ]
            },
            {
               "long_name" : "00101",
               "short_name" : "00101",
               "types" : [ "postal_code" ]
            }
         ],
         "formatted_address" : "Annankatu, 00101 Helsinki, Finland",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 60.168997,
                  "lng" : 24.9433353
               },
               "southwest" : {
                  "lat" : 60.16226160000001,
                  "lng" : 24.9332897
               }
            },
            "location" : {
               "lat" : 60.1657808,
               "lng" : 24.938451
            },
            "location_type" : "GEOMETRIC_CENTER",
            "viewport" : {
               "northeast" : {
                  "lat" : 60.168997,
                  "lng" : 24.9433353
               },
               "southwest" : {
                  "lat" : 60.16226160000001,
                  "lng" : 24.9332897
               }
            }
         },
         "place_id" : "ChIJARW7C8sLkkYRgl4je4-RPUM",
         "types" : [ "route" ]
      }
   ],
   "status" : "OK"
}