Búsqueda de sitios

Google Places API Web Service se debe usar en aplicaciones de servidor. Si estás generando una aplicación del lado del cliente, échale un vistazo a Google Places API for Android y Biblioteca de sitios en Google Maps JavaScript API.

El Google Places API Web Service te permite consultar información sobre sitios en una variedad de categorías, como establecimientos, puntos de interés importantes, ubicaciones geográficas, etc. Puedes buscar sitios por proximidad o una cadena de texto. Una búsqueda de sitios devuelve una lista de sitios junto con información resumida sobre cada sitio. La información adicional está disponible mediante la consulta de Detalles del sitio.

1. Solicitudes de búsquedas de sitios cercanos
2. Solicitudes de búsquedas de texto
3. Solicitudes de búsquedas por radar
4. Respuestas de búsqueda
   • Resultados de búsqueda
   • Acceso a resultados adicionales

Solicitudes de búsquedas de sitios cercanos

Las versiones anteriores de la Places API hacían referencia a la búsqueda de sitios cercanos como la búsqueda de sitios.

Una búsqueda de sitios cercanos te permite buscar sitios dentro de un área específica. Puedes perfeccionar tu solicitud de búsqueda si proporcionas palabras clave o especificas el tipo de sitio que estás buscando.

Una solicitud de búsqueda de sitios cercanos es una HTTP URL como la siguiente:

https://maps.googleapis.com/maps/api/place/nearbysearch/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 búsqueda de sitios cercanos. Como es norma en las direcciones URL, todos los parámetros se separan con el carácter de Y comercial (&).

Parámetros obligatorios

• 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 y permite que los sitios agregados desde tu aplicación estén inmediatamente disponibles en ella. Visita Google Developers Console para crear un proyecto de API y obtener tu clave.
• location: la latitud o la longitud alrededor de las cuales se debe obtener información sobre sitios. Esto se debe especificar como latitud,longitud.
• radius: define la distancia (en metros) dentro de la cual obtener resultados de sitios. El radio máximo permitido es de 50 000 metros. Ten en cuenta que el radius no se debe incluir si se especifica rankby=distance (descrito en Parámetros opcionales a continuación).
• Si se especifica rankby=distance (descrito en Parámetros opcionales a continuación), se requiere uno o más parámetros keyword, name o types.

Parámetros opcionales

• keyword: un término para coincidir con todo el contenido que Google indexó para este sitio, incluso, entre otros, nombre, tipo y dirección, como así también revisiones del cliente y otro contenido de terceros.
• language: el código de idioma, que indica en qué idioma se deben devolver los resultados, si fuera posible. 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.
• minprice y maxprice (opcional): restringe los resultados a solo dichos sitios dentro del rango especificado. Rango de valores válidos entre 0 (más asequible) y 4 (más costoso), inclusive. La cantidad exacta indicada por un valor específico variará según la región.
• name: uno o más términos para coincidir con los nombres de los sitios, separados por un carácter de espacio. Los resultados se restringirán a los que contienen los valores name aprobados. Ten en cuenta que un sitio puede tener nombres adicionales asociados, más allá de su nombre indicado. La API intentará hacer coincidir el valor del nombre aprobado con todos los de estos nombres. Como consecuencia, los sitios se pueden devolver en los resultados cuyos nombres indicados no coinciden con el término de búsqueda, pero cuyos nombres asociados sí coinciden.
• opennow: devuelve solo los sitios que están abiertos en el momento en que se envía la consulta. Los sitios que no especifican los horarios de apertura en la base de datos de Google Places no se devolverán si incluyes este parámetro en tu consulta.
• rankby: especifica el orden en el que se indican los resultados. Los posibles valores son los siguientes:
  • prominence (valor predeterminado). Esta opción clasifica los resultados según su importancia. La clasificación favorecerá los sitios importantes dentro del área especificada. La importancia se puede ver afectada por la clasificación de un sitio en el índice de Google, la popularidad global y otros factores.
  • distance. Esta opción clasifica los resultados en orden ascendente por su distancia desde la location especificada. Cuando se especifica el parámetro distance, se requiere uno o más parámetros keyword, name o types.
• types: restringe los resultados a sitios que coinciden, al menos, con uno de los tipos especificados. Los tipos se deben separar con una barra vertical (type1|type2|etc). Consulta la lista de tipos admitidos.
• pagetoken: devuelve los próximos 20 resultados de una búsqueda ejecutada previamente. Establecer un parámetro pagetoken ejecutará una búsqueda con los mismos parámetros usados previamente; se ignorarán todos los parámetros que no sean pagetoken.
• zagatselected: agrega este parámetro (solo el nombre del parámetro, sin valor asociado) para restringir tu búsqueda a las ubicaciones que sean negocios seleccionados por Zagat. Este parámetro no debe incluir un valor true o false. El parámetro zagatselected es experimental y solo está disponible para los clientes de Google Places API for Work.

Los clientes de la Maps API for Work no deben incluir un parámetro client o signature con sus solicitudes.

El siguiente ejemplo es una solicitud de búsqueda de sitios de tipo “alimentos” en un radio de 500 m desde un punto determinado en Sidney, Australia, que contengan la palabra “crucero” en su nombre:

https://maps.googleapis.com/maps/api/place/nearbysearch/json?location=-33.8670522,151.1957362&radius=500&types=food&name=cruise&key=YOUR_API_KEY

Para que la solicitud funcione en tu aplicación, deberás reemplazar la clave que se indica en este ejemplo por tu clave.

Solicitudes de búsquedas de texto

El servicio de búsqueda de texto de la Google Places API es un servicio web que devuelve información sobre un conjunto de sitios basados en una cadena; por ejemplo "pizza en Nueva York" o "tiendas de zapatos cerca de Ottawa". El servicio responde con una lista de sitios que coinciden con la cadena de texto y cualquier restricción de ubicación que se haya enviado. En la respuesta de la búsqueda se incluirá una lista de sitios; puedes enviar una solicitud de detalles del sitio para obtener más información acerca de cualquiera de los sitios en la respuesta.

Los servicios de búsqueda de Google Places comparten los mismos límites de uso. Sin embargo, el servicio de búsqueda de texto está sujeto a un multiplicador de 10 veces. Es decir, cada solicitud de búsqueda de texto que realices contará como 10 solicitudes que se descontarán de tu cuota. Si compraste la Google Places API como parte de tu contrato de la Google Maps API for Work, es posible que el multiplicador sea diferente. Para obtener más detalles, consulta la documentación de la Google Maps API for Work.

Una solicitud de búsqueda de texto es una HTTP URL como la siguiente:

https://maps.googleapis.com/maps/api/place/textsearch/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 búsqueda. Como es norma en las direcciones URL, todos los parámetros se separan con el carácter de Y comercial (&).

Parámetros obligatorios

• query: la cadena de texto en la que se realiza la búsqueda; por ejemplo, “restaurante”. El servicio de Google Places 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 y permite que los sitios agregados desde tu aplicación estén inmediatamente disponibles en ella. Visita Google Developers Console para crear un proyecto de API y obtener tu clave.

Parámetros opcionales

• location: la latitud o la longitud alrededor de las cuales se debe obtener información sobre sitios. Esto se debe especificar como latitud,longitud. Si especificas un parámetro location, también debes especificar un parámetro radius.
• radius: define la distancia (en metros) dentro de la cual restringir los resultados de sitios. El radio máximo permitido es de 50 000 metros. Los resultados dentro de esta región se clasificarán en un nivel superior que los resultados externos al círculo de búsqueda. Sin embargo, los resultados importantes externos al radio de búsqueda se pueden incluir.
• language: el código de idioma, que indica en qué idioma se deben devolver los resultados, si fuera posible. 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.
• minprice y maxprice (opcional): restringe los resultados solo a los sitios dentro del nivel de precio especificado. Los valores válidos se encuentran en el rango que varía de 0 (más asequible) a 4 (más costoso), inclusive. La cantidad exacta indicada por un valor específico variará según la región.
• opennow: devuelve solo los sitios que están abiertos en el momento en que se envió la consulta. Los sitios que no especifican los horarios de apertura en la base de datos de Google Places no se devolverán si incluyes este parámetro en tu consulta.
• types: restringe los resultados a sitios que coinciden, al menos, con uno de los tipos especificados. Los tipos se deben separar con una barra vertical (type1|type2|etc). Consulta la lista de tipos admitidos.
• pagetoken: devuelve los próximos 20 resultados de una búsqueda ejecutada previamente. Establecer un parámetro pagetoken ejecutará una búsqueda con los mismos parámetros usados previamente; se ignorarán todos los parámetros que no sean pagetoken.
• zagatselected: agrega este parámetro (solo el nombre del parámetro, sin valor asociado) para restringir tu búsqueda a las ubicaciones que sean negocios seleccionados por Zagat. Este parámetro no debe incluir un valor true o false. El parámetro zagatselected es experimental y solo está disponible para los clientes de Google Places API for Work.

Puedes restringir los resultados a un círculo específico al pasar un parámetro location y uno radius. Esto le indicará al servicio de Google Places que muestre preferentemente los resultados dentro de ese círculo. Es posible que aún se muestren resultados externos al área definida.

Los clientes de la Maps API for Work no deben incluir un parámetro client o signature con sus solicitudes.

Los siguientes ejemplos muestran una búsqueda de restaurantes cerca de Sydney.

https://maps.googleapis.com/maps/api/place/textsearch/xml?query=restaurants+in+Sydney&key=YOUR_API_KEY

Para que la solicitud funcione en tu aplicación, deberás reemplazar la clave que se indica en este ejemplo por tu clave.

Solicitudes de búsquedas por radar

El servicio de búsqueda por radar de la Google Places API te permite buscar hasta 200 sitios a la vez, pero con menos detalles que los que, generalmente, se devuelven de una solicitud de búsqueda de texto o de búsqueda de sitios cercanos. Con la búsqueda por radar, puedes crear aplicaciones que ayuden a los usuarios a identificar áreas específicas de interés dentro de un área geográfica.

La respuesta de búsqueda incluirá hasta 200 sitios y solo la siguiente información sobre cada sitio:

• El campo geometry contiene coordenadas geográficas.
• El campo place_id, que puedes usar en una solicitud de detalles de sitios para obtener información sobre el sitio. Para obtener más información sobre los id. de sitio, consulta la información general sobre id. de sitio.
• El campo reference en desuso. Consulta el aviso sobre desuso en esta página.

Una solicitud de búsqueda por radar es una HTTP URL como la siguiente:

https://maps.googleapis.com/maps/api/place/radarsearch/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 búsqueda. Como es norma en las direcciones URL, todos los parámetros se separan con el carácter de Y comercial (&).

Parámetros obligatorios

• 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 y permite que los sitios agregados desde tu aplicación estén inmediatamente disponibles en ella. Visita Google Developers Console para crear un proyecto de API y obtener tu clave.
• location: la latitud o la longitud alrededor de las cuales se debe obtener información sobre sitios. Esto se debe especificar como latitud,longitud.
• radius: define la distancia (en metros) dentro de la cual obtener resultados de sitios. El radio máximo permitido es de 50 000 metros.
• Una solicitud de búsqueda por radar debe incluir, al menos, uno de los parámetros keyword, name o types.

Parámetros opcionales

• keyword: un término para coincidir con todo el contenido que Google indexó para este sitio, incluso, entre otros, nombre, tipo y dirección, como así también revisiones del cliente y otro contenido de terceros.
• minprice y maxprice (opcional): restringe los resultados solo a los sitios dentro del nivel de precio especificado. Los valores válidos se encuentran en el rango que varía de 0 (más asequible) a 4 (más costoso), inclusive. La cantidad exacta indicada por un valor específico variará según la región.
• name: uno o más términos para coincidir con los nombres de los sitios, separados por un carácter de espacio. Los resultados se restringirán a los que contienen los valores name aprobados. Ten en cuenta que un sitio puede tener nombres adicionales asociados, más allá de su nombre indicado. La API intentará hacer coincidir el valor del nombre aprobado con todos los de estos nombres. Como consecuencia, los sitios se pueden devolver en los resultados cuyos nombres indicados no coinciden con el término de búsqueda, pero cuyos nombres asociados sí coinciden.
• opennow: devuelve solo los sitios que están abiertos en el momento en que se envía la consulta. Los sitios que no especifican los horarios de apertura en la base de datos de Google Places no se devolverán si incluyes este parámetro en tu consulta.
• types: restringe los resultados a sitios que coinciden, al menos, con uno de los tipos especificados. Los tipos se deben separar con una barra vertical (type1|type2|etc). Consulta la lista de tipos admitidos.
• zagatselected: agrega este parámetro (solo el nombre del parámetro, sin valor asociado) para restringir tu búsqueda a las ubicaciones que sean negocios seleccionados por Zagat. Este parámetro no debe incluir un valor true o false. El parámetro zagatselected es experimental y solo está disponible para los clientes de Google Places API for Work.

Los clientes de la Maps API for Work no deben incluir un parámetro client o signature con sus solicitudes.

El ejemplo a continuación devuelve una lista de museos cerca de Londres, Inglaterra.

https://maps.googleapis.com/maps/api/place/radarsearch/json?location=51.503186,-0.126446&radius=5000&types=museum&key=YOUR_API_KEY

Mediante el uso de una combinación de los parámetros keyword, name y types, puedes realizar consultas más precisas. El ejemplo a continuación muestra restaurantes y cafés en París que los usuarios describieron como vegetarianos.

https://maps.googleapis.com/maps/api/place/radarsearch/json?location=48.859294,2.347589&radius=5000&types=food|cafe&keyword=vegetarian&key=YOUR_API_KEY

Para que la solicitud funcione en tu aplicación, deberás reemplazar la clave que se indica en estos ejemplos por tu clave.

Respuestas de búsqueda

Las respuestas de búsquedas se devuelven en el formato indicado por el marcador output en la ruta de acceso de la dirección URL de la solicitud.

El siguiente ejemplo muestra una respuesta de la búsqueda de sitios cercanos. Una respuesta de búsqueda de texto es similar, excepto que devuelve una propiedad de formatted_address en lugar de una de vicinity. Una búsqueda por radar incluye solo campos limitados, como se describió anteriormente.

{
   "html_attributions" : [],
   "results" : [
      {
         "geometry" : {
            "location" : {
               "lat" : -33.870775,
               "lng" : 151.199025
            }
         },
         "icon" : "http://maps.gstatic.com/mapfiles/place_api/icons/travel_agent-71.png",
         "id" : "21a0b251c9b8392186142c798263e289fe45b4aa",
         "name" : "Rhythmboat Cruises",
         "opening_hours" : {
            "open_now" : true
         },
         "photos" : [
            {
               "height" : 270,
               "html_attributions" : [],
               "photo_reference" : "CnRnAAAAF-LjFR1ZV93eawe1cU_3QNMCNmaGkowY7CnOf-kcNmPhNnPEG9W979jOuJJ1sGr75rhD5hqKzjD8vbMbSsRnq_Ni3ZIGfY6hKWmsOf3qHKJInkm4h55lzvLAXJVc-Rr4kI9O1tmIblblUpg2oqoq8RIQRMQJhFsTr5s9haxQ07EQHxoUO0ICubVFGYfJiMUPor1GnIWb5i8",
               "width" : 519
            }
         ],
         "place_id" : "ChIJyWEHuEmuEmsRm9hTkapTCrk",
         "scope" : "GOOGLE",
         "alt_ids" : [
            {
               "place_id" : "D9iJyWEHuEmuEmsRm9hTkapTCrk",
               "scope" : "APP"
            }
         ],
         "reference" : "CoQBdQAAAFSiijw5-cAV68xdf2O18pKIZ0seJh03u9h9wk_lEdG-cP1dWvp_QGS4SNCBMk_fB06YRsfMrNkINtPez22p5lRIlj5ty_HmcNwcl6GZXbD2RdXsVfLYlQwnZQcnu7ihkjZp_2gk1-fWXql3GQ8-1BEGwgCxG-eaSnIJIBPuIpihEhAY1WYdxPvOWsPnb2-nGb6QGhTipN0lgaLpQTnkcMeAIEvCsSa0Ww",
         "types" : [ "travel_agency", "restaurant", "food", "establishment" ],
         "vicinity" : "Pyrmont Bay Wharf Darling Dr, Sydney"
      },
      {
         "geometry" : {
            "location" : {
               "lat" : -33.866891,
               "lng" : 151.200814
            }
         },
         "icon" : "http://maps.gstatic.com/mapfiles/place_api/icons/restaurant-71.png",
         "id" : "45a27fd8d56c56dc62afc9b49e1d850440d5c403",
         "name" : "Private Charter Sydney Habour Cruise",
         "photos" : [
            {
               "height" : 426,
               "html_attributions" : [],
               "photo_reference" : "CnRnAAAAL3n0Zu3U6fseyPl8URGKD49aGB2Wka7CKDZfamoGX2ZTLMBYgTUshjr-MXc0_O2BbvlUAZWtQTBHUVZ-5Sxb1-P-VX2Fx0sZF87q-9vUt19VDwQQmAX_mjQe7UWmU5lJGCOXSgxp2fu1b5VR_PF31RIQTKZLfqm8TA1eynnN4M1XShoU8adzJCcOWK0er14h8SqOIDZctvU",
               "width" : 640
            }
         ],
         "place_id" : "ChIJqwS6fjiuEmsRJAMiOY9MSms",
         "scope" : "GOOGLE",
         "reference" : "CpQBhgAAAFN27qR_t5oSDKPUzjQIeQa3lrRpFTm5alW3ZYbMFm8k10ETbISfK9S1nwcJVfrP-bjra7NSPuhaRulxoonSPQklDyB-xGvcJncq6qDXIUQ3hlI-bx4AxYckAOX74LkupHq7bcaREgrSBE-U6GbA1C3U7I-HnweO4IPtztSEcgW09y03v1hgHzL8xSDElmkQtRIQzLbyBfj3e0FhJzABXjM2QBoUE2EnL-DzWrzpgmMEulUBLGrtu2Y",
         "types" : [ "restaurant", "food", "establishment" ],
         "vicinity" : "Australia"
      },
      {
         "geometry" : {
            "location" : {
               "lat" : -33.870943,
               "lng" : 151.190311
            }
         },
         "icon" : "http://maps.gstatic.com/mapfiles/place_api/icons/restaurant-71.png",
         "id" : "30bee58f819b6c47bd24151802f25ecf11df8943",
         "name" : "Bucks Party Cruise",
         "opening_hours" : {
            "open_now" : true
         },
         "photos" : [
            {
               "height" : 600,
               "html_attributions" : [],
               "photo_reference" : "CnRnAAAA48AX5MsHIMiuipON_Lgh97hPiYDFkxx_vnaZQMOcvcQwYN92o33t5RwjRpOue5R47AjfMltntoz71hto40zqo7vFyxhDuuqhAChKGRQ5mdO5jv5CKWlzi182PICiOb37PiBtiFt7lSLe1SedoyrD-xIQD8xqSOaejWejYHCN4Ye2XBoUT3q2IXJQpMkmffJiBNftv8QSwF4",
               "width" : 800
            }
         ],
         "place_id" : "ChIJLfySpTOuEmsRsc_JfJtljdc",
         "scope" : "GOOGLE",
         "reference" : "CoQBdQAAANQSThnTekt-UokiTiX3oUFT6YDfdQJIG0ljlQnkLfWefcKmjxax0xmUpWjmpWdOsScl9zSyBNImmrTO9AE9DnWTdQ2hY7n-OOU4UgCfX7U0TE1Vf7jyODRISbK-u86TBJij0b2i7oUWq2bGr0cQSj8CV97U5q8SJR3AFDYi3ogqEhCMXjNLR1k8fiXTkG2BxGJmGhTqwE8C4grdjvJ0w5UsAVoOH7v8HQ",
         "types" : [ "restaurant", "food", "establishment" ],
         "vicinity" : "37 Bank St, Pyrmont"
      },
      {
         "geometry" : {
            "location" : {
               "lat" : -33.867591,
               "lng" : 151.201196
            }
         },
         "icon" : "http://maps.gstatic.com/mapfiles/place_api/icons/travel_agent-71.png",
         "id" : "a97f9fb468bcd26b68a23072a55af82d4b325e0d",
         "name" : "Australian Cruise Group",
         "opening_hours" : {
            "open_now" : true
         },
         "photos" : [
            {
               "height" : 242,
               "html_attributions" : [],
               "photo_reference" : "CnRnAAAABjeoPQ7NUU3pDitV4Vs0BgP1FLhf_iCgStUZUr4ZuNqQnc5k43jbvjKC2hTGM8SrmdJYyOyxRO3D2yutoJwVC4Vp_dzckkjG35L6LfMm5sjrOr6uyOtr2PNCp1xQylx6vhdcpW8yZjBZCvVsjNajLBIQ-z4ttAMIc8EjEZV7LsoFgRoU6OrqxvKCnkJGb9F16W57iIV4LuM",
               "width" : 200
            }
         ],
         "place_id" : "ChIJrTLr-GyuEmsRBfy61i59si0",
         "scope" : "GOOGLE",
         "reference" : "CoQBeQAAAFvf12y8veSQMdIMmAXQmus1zqkgKQ-O2KEX0Kr47rIRTy6HNsyosVl0CjvEBulIu_cujrSOgICdcxNioFDHtAxXBhqeR-8xXtm52Bp0lVwnO3LzLFY3jeo8WrsyIwNE1kQlGuWA4xklpOknHJuRXSQJVheRlYijOHSgsBQ35mOcEhC5IpbpqCMe82yR136087wZGhSziPEbooYkHLn9e5njOTuBprcfVw",
         "types" : [ "travel_agency", "restaurant", "food", "establishment" ],
         "vicinity" : "32 The Promenade, King Street Wharf 5, Sydney"
      }
   ],
   "status" : "OK"
}

<?xml version="1.0" encoding="UTF-8"?>
<PlaceSearchResponse>
 <status>OK</status>
 <result>
  <name>Rhythmboat Cruises</name>
  <vicinity>Pyrmont Bay Wharf Darling Dr, Sydney</vicinity>
  <type>travel_agency</type>
  <type>restaurant</type>
  <type>food</type>
  <type>establishment</type>
  <geometry>
   <location>
    <lat>-33.8707750</lat>
    <lng>151.1990250</lng>
   </location>
  </geometry>
  <icon>http://maps.gstatic.com/mapfiles/place_api/icons/travel_agent-71.png</icon>
  <place_id>ChIJyWEHuEmuEmsRm9hTkapTCrk</place_id>
  <scope>GOOGLE</scope>
  <alt_ids>
   <place_id>D9iJyWEHuEmuEmsRm9hTkapTCrk</place_id>
   <scope>APP</scope>
  </alt_ids>
  <reference>CoQBdAAAAChhtoQX_467esHavS0Sj9DrY306W3_uDXKmB2us8Eh7_dX7rDuln18i_uqocF_LmzRptuFr6WZs7aeBSLFq8VFmckxFjsXDaqMdd3gvxi_5dIwPTEugQQYG9oJA-YnYfPBvjGtuoMfNnjyU2GuxGRmJjCO77pEAbsTLq44eBG5jEhAvkKHCGqIzqgC9tdOb1dSqGhRA1hhG4pvILD5OEAq6W8L8sXbkug</reference>
  <id>21a0b251c9b8392186142c798263e289fe45b4aa</id>
  <opening_hours>
   <open_now>true</open_now>
  </opening_hours>
  <photo>
   <photo_reference>CnRnAAAAiRA8ls6lx5LTfLuHJtLYvz73LXIMa5EVsHz2OUjh70LBPBnIEULZ57w076gOuyCeJqP041_v-ek3I5C4IkqW7YgA0EBybwywfIcUXsj5W_qiJR2yaXHXI-FmDM6j1zaS0sJQnNJhe4Bl9W42Jx16phIQRmNOWKGIemKLgzNEPcCnmBoUGgr0gWQBwWd8HAseR-5ie3JYuIM</photo_reference>
   <width>519</width>
   <height>270</height>
  </photo>
 </result>
 <result>
  <name>Private Charter Sydney Habour Cruise</name>
  <vicinity>Australia</vicinity>
  <type>restaurant</type>
  <type>food</type>
  <type>establishment</type>
  <geometry>
   <location>
    <lat>-33.8668910</lat>
    <lng>151.2008140</lng>
   </location>
  </geometry>
  <icon>http://maps.gstatic.com/mapfiles/place_api/icons/restaurant-71.png</icon>
  <place_id>ChIJqwS6fjiuEmsRJAMiOY9MSms</place_id>
  <scope>GOOGLE</scope>
  <reference>CpQBhQAAAKGKrbbnAW3_eAypKW9bhAzAuSmaqAogs7MTFxsntDqCzt-gKD9nz-zqNsk0uJsl0yCUYpNYjHz_yzmh3J_4TTxpxIqdaq2uDvfoTYtvm8FkxMAkK3cS7k9t3Ze2aHRWnxlN9hczK2xlc5taDE7xAGOHF5Xe5IlVV1wV66sOrWrlHtGh47lqT9Id86eG2OmlVhIQo4djLtRkceg-zaYjULYEjRoUToVEyOUVCFfZMUs_E7ZLSzjFmcg</reference>
  <id>45a27fd8d56c56dc62afc9b49e1d850440d5c403</id>
  <photo>
   <photo_reference>CnRnAAAAUW97jpK2_C2Lh4jLPVKZlhyS84mqZxvVmWFdc6jdl3XxjzKbYdbJpz0PGW5eFRw6kTKYNZM9QvRf-csFegHILZxLCLJ-6ZnbdEXbVM4kBzOb-rhchJx1KC6LHs_vVWP8bK96569lFYRf7Hn8ylQrlhIQb69_dcZVwqQhREsHW6azWhoU0XMWqZMBBzx-hgpduAaeErOFg8E</photo_reference>
   <width>640</width>
   <height>426</height>
  </photo>
 </result>
 <result>
  <name>Bucks Party Cruise</name>
  <vicinity>37 Bank St, Pyrmont</vicinity>
  <type>restaurant</type>
  <type>food</type>
  <type>establishment</type>
  <geometry>
   <location>
    <lat>-33.8709430</lat>
    <lng>151.1903110</lng>
   </location>
  </geometry>
  <icon>http://maps.gstatic.com/mapfiles/place_api/icons/restaurant-71.png</icon>
  <place_id>ChIJLfySpTOuEmsRsc_JfJtljdc</place_id>
  <scope>GOOGLE</scope>
  <reference>CoQBdAAAAOMUoYamsekTDxBDVyKZ-E54VQ6HjirVzAZBBwz5gcn5KTfmemmwmOAtLcvRScp1NLQmj-fBYzEO2Gq_cO4Dc12PG0_twzDv9zq3KIyNQVuO-r0n1eQVj8Dlng-n4c1F2hMxufCNVp4-QfjMj81qXJm0invQMUc1xNgZRyiOpLe9EhDLn0KiVWEFKOURYsWrHRouGhR7YMJxYmFs-OXjKyzQKGdQXLrzPw</reference>
  <id>30bee58f819b6c47bd24151802f25ecf11df8943</id>
  <opening_hours>
   <open_now>true</open_now>
  </opening_hours>
  <photo>
   <photo_reference>CnRnAAAAjboYP9Ujxe5SmZFN5AJc42AWtpYFX9wYdqjcTXavXJlfoXdHPC2hErdbHcaeYJBNPV6CzoDc2RLw_w9HofGOhCWHtoAl9b3g8TZZjnZobnAHxoljUdgV8PXyd-pCO-QHKOtiKfIdUmF4HRj2QHj6OhIQhLNpoKNKP8MNjk90M4KGrhoUW2NyBgsWjRpUEoWlt0fD48BhEcQ</photo_reference>
   <width>800</width>
   <height>600</height>
  </photo>
 </result>
 <result>
  <name>Australian Cruise Group</name>
  <vicinity>32 The Promenade, King Street Wharf 5, Sydney</vicinity>
  <type>travel_agency</type>
  <type>restaurant</type>
  <type>food</type>
  <type>establishment</type>
  <geometry>
   <location>
    <lat>-33.8675910</lat>
    <lng>151.2011960</lng>
   </location>
  </geometry>
  <icon>http://maps.gstatic.com/mapfiles/place_api/icons/travel_agent-71.png</icon>
  <place_id>ChIJrTLr-GyuEmsRBfy61i59si0</place_id>
  <scope>GOOGLE</scope>
  <reference>CoQBeAAAAJZA0WY2pKnZ6nNnxNd_pSDA2NilDLfGDf7pTt7VssxB5tMYE7400w3HZHRav2unpKRhEp7lrh0yKcVdSfKYIz85k1SExoLGmYD8NIf1dPr8KlkRWOYZUTLGp623r5hAzEGk94mPleF4s50pWqLrhAzwvJb1tGj2ak-2PXQORkeTEhAfTj6tMFo_tRWZYOnYCxiVGhQA3n-KV7AW5MvJlGaIDHuLyyEBBA</reference>
  <id>a97f9fb468bcd26b68a23072a55af82d4b325e0d</id>
  <opening_hours>
   <open_now>true</open_now>
  </opening_hours>
  <photo>
   <photo_reference>CnRnAAAAhTkpwozMoZx_NXMkIrKdcEGe46BmPy3GPCfS-gkCK5PlR8rFDY9DtD_7wFYAIdhVoZz3I9QguRNbil5y37jTU-03GJ_LqVw_avSxFkT0g2kU0K5z2VYnAsgNsrbsK_EVglhg5PrDybC1tAVKCXSGsRIQOcdlAVnC1Qc46YLWjlqdyxoUL5JGZgczfo1jxLxhDeGs8OvBQCk</photo_reference>
   <width>200</width>
   <height>242</height>
  </photo>
 </result>
</PlaceSearchResponse>

Códigos de estado

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

• OK indica que no se produjeron errores, que el sitio se detectó satisfactoriamente 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 latlng 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 está faltando un parámetro de consulta obligatorio (location o radius).

Mensajes de error

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

Resultados de búsqueda

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

Cada elemento del conjunto de results contiene un solo resultado del área especificada (location y radius), ordenado por importancia.

El resultado también puede contener información sobre atribuciones, que se le debe mostrar al usuario. Este es un ejemplo de una atribución en el formato JSON:

"html_attributions" : [
      "Listings by \u003ca href=\"http://www.example.com/\"\u003eExample Company\u003c/a\u003e"
],

<html_attribution>Listings by <a href="http://www.example.com/">Example Company</a></html_attribution>

Cada resultado dentro del conjunto de results puede contener los siguientes campos:

• icon contiene la dirección URL de un icono recomendado que podría mostrarse al usuario al indicar este resultado.
• id contiene un identificador estable y único que designa el sitio. No se puede usar este identificador para recuperar información sobre el sitio, pero se garantiza que es válido en todas las sesiones. Se puede usar para consolidar datos acerca del sitio y para 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.
• geometry contiene información de geometría sobre el resultado, que generalmente incluye el parámetro location (geocódigo) del sitio y (opcionalmente) viewport, que identifica su área general de cobertura.
• name contiene el nombre del resultado devuelto en lenguaje natural. Para los resultados de establishment, generalmente, se proporciona el nombre comercial.
• opening_hours puede contener la siguiente información:
  • open_now es un valor booleano que indica si el sitio está abierto en ese momento.
• photos[]: un conjunto de objetos de photo, cada uno con una referencia a una imagen. Una búsqueda de sitios devolverá, a lo sumo, un objeto de photo. Una solicitud de detalles del sitio en el sitio puede devolver hasta diez fotos. Puedes encontrar más información acerca de las fotos de sitios y cómo usar imágenes en tu aplicación en la documentación de Fotos de sitios. Un objeto photo se describe de la siguiente manera:
  • photo_reference: cadena utilizada para identificar la foto cuando realizas una solicitud de foto.
  • height: la altura máxima de la imagen.
  • width: el ancho máximo de la imagen.
  • html_attributions[]: contiene las atribuciones requeridas. Este campo estará siempre presente, pero puede estar vacío.
• place_id: 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 la Places API. Para obtener más información sobre los id. de sitio, consulta la información general sobre id. de sitio.
• scope: indica el ámbito de place_id. Los posibles valores son los siguientes:
  • APP: solo tu aplicación reconoce el id. de sitio. Esto se debe a que agregaste un sitio a través de tu aplicación, y ese sitio aún no aprobó el proceso de moderación.
  • GOOGLE: el id. de sitio está disponible para otras aplicaciones y en Google Maps.
  Nota: El campo scope se incluye solo en los resultados de búsqueda de sitios cercanos y en los resultados de detalles del sitio. Solo puedes recuperar sitios para el ámbito de la aplicación mediante las solicitudes de búsquedas de sitios cercanos y detalles del sitio. Si el campo scope no está presente en una respuesta, es seguro asumir que el ámbito es GOOGLE.
• alt_ids: Un conjunto de cero, uno o más id. de sitio alternativos para el sitio, con un ámbito relacionado con cada id. alternativo. Nota: Este conjunto puede estar vacío o no aparecer. Si está presente, contendrá los siguientes campos:
  • place_id: el motivo más probable por el que un sitio puede contener un id. de sitio alternativo es que tu aplicación agregue un sitio y reciba un id. de sitio para el ámbito de la aplicación y que, luego de aprobar el proceso de moderación, reciba un id. de sitio para el ámbito de Google.
  • scope: el ámbito de un id. de sitio alternativo siempre será APP, lo que indica que solo tu aplicación reconoce el id. de sitio alternativo.
  Por ejemplo, supongamos que, a través de tu aplicación, agregas un sitio y recibes un place_id de AAA para el sitio nuevo. Más adelante, el sitio aprueba el proceso de moderación y se le otorga un place_id de BBB para el ámbito de Google. Desde ese momento, la información para ese sitio contendrá lo siguiente:

      "results" : [
        {
          "place_id" : "BBB",
          "scope" : "GOOGLE",
          "alt_ids" : [
            {
              "place_id" : "AAA",
              "scope" : "APP",
            }
          ],
        }
      ]
      

• price_level: el nivel de precios del sitio en una escala de 0 a 4. La cantidad exacta indicada por un valor específico variará según la región. Los niveles de precios se interpretan de la siguiente manera:
  • 0: gratis
  • 1: barato
  • 2: moderado
  • 3: caro
  • 4: muy caro
• rating contiene la clasificación del sitio, de 1,0 a 5,0, según las reseñas de usuarios agregadas.
• 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.
• types[] contiene un conjunto de tipos de características que describen el resultado proporcionado. Consulta la lista de tipos admitidos para obtener más información. Las respuestas XML incluyen múltiples elementos <type> si se asignó más de un tipo al resultado.
• vicinity contiene el nombre de una característica de una ubicación cercana. Generalmente, esa característica hace referencia a una calle o un vecindario dentro de los resultados proporcionados. La propiedad vicinity solo se devuelve para una búsqueda de sitios cercanos.
• formatted_address es una cadena que contiene la dirección del sitio en lenguaje natural. A menudo, esta dirección equivale a la “dirección postal”. La propiedad formatted_address solo se devuelve para una búsqueda de texto.

Datos premium

Además de los campos antes indicados, los clientes de Google Places API for Work pueden recibir los siguientes campos. Estos campos aparecerán como campos secundarios de nivel superior del campo result.

• aspects contiene un solo objeto AspectRating para la calificación principal de ese establecimiento. Cada AspectRating se describe de la siguiente manera:
  • type el nombre del aspecto que se está calificando. Los tipos admitidos son los siguientes: appeal, atmosphere, decor, facilities, food, overall, quality y service.
  • rating la calificación agregada para ese aspecto en particular en una escala de 0 a 30. Ten en cuenta que las calificaciones agregadas abarcan un rango de 0 a 30, mientras que las calificaciones que aparecen como parte de una reseña abarcan un rango de 0 a 3.
• zagat_selected indica que el sitio fue seleccionado como una ubicación de calidad por Zagat. La etiqueta de Zagat identifica sitios conocidos por su constante alta calidad o que poseen un estilo especial o exclusivo.

Acceso a resultados adicionales

De manera predeterminada, cada búsqueda de sitios cercanos o de texto devuelve hasta 20 resultados de establishment por solicitud. Sin embargo, cada búsqueda puede devolver hasta 60 resultados divididos en tres páginas. Si tu búsqueda devuelve más de 20, la respuesta de búsqueda incluirá un valor adicional: next_page_token. Pasa el valor de next_page_token al parámetro pagetoken de una nueva búsqueda para ver el siguiente conjunto de resultados. Si next_page_token es nulo o no se devuelve, no hay más resultados. Existe una breve demora entre la emisión de un parámetro next_page_token y su validación. Si solicitas la página siguiente antes de que esté disponible, se devolverá una respuesta INVALID_REQUEST. Si vuelves a realizar la solicitud con el mismo next_page_token, se devolverá la siguiente página de resultados.

Por ejemplo, en la consulta a continuación, buscamos restaurantes cerca de Darling Harbour, en Sydney, Australia, y clasificamos los resultados por distancia. Puedes ver que la respuesta contiene una propiedad next_page_token.

https://maps.googleapis.com/maps/api/place/nearbysearch/json?location=-33.8670522,151.1957362&rankby=distance&types=food&key=YOUR_API_KEY

{
   "html_attributions" : [],
   "next_page_token" : "CpQCAgEAAFxg8o-eU7_uKn7Yqjana-HQIx1hr5BrT4zBaEko29ANsXtp9mrqN0yrKWhf-y2PUpHRLQb1GT-mtxNcXou8TwkXhi1Jbk-ReY7oulyuvKSQrw1lgJElggGlo0d6indiH1U-tDwquw4tU_UXoQ_sj8OBo8XBUuWjuuFShqmLMP-0W59Vr6CaXdLrF8M3wFR4dUUhSf5UC4QCLaOMVP92lyh0OdtF_m_9Dt7lz-Wniod9zDrHeDsz_by570K3jL1VuDKTl_U1cJ0mzz_zDHGfOUf7VU1kVIs1WnM9SGvnm8YZURLTtMLMWx8-doGUE56Af_VfKjGDYW361OOIj9GmkyCFtaoCmTMIr5kgyeUSnB-IEhDlzujVrV6O9Mt7N4DagR6RGhT3g1viYLS4kO5YindU6dm3GIof1Q",
   "results" : [
      {
         "geometry" : {
            "location" : {
               "lat" : -33.867217,
               "lng" : 151.195939
            }
         },
         "icon" : "http://maps.gstatic.com/mapfiles/place_api/icons/cafe-71.png",
         "id" : "7eaf747a3f6dc078868cd65efc8d3bc62fff77d7",
         "name" : "Biaggio Cafe - Pyrmont",
         "opening_hours" : {
            "open_now" : true
         },
         "photos" : [
            {
               "height" : 600,
               "html_attributions" : [],
               "photo_reference" : "CnRnAAAAmWmj0BqA0Jorm1_vjAvx1n6c7ZNBxyY-U9x99-oNyOxvMjDlo2npJzyIq7c3EK1YyoNXdMFDcRPzwLJtBzXAwCUFDGo_RtLRGBPJTA2CoerPdC5yvT2SjfDwH4bFf5MrznB0_YWa4Y2Qo7ABtAxgeBIQv46sGBwVNJQDI36Wd3PFYBoUTlVXa0wn-zRITjGp0zLEBh8oIBE",
               "width" : 900
            }
         ],
         "place_id" : "ChIJIfBAsjeuEmsRdgu9Pl1Ps48",
         "scope" : "GOOGLE",
         "price_level" : 1,
         "rating" : 3.4,
         "reference" : "CoQBeAAAAGu0wNJjuZ40DMrRe3mpn7fhlfIK1mf_ce5hgkhfM79u-lqy0G2mnmcueTq2JGWu9wsgS1ctZDHTY_pcqFFJyQNV2P-kdhoRIeYRHeDfbWtIwr3RgFf2zzFBXHgNjSq-PSzX_OU6OT2_3dzdhhpV-bPezomtrarW4DsGl9uh773yEhDJT6R3V8Fyvl_xeE761DTCGhT1jJ3floFI5_c-bHgGLVwH1g-cbQ",
         "types" : [ "cafe", "bar", "restaurant", "food", "establishment" ],
         "vicinity" : "48 Pirrama Rd, Pyrmont"
      },
      {
         "geometry" : {
            "location" : {
               "lat" : -33.866786,
               "lng" : 151.195633
            }
         },
         "icon" : "http://maps.gstatic.com/mapfiles/place_api/icons/generic_business-71.png",
         "id" : "3ef986cd56bb3408bc1cf394f3dad9657c1d30f6",
         "name" : "Doltone House",
         "photos" : [
            {
               "height" : 1260,
               "html_attributions" : [ "From a Google User" ],
               "photo_reference" : "CnRwAAAAeM-aLqAm573T44qnNe8bGMkr_BOh1MOVQaA9CCggqtTwuGD1rjsviMyueX_G4-mabgH41Vpr8L27sh-VfZZ8TNCI4FyBiGk0P4fPxjb5Z1LrBZScYzM1glRxR-YjeHd2PWVEqB9cKZB349QqQveJLRIQYKq2PNlOM0toJocR5b_oYRoUYIipdBjMfdUyJN4MZUmhCsTMQwg",
               "width" : 1890
            }
         ],
         "place_id" : "ChIJ5xQ7szeuEmsRs6Kj7YFZE9k",
         "scope" : "GOOGLE",
         "reference" : "CnRvAAAA22k1PAGyDxAgHZk6ErHh_h_mLUK_8XNFLvixPJHXRbCzg-gw1ZxdqUwA_8EseDuEZKolBs82orIQH4m6-afDZV9VcpggokHD9x7HdMi9TnJDmGb9Bdh8f-Od4DK0fASNBL7Me3CsAWkUMWhlNQNYExIQ05W7VbxDTQe2Kh9TiL840hoUZfiO0q2HgDHSUyRdvTQx5Rs2SBU",
         "types" : [ "food", "establishment" ],
         "vicinity" : "48 Pirrama Rd, Pyrmont"
      },
      {
         "aspects" : [
            {
               "rating" : 23,
               "type" : "overall"
            }
         ],
      ...
   ],
   "status" : "OK"
}

Para ver el siguiente conjunto de resultados, puedes volver a emitir la misma consulta o enviar una nueva pasando el resultado de next_page_token al parámetro pagetoken. Por ejemplo:

https://maps.googleapis.com/maps/api/place/nearbysearch/json?pagetoken=CpQCAgEAAFxg8o-eU7_uKn7Yqjana-HQIx1hr5BrT4zBaEko29ANsXtp9mrqN0yrKWhf-y2PUpHRLQb1GT-mtxNcXou8TwkXhi1Jbk-ReY7oulyuvKSQrw1lgJElggGlo0d6indiH1U-tDwquw4tU_UXoQ_sj8OBo8XBUuWjuuFShqmLMP-0W59Vr6CaXdLrF8M3wFR4dUUhSf5UC4QCLaOMVP92lyh0OdtF_m_9Dt7lz-Wniod9zDrHeDsz_by570K3jL1VuDKTl_U1cJ0mzz_zDHGfOUf7VU1kVIs1WnM9SGvnm8YZURLTtMLMWx8-doGUE56Af_VfKjGDYW361OOIj9GmkyCFtaoCmTMIr5kgyeUSnB-IEhDlzujVrV6O9Mt7N4DagR6RGhT3g1viYLS4kO5YindU6dm3GIof1Q&key=YOUR_API_KEY

Al establecer pagetoken, se ignorará cualquier otro parámetro. La consulta ejecutará la misma búsqueda que antes, pero devolverá un nuevo conjunto de resultados. Puedes solicitar una página nueva hasta dos veces después de la consulta original. Las páginas de resultados se deben mostrar una a la vez. Dos o más páginas de resultados de búsqueda no se deben mostrar como el resultado de una consulta única. Ten en cuenta que cada búsqueda cuenta como una solicitud única para tus límites de uso.

El parámetro sensor

Antes, la Google Places API 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.