Eso es todo.

Para comenzar a desarrollar, consulta nuestra documentación para desarrolladores.

Activar el Google Places API Web Service

Para que puedas comenzar, te proporcionaremos orientación en la consola para desarrolladores de Google a fin de que hagas primero algunas acciones:

  1. Crear o seleccionar un proyecto
  2. Activar el Google Places API Web Service
  3. Crear claves correspondientes
Continuar

Autocompletado de sitios

El servicio de autocompletado de sitios es un servicio web que devuelve predicciones de sitios en respuesta a una solicitud HTTP. La solicitud especifica una cadena de búsqueda textual y límites geográficos opcionales. El servicio se puede usar para proporcionar la funcionalidad de autocompletado para búsquedas geográficas basadas en texto al devolver sitios como negocios, direcciones y puntos de interés a medida que el usuario escribe.

Solicitudes de autocompletado de sitios

El servicio de autocompletado de sitios forma parte del Google Places API Web Service, y comparte cuotas y una clave de API con Google Places API Web Service.

El servicio de autocompletado de sitios puede encontrar coincidencias con palabras completas y con subcadenas. Por lo tanto, las aplicaciones pueden enviar consultas a medida que el usuario escribe para proporcionar predicciones de sitios en el momento.

Las predicciones devueltas están diseñadas para su presentación al usuario con el fin de ayudarlo en la selección del sitio deseado. Puedes enviar una solicitud de detalles del sitio para obtener más información acerca de cualquiera de los sitios devueltos.

Una solicitud de autocompletado de sitios es una solicitud HTTP URL como la siguiente:

https://maps.googleapis.com/maps/api/place/autocomplete/output?parameters

donde output 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.

Ciertos parámetros son obligatorios para iniciar una solicitud de autocompletado de sitios. Como es norma en las direcciones URL, todos los parámetros se separan con el carácter de Y comercial (&). A continuación, se proporciona una lista de los parámetros y sus posibles valores.

Parámetros obligatorios

  • input: la cadena de texto en la que se realiza la búsqueda. El servicio de autocompletado de sitios devolverá posibles coincidencias en función de esta cadena y ordenará los resultados según la relevancia percibida.
  • 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. Para obtener más información, consulta Obtener una clave. Los clientes de Google Maps API Premium Plan deben usar el proyecto de API creado por ellos como parte de su compra Plan premium.

Parámetros opcionales

  • offset: la posición en el término introducido del último carácter que el servicio utiliza para establecer coincidencias y proporcionar predicciones. Por ejemplo, si se introduce 'Google' y el valor de offset es 3, el servicio comenzará a establecer coincidencias en 'Goo'. Las coincidencias de la cadena determinada por offset se establecen solo para la primera palabra del término introducido. Por ejemplo, si el término introducido es 'Google abc' y el valor de offset es 3, el servicio intentará establecer una coincidencia con 'Goo abc'. Si no se proporciona un valor de offset, el servicio utilizará el término completo. El valor de offset, generalmente, se debe configurar en la posición del símbolo de intercalación.
  • location: el punto alrededor del cual quieres obtener información de sitios. Se debe especificar como latitud,longitud.
  • radius: la distancia (en metros) dentro de la cual obtener resultados de sitios. Ten en cuenta que al establecer un valor de radius, los resultados se restringen para el área indicada, pero es posible que esos resultados no se limiten exclusivamente al área especificada. Consulta Restricción de ubicación y Restricción de ubicación, a continuación.
  • language: el código de idioma, que indica en qué idioma se deben devolver los resultados, si fuera posible. Las búsquedas también están restringidas al idioma seleccionado. Es posible que se les otorgue una clasificación más alta a los resultados en el idioma seleccionado. Consulta la lista de idiomas admitidos y sus códigos. Ten en cuenta que, a menudo, actualizamos los idiomas admitidos, por lo que es posible que esta lista no esté completa. Si no se indica el idioma, el servicio de autocompletado de sitios intentará utilizar el idioma nativo del dominio desde el que se envió la solicitud.
  • types: los tipos de resultados de sitios que se deben devolver. Consulta Tipos de sitios a continuación. Si no se especifica un tipo, se devolverán todos los tipos.
  • components: un conjunto de sitios a los que te gustaría restringir tus resultados. Actualmente, puedes usar components para filtrar por país. El país se debe pasar mediante un código de país de dos caracteres, de acuerdo con la norma ISO 3166-1-Alpha-2. Por ejemplo: components=country:fr limitaría tus resultados a sitios dentro de Francia.
  • strictbounds: muestra solo aquellos sitios que se encuentran estrictamente dentro de la región definida por location y radius. Se trata de una restricción, en lugar de una preferencia, lo que significa que los resultados fuera de esta región no se mostrarán incluso si coinciden con la entrada del usuario.

Restricción de ubicación

Puedes restringir los resultados a un círculo específico al pasar un parámetro location y uno radius. Esto le indica al servicio de autocompletado de sitios que muestre preferentemente los resultados dentro de ese círculo. Es posible que aún se muestren resultados externos al área definida. Puedes usar el parámetro components para filtrar los resultados de modo que solo se muestren los sitios de un país determinado.

Sugerencia: Los resultados de establecimientos, generalmente, no tienen una clasificación lo suficientemente alta como para aparecer en los resultados cuando se utiliza un área de búsqueda amplia. Si quieres que aparezcan establecimientos en los resultados combinados de establecimientos y codificación geográfica, puedes especificar un radio más limitado. También puedes usar types=establishment para limitar los resultados a establecimientos únicamente.

Restricción de ubicación

También puedes restringir los resultados a la región definida por location y un parámetro radius agregando el parámetro strictbounds. De esta manera, se indica al servicio de autocompletado de sitios que muestre solo resultados dentro de la región en cuestión.

Tipos de sitio

Puedes restringir los resultados de una solicitud de autocompletado de sitios a fin de que sean de un tipo en particular al pasar un parámetro types. El parámetro especifica un tipo o un conjunto de tipos, según los tipos admitidos que se indican a continuación. Si no se especifica nada, se devolverán todos los tipos. En general, solo se permite un tipo. Como excepción, puedes combinar con seguridad los tipos geocode y establishment, pero debes tener en cuenta que esto tendrá el mismo efecto que si no especificaras ningún tipo. Los tipos admitidos son los siguientes:

  • geocode le indica al servicio de autocompletado de sitios que devuelva solo resultados de geocodificación, en lugar de resultados de negocios. Puedes usar esta solicitud para eliminar ambigüedades en los resultados en los cuales la ubicación especificada puede ser indeterminada.
  • address le indica al servicio de autocompletado de sitios que devuelva solo resultados de geocodificación con una dirección exacta. Por lo general, puedes usar esta solicitud cuando sabes que el usuario buscará una dirección especificada con precisión.
  • establishment le indica al servicio de autocompletado de sitios que devuelva solo resultados de negocios.
  • El conjunto de tipos (regions) le indica al servicio de Places que devuelva todos los resultados que coincidan con los siguientes tipos:
    • locality
    • sublocality
    • postal_code
    • country
    • administrative_area_level_1
    • administrative_area_level_2
  • el grupo de tipos (cities) le indica al servicio de Places que devuelva resultados que coincidan con locality o administrative_area_level_3.

Ejemplo de solicitudes de autocompletado

Solicitud de establecimientos que contengan la cadena "Amoeba" en un área de San Francisco, CA:

https://maps.googleapis.com/maps/api/place/autocomplete/xml?input=Amoeba&types=establishment&location=37.76999,-122.44696&radius=500&key=YOUR_API_KEY

La misma solicitud, con restricción de resultados a una distancia de hasta 500 metros de Ashbury St & Haight St, San Francisco:

https://maps.googleapis.com/maps/api/place/autocomplete/xml?input=Amoeba&types=establishment&location=37.76999,-122.44696&radius=500&strictbounds&key=YOUR_API_KEY

Solicitud de direcciones que contengan "Vict" con resultados en francés:

https://maps.googleapis.com/maps/api/place/autocomplete/json?input=Vict&types=geocode&language=fr&key=YOUR_API_KEY

Solicitud de ciudades que contengan "Vict" con resultados en portugués de Brasil:

https://maps.googleapis.com/maps/api/place/autocomplete/json?input=Vict&types=(cities)&language=pt_BR&key=YOUR_API_KEY

Ten en cuenta que deberás reemplazar la clave de la API que se indica en estos ejemplos por tu propia clave.

Respuestas de autocompletado de sitios

Las respuestas de autocompletado de sitios se proporcionan en el formato indicado por el marcador output en la ruta de acceso de la dirección URL de la solicitud. Los resultados a continuación indican las posibles devoluciones para una solicitud con los siguientes parámetros:

input=Paris&types=geocode

JSON
{
  "status": "OK",
  "predictions" : [
      {
         "description" : "Paris, France",
         "id" : "691b237b0322f28988f3ce03e321ff72a12167fd",
         "matched_substrings" : [
            {
               "length" : 5,
               "offset" : 0
            }
         ],
         "place_id" : "ChIJD7fiBh9u5kcRYJSMaMOCCwQ",
         "reference" : "CjQlAAAA_KB6EEceSTfkteSSF6U0pvumHCoLUboRcDlAH05N1pZJLmOQbYmboEi0SwXBSoI2EhAhj249tFDCVh4R-PXZkPK8GhTBmp_6_lWljaf1joVs1SH2ttB_tw",
         "terms" : [
            {
               "offset" : 0,
               "value" : "Paris"
            },
            {
               "offset" : 7,
               "value" : "France"
            }
         ],
         "types" : [ "locality", "political", "geocode" ]
      },
      {
         "description" : "Paris Avenue, Earlwood, New South Wales, Australia",
         "id" : "359a75f8beff14b1c94f3d42c2aabfac2afbabad",
         "matched_substrings" : [
            {
               "length" : 5,
               "offset" : 0
            }
         ],
         "place_id" : "ChIJrU3KAHG6EmsR5Uwfrk7azrI",
         "reference" : "CkQ2AAAARbzLE-tsSQPgwv8JKBaVtbjY48kInQo9tny0k07FOYb3Z_z_yDTFhQB_Ehpu-IKhvj8Msdb1rJlX7xMr9kfOVRIQVuL4tOtx9L7U8pC0Zx5bLBoUTFbw9R2lTn_EuBayhDvugt8T0Oo",
         "terms" : [
            {
               "offset" : 0,
               "value" : "Paris Avenue"
            },
            {
               "offset" : 14,
               "value" : "Earlwood"
            },
            {
               "offset" : 24,
               "value" : "New South Wales"
            },
            {
               "offset" : 41,
               "value" : "Australia"
            }
         ],
         "types" : [ "route", "geocode" ]
      },
      {
         "description" : "Paris Street, Carlton, New South Wales, Australia",
         "id" : "bee539812eeda477dad282bcc8310758fb31d64d",
         "matched_substrings" : [
            {
               "length" : 5,
               "offset" : 0
            }
         ],
         "place_id" : "ChIJCfeffMi5EmsRp7ykjcnb3VY",
         "reference" : "CkQ1AAAAAERlxMXkaNPLDxUJFLm4xkzX_h8I49HvGPvmtZjlYSVWp9yUhQSwfsdveHV0yhzYki3nguTBTVX2NzmJDukq9RIQNcoFTuz642b4LIzmLgcr5RoUrZhuNqnFHegHsAjtoUUjmhy4_rA",
         "terms" : [
            {
               "offset" : 0,
               "value" : "Paris Street"
            },
            {
               "offset" : 14,
               "value" : "Carlton"
            },
            {
               "offset" : 23,
               "value" : "New South Wales"
            },
            {
               "offset" : 40,
               "value" : "Australia"
            }
         ],
         "types" : [ "route", "geocode" ]
      },
  ...additional results ...
      
XML
<?xml version="1.0" encoding="UTF-8"?>
<AutocompletionResponse>
 <status>OK</status>
 <prediction>
  <description>Paris, France</description>
  <type>locality</type>
  <type>political</type>
  <type>geocode</type>
  <place_id>ChIJD7fiBh9u5kcRYJSMaMOCCwQ</place_id>
  <reference>CiQRAAAAJm0CiCHIC8C4GOjREdm3QtHYhMyFaUXKWAbGSaZImQ8SECnHAhpcuZaoSr0_TKfeHvwaFHMIq_BmUccTC4mt6EWVNMa67Xuq</reference>
  <id>691b237b0322f28988f3ce03e321ff72a12167fd</id>
  <term>
   <value>Paris</value>
   <offset>0</offset>
  </term>
  <term>
   <value>France</value>
   <offset>7</offset>
  </term>
  <matched_substring>
   <offset>0</offset>
   <length>5</length>
  </matched_substring>
 </prediction>
 <prediction>
  <description>Paris, TX, United States</description>
  <type>colloquial_area</type>
  <type>political</type>
  <type>geocode</type>
  <place_id>ChIJrU3KAHG6EmsR5Uwfrk7azrI</place_id>
  <reference>CiQcAAAArNRoGmiHh0PNVH5LSnJEbT5L7DfUE-APvTfYac9Ta5USEIfAOzXTkqTpioZX9qeevY8aFPgN_H6qcRnGLqPUq4zkOE-_g-ul</reference>
  <id>029556239a911839382f42ec36c5ce2b85be9be3</id>
  <term>
   <value>Paris</value>
   <offset>0</offset>
  </term>
  <term>
   <value>TX</value>
   <offset>7</offset>
  </term>
  <term>
   <value>United States</value>
   <offset>11</offset>
  </term>
  <matched_substring>
   <offset>0</offset>
   <length>5</length>
  </matched_substring>
 </prediction>
 <prediction>
  <description>Paris, Ontario, Canada</description>
  <type>locality</type>
  <type>political</type>
  <type>geocode</type>
  <place_id>ChIJCfeffMi5EmsRp7ykjcnb3VY</place_id>
  <reference>CiQaAAAApuD3Th6N5_EcJjKw0umu_IonagFPBo9idTf7WB8-cw8SEGS5wSvHzhuUvCqPH-uM5B8aFIedLGNSuh5M5eqWdBJCtc0Ibvd0</reference>
  <id>e7ac9c89d4a590305242b0cb5bf43064027223c9</id>
  <term>
   <value>Paris</value>
   <offset>0</offset>
  </term>
  <term>
   <value>Ontario</value>
   <offset>7</offset>
  </term>
  <term>
   <value>Canada</value>
   <offset>16</offset>
  </term>
  <matched_substring>
   <offset>0</offset>
   <length>5</length>
  </matched_substring>
 </prediction>
</AutocompletionResponse>

Una respuesta JSON contiene dos elementos principales:

  • status contiene metadatos sobre la solicitud. Consulta los siguientes códigos de estado.
  • predictions contiene un conjunto de sitios con información acerca del sitio. Consulta Resultados de autocompletado de sitios para obtener información acerca de esos resultados. Google Places API Web Service devuelve hasta cinco resultados.

De particular interés entre los resultados son los elementos place_id, que se pueden usar para solicitar detalles más específicos acerca del sitio mediante una consulta independiente. Consulta Solicitudes de detalles del sitio.

Consulta Procesamiento de JSON con Javascript para obtener ayuda sobre el procesamiento de respuestas JSON.

Una respuesta XML consiste en un único elemento <AutocompletionResponse> con dos tipos de elementos secundarios:

  • Un solo elemento <status> contiene metadatos sobre la solicitud. Consulta los siguientes códigos de estado.
  • Cero o más elementos <prediction>, cada uno con información acerca de un sitio individual. Consulta Resultados de autocompletado de sitios para obtener información acerca de esos resultados. Google Places API Web Service devuelve hasta cinco resultados.

Te recomendamos que uses json como marcador de formato de salida preferido, a menos que tu aplicación requiera xml por algún motivo. El procesamiento de árboles XML requiere de cierto cuidado, ya que debes hacer referencia a los nodos y elementos adecuados. Consulta Procesamiento de XML con XPath para obtener ayuda con el procesamiento de XML.

Códigos de estado

El campo status en el objeto de la respuesta de autocompletado de sitios contiene el estado de la solicitud y podría contener información de depuración para ayudarte a localizar por qué falló la solicitud de autocompletado de sitios. El campo status puede contener los siguientes valores:

  • OK indica que no se produjeron errores y que se devolvió, al menos, un resultado.
  • ZERO_RESULTS indica que la búsqueda fue exitosa, pero no devolvió resultados. Esto puede ocurrir si se pasa un valor bounds para la búsqueda correspondiente a una ubicación remota.
  • OVER_QUERY_LIMIT indica que has excedido tu cuota.
  • REQUEST_DENIED indica que se rechazó tu solicitud, generalmente, debido a un parámetro key no válido.
  • INVALID_REQUEST generalmente indica que falta el parámetro input.

Mensajes de error

Cuando el servicio de Places devuelve un código de estado diferente de OK, podría haber un campo error_message adicional en el objeto de la respuesta. Este campo contiene información más detallada acerca de los motivos que subyacen al código de estado proporcionado.

Resultados de autocompletado de sitios

Cuando el servicio de Places devuelve resultados JSON a partir de una búsqueda, los ubica en un conjunto de predictions. Incluso si el servicio no devuelve resultados (como ocurriría si la location fuera remota), aún devolverá un conjunto de predictions vacío. Las respuestas XML consisten en cero o más elementos <prediction>.

Cada resultado de predicción contiene los siguientes campos:

  • description contiene el nombre del resultado devuelto en lenguaje natural. Para los resultados de establishment, generalmente, se proporciona el nombre comercial.
  • place_id es un identificador textual que identifica de forma exclusiva un sitio. Para recuperar información sobre el sitio, pasa este identificador en el campo placeid de una solicitud de Google Places API Web Service. Para obtener más información sobre los id. de sitio, consulta la información general sobre id. de sitio.
  • reference contiene un token único que puedes usar para recuperar información adicional acerca del sitio en una solicitud de detalles del sitio. Si bien este token identifica de forma exclusiva al sitio, no ocurre lo mismo de forma inversa. Un sitio puede tener muchos tokens de referencia válidos. No se garantiza que se devolverá el mismo token para un sitio determinado en diferentes búsquedas. Nota: reference ha quedado en desuso en favor de place_id. Consulta el aviso sobre desuso en esta página.
  • id contiene un identificador estable y único que designa el sitio. Este identificador no se puede usar para recuperar información acerca del sitio, pero sí para consolidar datos acerca del sitio y verificar la identidad de un sitio entre búsquedas independientes. Nota: id ha quedado en desuso en favor de place_id. Consulta el aviso sobre desuso en esta página.
  • terms contiene un conjunto de términos que identifican a cada sección de la descripción devuelta (las secciones de la descripción generalmente terminan en una coma). Cada una de las entradas del conjunto posee un campo value que contiene el texto del término y un campo offset que define la posición inicial de ese término en la descripción medida en caracteres Unicode.
  • types contiene un conjunto de tipos que pueden aplicarse a ese sitio. Por ejemplo: [ "political", "locality" ] o [ "establishment", "geocode" ].
  • matched_substrings contiene un conjunto con el valor offset y length. Estos valores describen la ubicación del término introducido en el texto del resultado de predicción, por lo que es posible resaltar el término si así lo deseas.

El parámetro sensor

Antes, Google Places API Web Service requería que incluyeras el parámetro sensor para indicar si tu aplicación usaba un sensor para determinar la ubicación del usuario. El uso de este parámetro ya no es obligatorio.

Enviar comentarios sobre...