Place Autocomplete (heredado)

Desarrolladores del Espacio Económico Europeo (EEE)

Place Autocomplete (heredado) es un servicio web que devuelve predicciones de lugares 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 funcionalidad de autocompletado para búsquedas geográficas basadas en texto, ya que devuelve lugares como empresas, direcciones y lugares de interés a medida que el usuario escribe.

Solicitudes de Place Autocomplete (legacy)

Place Autocomplete (heredado) forma parte de la API de Places y comparte una clave de API y cuotas con la API de Places.

Place Autocomplete (heredado) puede buscar coincidencias para palabras completas y subcadenas, y resolver nombres de lugares, direcciones y Plus Codes. Así, las aplicaciones pueden enviar búsquedas a medida que el usuario escribe para proporcionar predicciones de lugares en el momento.

Debes darles el formato adecuado a los códigos plus. Esto significa que debes escapar el signo más en la URL como %2B y los espacios como %20.

  • Un código global se compone de un código de área de cuatro caracteres y un código local de seis caracteres o más. Por ejemplo, el código global 849VCWC8+R9 con escape de URL es 849VCWC8%2BR9.
  • Un código compuesto es un código local de seis caracteres (o más) con una ubicación explícita. Por ejemplo, el código compuesto con escape de URL CWC8+R9 Mountain View, CA, USA es CWC8%2BR9%20Mountain%20View%20CA%20USA.

Las predicciones que se muestran están diseñadas para presentarse al usuario y ayudarlo a seleccionar el lugar que desea. Puedes enviar una solicitud de Place Details (legado) para obtener más información sobre cualquiera de los lugares que se muestran.

Una solicitud de Place Autocomplete (legado) es una URL HTTP con el siguiente formato:

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

donde output puede ser cualquiera de los siguientes valores:

  • json (recomendado) indica el resultado en notación de objetos JavaScript (JSON).
  • xml indica que el resultado es en formato XML.

Se requieren ciertos parámetros para iniciar una solicitud de Place Autocomplete (heredado). Tal como es práctica estándar para las URLs, todos los parámetros se separan usando el signo et (&). A continuación, se enumeran los parámetros y sus posibles valores.

Parámetros obligatorios

  • entrada

    Es la cadena de texto en la que se realizará la búsqueda. El servicio Place Autocomplete devolverá posibles coincidencias en función de esta cadena y ordenará los resultados según la relevancia percibida.

Parámetros opcionales

  • de la industrialización de la nube

    Es una agrupación de lugares a los que deseas restringir tus resultados. Puedes usar componentes para filtrar por hasta 5 países. Los países se deben pasar como un código de país ISO 3166-1 Alfa-2 compatible de dos caracteres. Por ejemplo, components=country:fr restringiría los resultados a lugares dentro de Francia. Si se pasan varios países, se deben utilizar varios filtros country:XX, con el carácter de barra vertical | como separador. Por ejemplo: components=country:us|country:pr|country:vi|country:gu|country:mp restringiría los resultados a lugares dentro de Estados Unidos y sus territorios organizados no incorporados.

    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.

  • idioma

    Es el idioma en el que se mostrarán los resultados.

    • Consulta la lista de idiomas admitidos. Google actualiza con frecuencia los idiomas admitidos, por lo que es posible que esta lista no sea exhaustiva.
    • Si no se proporciona language, la API intenta usar el idioma preferido especificado en el encabezado Accept-Language.
    • La API hace todo lo posible para proporcionar una dirección que sea legible tanto para el usuario como para los residentes locales. Para lograr ese objetivo, devuelve direcciones de calles en el idioma local, transliteradas a una escritura que el usuario pueda leer si es necesario, y observa el idioma preferido. Todas las demás direcciones se devuelven en el idioma preferido. Todos los componentes de la dirección se devuelven en el mismo idioma, que se elige a partir del primer componente.
    • Si un nombre no está disponible en el idioma preferido, la API usa la coincidencia más cercana.
    • El idioma preferido tiene una pequeña influencia en el conjunto de resultados que la API elige devolver y en el orden en que se devuelven. El geocodificador interpreta las abreviaturas de manera diferente según el idioma, como las abreviaturas de los tipos de calles 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 en húngaro.

  • ubicación

    Es el punto alrededor del cual se recupera la información del lugar. Debe especificarse como latitude,longitude. El parámetro radius también se debe proporcionar cuando se especifica una ubicación. Si no se proporciona radius, se ignora el parámetro location.

    Cuando se usa la API de Text Search, se puede anular el parámetro "location" si la "query" contiene una ubicación explícita, como "Mercado en Barcelona".

  • locationbias

    Prefiere los resultados en un área especificada, ya sea con un radio y una latitud y longitud, o bien con dos pares de latitud y longitud que representan los puntos de un rectángulo. Si no se especifica este parámetro, la API usa la adaptación de la búsqueda por dirección IP de forma predeterminada.

    • Sesgo de IP: Indica a la API que use el sesgo de dirección IP. Pasa la cadena ipbias (esta opción no tiene parámetros adicionales).
    • Circular: Es una cadena que especifica el radio en metros, además de la latitud y la longitud en grados decimales. Usa el siguiente formato: circle:radius@lat,lng.
    • Rectangular: Es una cadena que especifica dos pares de coordenadas de latitud y longitud en grados decimales, que representan los puntos sur/oeste y norte/este de un rectángulo. Usa el siguiente formato:rectangle:south,west|north,east. Ten en cuenta que los valores este/oeste se ajustan al rango de -180 a 180, y los valores norte/sur se ajustan al rango de -90 a 90.

  • locationrestriction

    Restringe los resultados a un área especificada. Para ello, especifica un radio más una latitud y una longitud, o bien dos pares de latitud y longitud que representen los puntos de un rectángulo.

    • Circular: Es una cadena que especifica el radio en metros, además de la latitud y la longitud en grados decimales. Usa el siguiente formato: circle:radius@lat,lng.
    • Rectangular: Es una cadena que especifica dos pares de coordenadas de latitud y longitud en grados decimales, que representan los puntos sur/oeste y norte/este de un rectángulo. Usa el siguiente formato:rectangle:south,west|north,east. Ten en cuenta que los valores este/oeste se ajustan al rango de -180 a 180, y los valores norte/sur se ajustan al rango de -90 a 90.

  • offset

    Posición, en el término de entrada, del último carácter que el servicio usa para correlacionar predicciones. Por ejemplo, si la entrada es Google y el desplazamiento es 3, el servicio coincidirá con Goo. La cadena determinada por el desplazamiento solo se compara con la primera palabra del término de entrada. Por ejemplo, si el término de entrada es Google abc y el desplazamiento es 3, el servicio intentará hacer coincidir el término con Goo abc. Si no se proporciona ninguna compensación, el servicio usará todo el período. Por lo general, el desplazamiento debe establecerse en la posición del cursor de texto.

  • origin

    Punto de origen desde el que se calcula la distancia en línea recta hasta el destino (se devuelve como distance_meters). Si se omite este valor, no se devolverá la distancia en línea recta. Se debe especificar como latitude,longitude.

  • radio

    Define la distancia (en metros) dentro de la cual se deben devolver los resultados de lugares. Puedes personalizar los resultados para un círculo específico si pasas los parámetros location y radius. Si lo haces, le indicas al servicio Places que prefiera mostrar resultados dentro de ese círculo. Es posible que también se muestren resultados fuera del área definida.

    El radio se ajustará automáticamente a un valor máximo según el tipo de búsqueda y otros parámetros.

    • Autocompletar: 50,000 metros
    • Nearby Search:
      • Con keyword o name: 50,000 metros
      • sin keyword o name
        • Hasta 50,000 metros, ajustado de forma dinámica según la densidad del área, independientemente del parámetro rankby.
        • Cuando se usa rankby=distance, no se aceptará el parámetro de radio y se generará un INVALID_REQUEST.
    • Autocompletar búsquedas: 50,000 metros
    • Text Search: 50,000 metros

  • región

    Es el código de región, especificado como un valor de dos caracteres del ccTLD ("dominio de nivel superior"). 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 "El Reino Unido de Gran Bretaña e Irlanda del Norte").

  • sessiontoken

    Es una cadena aleatoria que identifica una sesión de autocompletado a los efectos de la facturación.

    La sesión comienza cuando el usuario comienza a escribir una búsqueda y termina cuando selecciona un lugar y se realiza una llamada a Place Details. Cada sesión puede tener varias búsquedas, seguidas de una selección de lugar. Las claves de API utilizadas para cada solicitud dentro de una sesión deben pertenecer al mismo proyecto de Google Cloud Console. Una vez que finaliza la sesión, el token deja de ser válido, por lo que tu app debe generar un token nuevo para cada sesión. Si se omite el parámetro sessiontoken o si reutilizas un token de sesión, la sesión se cobrará como si no se hubiera proporcionado un token de sesión (cada solicitud se factura por separado).

    Recomendamos los siguientes lineamientos:

    • Usa tokens de sesión para todas las sesiones de autocompletado.
    • Genera un token nuevo para cada sesión. Se recomienda usar un UUID de versión 4.
    • Asegúrate de que las claves de API que se usan para todas las solicitudes de Place Autocomplete y Place Details dentro de una sesión pertenezcan al mismo proyecto de Cloud Console.
    • Asegúrate de pasar un token de sesión único para cada sesión nueva. Usar el mismo token en más de una sesión hará que cada solicitud se facture de forma individual.

  • strictbounds

    Devuelve solo los lugares que se encuentran estrictamente dentro de la región definida por location y radius. Esta es una restricción, no un sesgo, lo que significa que no se devolverán resultados fuera de esta región, incluso si coinciden con la entrada del usuario.

  • máquinas activas

    Puedes restringir los resultados de una solicitud de Place Autocomplete para que sean de un tipo determinado pasando el parámetro types. Este parámetro especifica un tipo o una colección de tipos, como se indica en Tipos de lugares. Si no se especifica nada, se devolverán todos los tipos.

    Un lugar solo puede tener un solo tipo principal de los tipos que se enumeran en la Tabla 1 o la Tabla 2. Por ejemplo, un hotel en el que se sirve comida puede devolverse solo con types=lodging y no con types=restaurant.

    Para el valor del parámetro types, puedes especificar lo siguiente:

    • Hasta cinco valores de la Tabla 1 o Tabla 2. Si hay varios valores, sepáralos con una barra vertical (|). Por ejemplo:

      types=book_store|cafe

    • Cualquier filtro admitido único en la Tabla 3 No puedes mezclar colecciones de tipos.

    La solicitud se rechazará con un error INVALID_REQUEST en los siguientes casos:

    • Se especifican más de cinco tipos.
    • Hay tipos no reconocidos.
    • Cualquier tipo de la Tabla 1 o Tabla 2 se combina con cualquiera de los filtros de la Tabla 3.

Ejemplos de Place Autocomplete (heredado)

Una solicitud de establecimientos que contengan la cadena "Amoeba" dentro de un área centrada en San Francisco, California:

URL

https://maps.googleapis.com/maps/api/place/autocomplete/json
      ?input=amoeba
      &types=establishment
      &location=37.76999%2C-122.44696
      &radius=500
      &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/place/autocomplete/json?input=amoeba&types=establishment&location=37.76999%2C-122.44696&radius=500&key=YOUR_API_KEY'

La misma solicitud, restringida a los resultados que se encuentran a 500 metros de Ashbury St y Haight St, San Francisco:

URL

https://maps.googleapis.com/maps/api/place/autocomplete/json
      ?input=amoeba
      &types=establishment
      &location=37.76999%2C-122.44696&radius=500
      &strictbounds=true
      &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/place/autocomplete/json?input=amoeba&types=establishment&location=37.76999%2C-122.44696&radius=500&strictbounds=true&key=YOUR_API_KEY'

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

URL

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

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/place/autocomplete/json?input=Vict&types=geocode&language=fr&key=YOUR_API_KEY'

Una solicitud de ciudades que contengan "Vict" con resultados en portugués brasileño:

URL

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

curl

curl -L -X GET '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 API en estos ejemplos por tu propia clave.

Respuesta de Place Autocomplete (heredado)

Las respuestas de Place Autocomplete (legacy) se muestran en el formato indicado por la marca output dentro de la ruta de URL de la solicitud. Los resultados que se muestran a continuación son indicativos de lo que se puede devolver para una búsqueda con los siguientes parámetros:

URL

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

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/place/autocomplete/json?input=Paris&types=geocode&key=YOUR_API_KEY'

JSON

{
  "predictions":
    [
      {
        "description": "Paris, France",
        "matched_substrings": [{ "length": 5, "offset": 0 }],
        "place_id": "ChIJD7fiBh9u5kcRYJSMaMOCCwQ",
        "reference": "ChIJD7fiBh9u5kcRYJSMaMOCCwQ",
        "structured_formatting":
          {
            "main_text": "Paris",
            "main_text_matched_substrings": [{ "length": 5, "offset": 0 }],
            "secondary_text": "France",
          },
        "terms":
          [
            { "offset": 0, "value": "Paris" },
            { "offset": 7, "value": "France" },
          ],
        "types": ["locality", "political", "geocode"],
      },
      {
        "description": "Paris, TX, USA",
        "matched_substrings": [{ "length": 5, "offset": 0 }],
        "place_id": "ChIJmysnFgZYSoYRSfPTL2YJuck",
        "reference": "ChIJmysnFgZYSoYRSfPTL2YJuck",
        "structured_formatting":
          {
            "main_text": "Paris",
            "main_text_matched_substrings": [{ "length": 5, "offset": 0 }],
            "secondary_text": "TX, USA",
          },
        "terms":
          [
            { "offset": 0, "value": "Paris" },
            { "offset": 7, "value": "TX" },
            { "offset": 11, "value": "USA" },
          ],
        "types": ["locality", "political", "geocode"],
      },
      {
        "description": "Paris, TN, USA",
        "matched_substrings": [{ "length": 5, "offset": 0 }],
        "place_id": "ChIJ4zHP-Sije4gRBDEsVxunOWg",
        "reference": "ChIJ4zHP-Sije4gRBDEsVxunOWg",
        "structured_formatting":
          {
            "main_text": "Paris",
            "main_text_matched_substrings": [{ "length": 5, "offset": 0 }],
            "secondary_text": "TN, USA",
          },
        "terms":
          [
            { "offset": 0, "value": "Paris" },
            { "offset": 7, "value": "TN" },
            { "offset": 11, "value": "USA" },
          ],
        "types": ["locality", "political", "geocode"],
      },
      {
        "description": "Paris, Brant, ON, Canada",
        "matched_substrings": [{ "length": 5, "offset": 0 }],
        "place_id": "ChIJsamfQbVtLIgR-X18G75Hyi0",
        "reference": "ChIJsamfQbVtLIgR-X18G75Hyi0",
        "structured_formatting":
          {
            "main_text": "Paris",
            "main_text_matched_substrings": [{ "length": 5, "offset": 0 }],
            "secondary_text": "Brant, ON, Canada",
          },
        "terms":
          [
            { "offset": 0, "value": "Paris" },
            { "offset": 7, "value": "Brant" },
            { "offset": 14, "value": "ON" },
            { "offset": 18, "value": "Canada" },
          ],
        "types": ["neighborhood", "political", "geocode"],
      },
      {
        "description": "Paris, KY, USA",
        "matched_substrings": [{ "length": 5, "offset": 0 }],
        "place_id": "ChIJsU7_xMfKQ4gReI89RJn0-RQ",
        "reference": "ChIJsU7_xMfKQ4gReI89RJn0-RQ",
        "structured_formatting":
          {
            "main_text": "Paris",
            "main_text_matched_substrings": [{ "length": 5, "offset": 0 }],
            "secondary_text": "KY, USA",
          },
        "terms":
          [
            { "offset": 0, "value": "Paris" },
            { "offset": 7, "value": "KY" },
            { "offset": 11, "value": "USA" },
          ],
        "types": ["locality", "political", "geocode"],
      },
    ],
  "status": "OK",
}

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>
  <reference>ChIJD7fiBh9u5kcRYJSMaMOCCwQ</reference>
  <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>
  <place_id>ChIJD7fiBh9u5kcRYJSMaMOCCwQ</place_id>
  <structured_formatting>
   <description>Paris</description>
   <subdescription>France</subdescription>
   <description_matched_substring>
    <offset>0</offset>
    <length>5</length>
   </description_matched_substring>
  </structured_formatting>
 </prediction>
 <prediction>
  <description>Paris, TX, USA</description>
  <type>locality</type>
  <type>political</type>
  <type>geocode</type>
  <reference>ChIJmysnFgZYSoYRSfPTL2YJuck</reference>
  <term>
   <value>Paris</value>
   <offset>0</offset>
  </term>
  <term>
   <value>TX</value>
   <offset>7</offset>
  </term>
  <term>
   <value>USA</value>
   <offset>11</offset>
  </term>
  <matched_substring>
   <offset>0</offset>
   <length>5</length>
  </matched_substring>
  <place_id>ChIJmysnFgZYSoYRSfPTL2YJuck</place_id>
  <structured_formatting>
   <description>Paris</description>
   <subdescription>TX, USA</subdescription>
   <description_matched_substring>
    <offset>0</offset>
    <length>5</length>
   </description_matched_substring>
  </structured_formatting>
 </prediction>
 <prediction>
  <description>Paris, TN, USA</description>
  <type>locality</type>
  <type>political</type>
  <type>geocode</type>
  <reference>ChIJ4zHP-Sije4gRBDEsVxunOWg</reference>
  <term>
   <value>Paris</value>
   <offset>0</offset>
  </term>
  <term>
   <value>TN</value>
   <offset>7</offset>
  </term>
  <term>
   <value>USA</value>
   <offset>11</offset>
  </term>
  <matched_substring>
   <offset>0</offset>
   <length>5</length>
  </matched_substring>
  <place_id>ChIJ4zHP-Sije4gRBDEsVxunOWg</place_id>
  <structured_formatting>
   <description>Paris</description>
   <subdescription>TN, USA</subdescription>
   <description_matched_substring>
    <offset>0</offset>
    <length>5</length>
   </description_matched_substring>
  </structured_formatting>
 </prediction>
 <prediction>
  <description>Paris, Brant, ON, Canada</description>
  <type>neighborhood</type>
  <type>political</type>
  <type>geocode</type>
  <reference>ChIJsamfQbVtLIgR-X18G75Hyi0</reference>
  <term>
   <value>Paris</value>
   <offset>0</offset>
  </term>
  <term>
   <value>Brant</value>
   <offset>7</offset>
  </term>
  <term>
   <value>ON</value>
   <offset>14</offset>
  </term>
  <term>
   <value>Canada</value>
   <offset>18</offset>
  </term>
  <matched_substring>
   <offset>0</offset>
   <length>5</length>
  </matched_substring>
  <place_id>ChIJsamfQbVtLIgR-X18G75Hyi0</place_id>
  <structured_formatting>
   <description>Paris</description>
   <subdescription>Brant, ON, Canada</subdescription>
   <description_matched_substring>
    <offset>0</offset>
    <length>5</length>
   </description_matched_substring>
  </structured_formatting>
 </prediction>
 <prediction>
  <description>Paris, KY, USA</description>
  <type>locality</type>
  <type>political</type>
  <type>geocode</type>
  <reference>ChIJsU7_xMfKQ4gReI89RJn0-RQ</reference>
  <term>
   <value>Paris</value>
   <offset>0</offset>
  </term>
  <term>
   <value>KY</value>
   <offset>7</offset>
  </term>
  <term>
   <value>USA</value>
   <offset>11</offset>
  </term>
  <matched_substring>
   <offset>0</offset>
   <length>5</length>
  </matched_substring>
  <place_id>ChIJsU7_xMfKQ4gReI89RJn0-RQ</place_id>
  <structured_formatting>
   <description>Paris</description>
   <subdescription>KY, USA</subdescription>
   <description_matched_substring>
    <offset>0</offset>
    <length>5</length>
   </description_matched_substring>
  </structured_formatting>
 </prediction>
</AutocompletionResponse>

PlacesAutocompleteResponse

Campo Obligatorio Tipo Descripción
required Arreglo<PlaceAutocompletePrediction>

Contiene un array de predicciones.

Consulta PlaceAutocompletePrediction para obtener más información.

required PlacesAutocompleteStatus

Contiene el estado de la solicitud y puede incluir información de depuración para ayudarte a identificar el motivo del error en la solicitud.

Consulta PlacesAutocompleteStatus para obtener más información.

opcional string

Cuando el servicio devuelve un código de estado que no es OK<, es posible que haya un campo error_message adicional dentro del objeto de respuesta. Este campo contiene información más detallada sobre los motivos del código de estado proporcionado. Este campo no siempre se devuelve y su contenido está sujeto a cambios.

opcional Arreglo<cadena>

Cuando el servicio devuelve información adicional sobre la especificación de la solicitud, puede haber un campo info_messages adicional dentro del objeto de respuesta. Este campo solo se devuelve para las solicitudes exitosas. Es posible que no siempre se devuelva y su contenido está sujeto a cambios.

En los resultados, son de especial interés los elementos place_id, que se pueden usar para solicitar detalles más específicos sobre el lugar con una consulta independiente. Consulta las solicitudes de Place Details (legacy).

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

  • Un solo elemento <status> contiene metadatos sobre la solicitud. Consulta los códigos de estado a continuación.
  • Cero o más elementos <prediction>, cada uno con información sobre un solo lugar. Consulta Resultados de Place Autocomplete (heredado) para obtener información sobre estos resultados. La API de Places devuelve hasta 5 resultados.

Te recomendamos que uses json como la marca de salida preferida, a menos que tu aplicación requiera xml por algún motivo. El procesamiento de árboles XML requiere cierto cuidado para que hagas referencia a los nodos y elementos adecuados. Consulta Cómo procesar XML con XPath para obtener ayuda con el procesamiento de XML.

PlacesAutocompleteStatus

Son los códigos de estado que muestra el servicio.

  • OK: Indica que la solicitud a la API se realizó correctamente.
  • ZERO_RESULTS indica que la búsqueda se realizó correctamente, pero no devolvió ningún resultado. Esto puede ocurrir si se pasó una búsqueda con límites en una ubicación remota.
  • INVALID_REQUEST, que indica que la solicitud a la API tenía un formato incorrecto, por lo general, debido a la falta del parámetro input
  • OVER_QUERY_LIMIT que indica cualquiera de las siguientes opciones:
    • Superaste los límites de QPS.
    • No se habilitó la facturación en tu cuenta.
    • Se superó el crédito mensual de USD 200 o 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 más información sobre cómo resolver este error.
  • REQUEST_DENIED indica que se rechazó tu solicitud, generalmente por los siguientes motivos:
    • Falta una clave de API en la solicitud.
    • El parámetro key no es válido.
  • UNKNOWN_ERROR: Indica un error desconocido.

Cuando el servicio de Places devuelve resultados JSON de una búsqueda, los coloca dentro de un array predictions. Incluso si el servicio no devuelve resultados (por ejemplo, si el location es remoto), devuelve un array predictions vacío. Las respuestas XML constan de cero o más elementos <prediction>.

PlaceAutocompletePrediction

Campo Obligatorio Tipo Descripción
required string

Contiene el nombre legible del resultado devuelto. En el caso de los resultados de establishment, suele ser el nombre de la empresa. Este contenido se debe leer tal como está. No analices la dirección con formato de manera programática.

required Arreglo<PlaceAutocompleteMatchedSubstring>

Es una lista de subcadenas que describen la ubicación del término ingresado en el texto del resultado de la predicción, de modo que el término se pueda destacar si se elige.

Consulta PlaceAutocompleteMatchedSubstring para obtener más información.

required PlaceAutocompleteStructuredFormat

Proporciona texto con formato previo que se puede mostrar en los resultados de autocompletado. Este contenido se debe leer tal como está. No analices la dirección con formato de manera programática.

Consulta PlaceAutocompleteStructuredFormat para obtener más información.

required Arreglo<PlaceAutocompleteTerm>

Contiene un array de términos que identifican cada sección de la descripción devuelta (por lo general, una sección de la descripción termina con una coma). Cada entrada del array tiene un campo value, que contiene el texto del término, y un campo offset, que define la posición inicial de este término en la descripción, medida en caracteres Unicode.

Consulta PlaceAutocompleteTerm para obtener más información.

opcional integer

Es la distancia en línea recta desde el origen, expresada en metros. Este campo solo se devuelve para las solicitudes realizadas con un origin.

opcional string

un identificador textual que identifica de forma exclusiva un sitio. Para recuperar información sobre el lugar, pasa este identificador en el campo placeId de una solicitud a la API de Places. Para obtener más información sobre los IDs de lugar, consulta la descripción general de los IDs de lugar.

opcional string

Consulta place_id.
opcional Arreglo<cadena>

Contiene un array de tipos que se aplican a este lugar. Por ejemplo: [ "political", "locality" ] o [ "establishment", "geocode", "beauty_salon" ]. El array puede contener varios valores. Obtén más información sobre los tipos de lugares.

PlaceAutocompleteMatchedSubstring

Campo Obligatorio Tipo Descripción
required número

Longitud de la subcadena coincidente en el texto del resultado de la predicción.
required número

Ubicación inicial de la subcadena coincidente en el texto del resultado de la predicción.

PlaceAutocompleteStructuredFormat

Campo Obligatorio Tipo Descripción

main_text

required string

Contiene el texto principal de una predicción, que suele ser el nombre del lugar.

main_text_matched_substrings

required Arreglo<PlaceAutocompleteMatchedSubstring>

Contiene un array con el valor offset y length. Estos describen la ubicación del término ingresado en el texto del resultado de la predicción, de modo que el término se pueda destacar si se elige.

Consulta PlaceAutocompleteMatchedSubstring para obtener más información.

secondary_text

opcional string

Contiene el texto secundario de una predicción, que suele ser la ubicación del lugar.

secondary_text_matched_substrings

opcional Arreglo<PlaceAutocompleteMatchedSubstring>

Contiene un array con el valor offset y length. Estos describen la ubicación del término ingresado en el texto del resultado de la predicción, de modo que el término se pueda destacar si se elige.

Consulta PlaceAutocompleteMatchedSubstring para obtener más información.

PlaceAutocompleteTerm

Campo Obligatorio Tipo Descripción
required número

Define la posición inicial de este término en la descripción, medida en caracteres Unicode.

required string

Es el texto del término.

Optimización de Place Autocomplete (heredado)

En esta sección, se describen algunas prácticas recomendadas que te ayudarán a aprovechar al máximo el servicio Place Autocomplete (Legacy).

A continuación, se indican algunos lineamientos generales:

  • La forma más rápida de desarrollar una interfaz de usuario que funcione es usar el widget de Place Autocomplete (heredado) de la API de Maps JavaScript, el widget de Place Autocomplete (heredado) del SDK de Places para Android, o el control de la IU de Place Autocomplete (heredado) del SDK de Places para iOS.
  • Comprende los campos de datos esenciales de Place Autocomplete (heredado) desde el principio.
  • Los campos de restricción y personalización de la ubicación son opcionales, pero pueden afectar significativamente el rendimiento del autocompletado.
  • Usa el procedimiento de manejo de errores para asegurarte de que tu app administre el problema de forma adecuada si la API muestra un error.
  • Asegúrate de que tu app gestione correctamente los problemas cuando no haya selección y ofrezca a los usuarios una manera de continuar.

Prácticas recomendadas para la optimización de los costos

Optimización básica de los costos

Para optimizar el costo de usar el servicio Place Autocomplete (heredado), usa máscaras de campo en los widgets de Place Details (heredado) y Place Autocomplete (heredado) para mostrar solo los campos de datos de Place Autocomplete (heredado) que necesitas.

Optimización avanzada de los costos

Considera utilizar la implementación programática de Place Autocomplete (legado) para acceder a los SKU: precios de Autocomplete por solicitud y solicitar resultados de la API de Geocoding sobre el lugar seleccionado en lugar de utilizar Place Details (legado). Los precios por solicitud asociados con la API de Geocoding son más rentables que los precios por sesión (basados en sesión) si se cumplen las siguientes condiciones:

  • Si solo necesitas las coordenadas de latitud y longitud, o la dirección del lugar seleccionado por el usuario, la API de Geocoding proporciona esta información de manera más fácil que una llamada a Place Details (Legacy).
  • Si los usuarios seleccionan una predicción de autocompletar con un promedio de cuatro solicitudes o menos, el precio por solicitud puede ser más rentable que el precio por sesión.
Si necesitas ayuda para elegir la implementación de Place Autocomplete (heredado) más adecuada para tus necesidades, selecciona la pestaña correspondiente a tu respuesta en función de la siguiente pregunta.

¿Tu aplicación requiere algún dato diferente de la dirección y las coordenadas de latitud o longitud de la predicción seleccionada?

Sí, necesita más detalles

Usa el servicio Place Autocomplete basado en sesiones (heredado) con Place Details (heredado).
Dado que tu aplicación requiere Places Details (heredado), como el nombre del lugar, el estado comercial o el horario de atención, tu implementación de Place Autocomplete (heredado) debe usar un token de sesión (de forma programática o integrado en los widgets de JavaScript, Android o iOS) por sesión, además de los SKU de datos de Places aplicables, según los campos de datos de lugares que solicites.1

Implementación de widgets
La administración de sesiones está integrada automáticamente en los widgets de JavaScript, Android, o iOS. Esto incluye las solicitudes de Place Autocomplete (legado) y Place Details (legado) en la predicción seleccionada. Asegúrate de especificar el parámetro fields para asegurarte de solicitar únicamente los campos de datos de Place Autocomplete (legacy) que necesitas.

Implementación programática
Usa un token de sesión con tus solicitudes de Place Autocomplete (heredado). Cuando solicites Place Details (Legacy) sobre la predicción seleccionada, incluye los siguientes parámetros:

  1. El ID de lugar de la respuesta de Place Autocomplete (heredado)
  2. El token de sesión que se usó en la solicitud de Place Autocomplete (legacy)
  3. El parámetro fields que especifica los campos de datos de Place Autocomplete (heredado) que necesitas

No, solo requiere la dirección y la ubicación

La API de Geocoding podría ser una opción más rentable que Place Details (Legacy) para tu aplicación, según el rendimiento de tu uso de Place Autocomplete (Legacy). La eficiencia de Place Autocomplete (legacy) de cada aplicación varía según las búsquedas que ingresan los usuarios, dónde se usa la aplicación y si se siguen las prácticas recomendadas de optimización del rendimiento.

Para responder la siguiente pregunta, analiza cuántos caracteres escribe un usuario en promedio antes de seleccionar una predicción de Place Autocomplete (heredado) en tu aplicación.

¿Tus usuarios seleccionan, en promedio, una predicción de Place Autocomplete (heredado) cada cuatro solicitudes o menos?

Sí

Implementa Place Autocomplete (heredado) de manera programática sin tokens de sesión y llama a la API de Geocoding en la predicción de lugar seleccionada.
La API de Geocoding proporciona direcciones y coordenadas de latitud y longitud. Realizar cuatro solicitudes de Autocomplete por solicitud más una llamada a la API de Geocoding sobre la predicción de lugar seleccionada cuesta menos que el costo por sesión de Place Autocomplete (Legacy).1

Considera aplicar las prácticas recomendadas de rendimiento para ayudar a los usuarios a obtener la predicción que buscan con menos caracteres.

No

Usa el servicio Place Autocomplete basado en sesiones (heredado) con Place Details (heredado).
Dado que la cantidad promedio de solicitudes que esperas realizar antes de que un usuario seleccione una predicción de Place Autocomplete (Legacy) supera el costo de los precios por sesión, tu implementación de Place Autocomplete (Legacy) debe usar un token de sesión para las solicitudes de Place Autocomplete (Legacy) y la solicitud de Place Details (Legacy) asociada por sesión. 1

Implementación de widgets
La administración de sesiones está integrada automáticamente en los widgets de JavaScript, Android, o iOS. Esto incluye las solicitudes de Place Autocomplete (legado) y Place Details (legado) en la predicción seleccionada. Asegúrate de especificar el parámetro fields para asegurarte de solicitar únicamente los campos que necesitas.

Implementación programática
Usa un token de sesión con tus solicitudes de Place Autocomplete (heredado). Cuando solicites Place Details (Legacy) sobre la predicción seleccionada, incluye los siguientes parámetros:

  1. El ID de lugar de la respuesta de Place Autocomplete (heredado)
  2. El token de sesión que se usó en la solicitud de Place Autocomplete (legacy)
  3. El parámetro fields que especifica campos de datos básicos, como la dirección y la geometría

Considera retrasar las solicitudes de Place Autocomplete (heredado)
Puedes emplear estrategias como demorar una solicitud de Place Autocomplete (heredado) hasta que el usuario escriba los primeros tres o cuatro caracteres para que tu aplicación realice menos solicitudes. Por ejemplo, realizar solicitudes de Place Autocomplete (legacy) para cada carácter después de que el usuario haya escrito el tercer carácter significa que, si el usuario escribe siete caracteres y, luego, selecciona una predicción para la que realizas una solicitud a la API de Geocoding, el costo total sería el de 4 solicitudes de Place Autocomplete (legacy) por solicitud más Geocoding.1

Si retrasar las solicitudes puede hacer que tu solicitud programática promedio sea inferior a cuatro, puedes seguir las instrucciones para implementar Place Autocomplete (heredado) con la API de Geocoding y obtener un rendimiento optimizado. Ten en cuenta que demorar las solicitudes puede percibirse como latencia por parte del usuario, que tal vez espere ver predicciones con cada letra que ingresa.

Considera seguir las prácticas recomendadas de rendimiento para ayudar a los usuarios a obtener la predicción que buscan con menos caracteres.

  1. Para conocer los costos, consulta las listas de precios de Google Maps Platform.

Prácticas recomendadas para el rendimiento

Los siguientes lineamientos describen maneras de optimizar el rendimiento de Place Autocomplete (heredado):

  • Agrega restricciones por país, personalización de la ubicación y, en el caso de las implementaciones programáticas, la preferencia de idioma a la implementación de Place Autocomplete (Legacy). La preferencia de idioma no es necesaria para los widgets, dado que toman esta información del navegador o el dispositivo móvil del usuario.
  • Si Place Autocomplete (heredado) cuenta con un mapa, puedes personalizar la ubicación según su viewport.
  • En las situaciones en que un usuario no elige una de las predicciones de Place Autocomplete (heredado), generalmente, porque ninguna de ellas indica la dirección del resultado deseado, puedes reutilizar la entrada original del usuario para tratar de obtener resultados más relevantes:
    • Si esperas que el usuario ingrese únicamente información sobre la dirección, vuelve a usar su entrada original en una llamada a la API de Geocoding.
    • Si esperas que el usuario ingrese búsquedas para un lugar específico por nombre o dirección, usa una solicitud de Place Details (Legacy). Si se espera que los resultados pertenezcan únicamente a una región específica, usa la restricción de ubicación.
    A continuación, indicamos otras situaciones en las que es mejor recurrir a la API de Geocoding:
    • Usuarios que ingresan direcciones de subinstalaciones, como direcciones de unidades o apartamentos específicos dentro de un edificio Por ejemplo, la dirección checa "Stroupežnického 3191/17, Praha" genera una predicción parcial en Place Autocomplete (legacy).
    • Usuarios que ingresan direcciones con prefijos de tramo de ruta, como "23-30 29th St, Queens" en la ciudad de Nueva York o "47-380 Kamehameha Hwy, Kaneohe" en la isla de Kauai en Hawái

Ajuste de la ubicación

Personaliza los resultados para un área específica pasando un parámetro location y un parámetro radius. Esto le indica a Place Autocomplete (heredado) que prefiera mostrar resultados dentro del área definida. Es posible que también se muestren resultados externos al área definida. Puedes usar el parámetro includedRegionCodes para filtrar los resultados y mostrar solo los lugares dentro de un país especificado.

Restricción de ubicación

Restringe los resultados a un área específica pasando un parámetro locationRestriction.

También puedes restringir los resultados a la región definida por location y un parámetro radius agregando el parámetro strictbounds. Esto le indica a Place Autocomplete (Legacy) que devuelva solo resultados dentro de esa región.