Autocompletar (nuevo)

Introducción

La función Autocomplete (nuevo) es un servicio web que devuelve predicciones de lugares y de búsquedas en respuesta a una solicitud HTTP. En la solicitud, especifica una cadena de búsqueda de texto y los límites geográficos que controlan el área de búsqueda.

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

La respuesta de Autocomplete (nuevo) puede contener dos tipos de predicciones:

• Predicciones de lugares: Son lugares, como empresas, direcciones y lugares de interés, según la cadena de texto de entrada y el área de búsqueda especificados. Las predicciones de lugar se devuelven de forma predeterminada.
• Predicciones de búsqueda: Son cadenas de consulta que coinciden con la cadena de texto de entrada y el área de búsqueda. Las predicciones de consultas no se devuelven de forma predeterminada. Usa el parámetro de solicitud includeQueryPredictions para agregar predicciones de búsqueda a la respuesta.

Por ejemplo, llamas a Autocomplete (nuevo) con una cadena que contiene una entrada parcial del usuario, "Sicilian piz", con el área de búsqueda limitada a San Francisco, CA. Luego, la respuesta contiene una lista de predicciones de lugares que coinciden con la cadena y el área de búsqueda, como el restaurante llamado "Sicilian Pizza Kitchen", junto con detalles sobre el lugar.

Las predicciones de lugares que se devuelven están diseñadas para presentarse al usuario y ayudarlo a seleccionar el lugar deseado. Puedes realizar una solicitud de Place Details (nuevo) para obtener más información sobre cualquiera de las predicciones de lugares que se devuelven.

La respuesta también puede contener una lista de predicciones de búsqueda que coincidan con la cadena y el área de búsqueda, como "Sicilian Pizza & Pasta". Cada predicción de consulta en la respuesta incluye el campo text, que contiene una cadena de búsqueda de texto recomendada. Usa esa cadena como entrada para Text Search (nueva) y realiza una búsqueda más detallada.

El Explorador de APIs te permite realizar solicitudes en tiempo real para que puedas familiarizarte con la API y sus opciones:

Solicitudes de Autocomplete (New)

Una solicitud de Autocomplete (nuevo) es una solicitud HTTP POST a una URL con el siguiente formato:

https://places.googleapis.com/v1/places:autocomplete

Pasa todos los parámetros en el cuerpo de la solicitud JSON o en los encabezados como parte de la solicitud POST. Por ejemplo:

curl -X POST -d '{
  "input": "pizza",
  "locationBias": {
    "circle": {
      "center": {
        "latitude": 37.7937,
        "longitude": -122.3965
      },
      "radius": 500.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

Parámetros admitidos

Acerca de la respuesta

Autocomplete (nuevo) devuelve un objeto JSON como respuesta. En la respuesta, figura lo siguiente:

• El array suggestions contiene todos los lugares y las búsquedas previstos en orden según su relevancia percibida. Cada lugar se representa con un campo placePrediction y cada búsqueda se representa con un campo queryPrediction.
• Un campo placePrediction contiene información detallada sobre una sola predicción de lugar, incluidos el ID de lugar y la descripción de texto.
  • Para que coincida más con la entrada del usuario, tal como se proporciona en el parámetro input, la descripción de texto de una predicción de lugar puede incluir nombres alternativos para lugares, calles y otros componentes de la dirección. Estos nombres alternativos pueden diferir de los nombres que se devuelven en los campos displayName y de dirección de los resultados de Place Details para el mismo ID de lugar.
  • En este contexto, los nombres alternativos de algunos lugares pueden estar en un idioma diferente del esperado según el parámetro languageCode, según los nombres que coincidan más con la entrada del usuario.
• Un campo queryPrediction contiene información detallada sobre una sola predicción de consulta.

El objeto JSON completo tiene el siguiente formato:

{
  "suggestions": [
    {
      "placePrediction": {
        "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "text": {
          "text": "Amoeba Music, Haight Street, San Francisco, CA, USA",
          "matches": [
            {
              "endOffset": 6
            }]
        },
      ...
    },
    {
      "queryPrediction": {
        "text": {
          "text": "Amoeba Music",
          "matches": [
            {
              "endOffset": 6
            }]
        },
        ...
    }
  ...]
}

Parámetros obligatorios

entrada

Es la cadena de texto en la que se realizará la búsqueda. Especifica palabras completas y subcadenas, nombres de lugares, direcciones y Plus Codes. El servicio de Autocomplete (nuevo) devuelve posibles coincidencias en función de esta cadena y ordena los resultados según la relevancia percibida.

Parámetros opcionales

FieldMask

Especifica la lista de campos que se mostrarán en la respuesta creando una máscara de campo de respuesta. Pasa la máscara de campo de respuesta al método con el encabezado HTTP X-Goog-FieldMask.

Especifica una lista separada por comas de los campos de sugerencias que se devolverán. Por ejemplo, para recuperar el suggestions.placePrediction.text.text y el suggestions.queryPrediction.text.text de la sugerencia.

  X-Goog-FieldMask: suggestions.placePrediction.text.text,suggestions.queryPrediction.text.text

Usa * para recuperar todos los campos.

  X-Goog-FieldMask: *

includeFutureOpeningBusinesses

Si es true, devuelve las empresas que se espera que abran en el futuro. La configuración predeterminada es false.

includedPrimaryTypes

Un lugar solo puede tener un tipo principal único de los tipos que se indican en la tabla A o la tabla B. Por ejemplo, el tipo principal puede ser "mexican_restaurant" o "steak_house".

De forma predeterminada, la API devuelve todos los lugares según el parámetro input, independientemente del valor de tipo principal asociado con el lugar. Restringe los resultados para que sean de un tipo principal o de tipos principales determinados pasando el parámetro includedPrimaryTypes.

Usa este parámetro para especificar hasta cinco valores de tipo de la Tabla A o la Tabla B. Un lugar debe coincidir con uno de los valores de tipo principal especificados para incluirse en la respuesta.

Este parámetro también puede incluir, en su lugar, (regions) o (cities). El tipo (regions) filtra las recopilaciones por áreas o divisiones, como vecindarios y códigos postales. La colección de tipos (cities) filtra los lugares que Google identifica como ciudades.

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

• Si se especifican más de cinco tipos
• Se especifica cualquier tipo además de (cities) o (regions).
• Se especifican los tipos no reconocidos.

includePureServiceAreaBusinesses

Si se establece en true, la respuesta incluye las empresas que visitan a los clientes o les hacen entregas de forma directa, pero no tienen una ubicación comercial física. Si se establece en false, la API solo devuelve las empresas que tienen una ubicación física.

includeQueryPredictions

Si es true, la respuesta incluye predicciones de lugares y de búsquedas. El valor predeterminado es false, lo que significa que la respuesta solo incluye predicciones de lugares.

includedRegionCodes

Solo incluye resultados de la lista de regiones especificadas, que se indican como un array de hasta 15 valores de ccTLD ("dominio de nivel superior") de dos caracteres. Si se omite, no se aplican restricciones a la respuesta. Por ejemplo, para limitar las regiones a Alemania y Francia, haz lo siguiente:

    "includedRegionCodes": ["de", "fr"]

Si especificas locationRestriction y includedRegionCodes, los resultados se ubicarán en el área de intersección de los dos parámetros de configuración.

inputOffset

Es el desplazamiento de caracteres Unicode basado en cero que indica la posición del cursor en input. La posición del cursor puede influir en las predicciones que se devuelven. Si está vacío, el valor predeterminado es la longitud de input.

languageCode

Es el idioma preferido en el que se devolverán los resultados. Los resultados pueden estar en varios idiomas si el idioma que se usa en input es diferente del valor especificado por languageCode, o si el lugar que se devuelve no tiene una traducción del idioma local a languageCode.

• Debes usar los códigos de idioma IETF BCP-47 para especificar el idioma preferido.
• Si no se proporciona languageCode, la API usa el valor especificado en el encabezado Accept-Language. Si no se especifica ninguno, el valor predeterminado es en. Si especificas un código de idioma no válido, la API mostrará un error INVALID_ARGUMENT.
• El idioma preferido tiene una pequeña influencia en el conjunto de resultados que la API elige mostrar y en el orden en que se muestran. Esto también afecta la capacidad de la API para corregir errores ortográficos.
• Las predicciones de lugares tienen un formato diferente según la entrada del usuario en cada solicitud.
  • Primero, se eligen los términos que coinciden en el parámetro input, con nombres alineados con la preferencia de idioma que indica el parámetro languageCode, cuando está disponible, mientras que, de lo contrario, se usan los nombres que mejor coinciden con la entrada del usuario.
  • Los nombres de lugares se pueden formatear con nombres alternativos para que coincidan con los términos del parámetro input, incluidos los nombres en idiomas distintos del que se indica en el parámetro languageCode.
  • Las direcciones se formatean en el idioma local, en una escritura legible para el usuario cuando sea posible, solo después de que se hayan elegido los términos que coincidan con los términos del parámetro input.
  • Todas las demás direcciones se devuelven en el idioma preferido, después de que se eligen los términos que coinciden con los del parámetro input. Si no hay un nombre disponible en el idioma preferido, la API usa la coincidencia más cercana.

locationBias o locationRestriction

Puedes especificar locationBias o locationRestriction, pero no ambos, para definir el área de búsqueda. Piensa en locationRestriction como la especificación de la región en la que deben estar los resultados y en locationBias como la especificación de la región cerca de la que deben estar los resultados, pero que pueden estar fuera del área.

• locationBias

  Especifica un área para buscar. Esta ubicación sirve como un sesgo, lo que significa que se pueden mostrar resultados alrededor de la ubicación especificada, incluidos los resultados fuera del área especificada.

• locationRestriction

  Especifica un área para buscar. No se devuelven resultados fuera del área especificada.

Especifica la región locationBias o locationRestriction como un Viewport rectangular o como un círculo.

• Un círculo se define por el punto central y el radio en metros. El radio debe estar entre 0.0 y 50000.0, inclusive. El valor predeterminado es 0.0. Para locationRestriction, debes establecer el radio en un valor mayor que 0.0. De lo contrario, la solicitud no devolverá resultados.

  Por ejemplo:

  "locationBias": {
    "circle": {
      "center": {
        "latitude": 37.7937,
        "longitude": -122.3965
      },
      "radius": 500.0
    }
  }

• Un rectángulo es un viewport de latitud y longitud, representado como dos puntos low y altos diagonalmente opuestos. Un viewport se considera una región cerrada, lo que significa que incluye su límite. Los límites de latitud deben estar comprendidos entre -90 y 90 grados, inclusive, y los límites de longitud deben estar comprendidos entre -180 y 180 grados, inclusive:

  • Si low = high, el viewport consta de ese único punto.
  • Si low.longitude > high.longitude, el rango de longitud se invierte (el viewport cruza la línea de longitud de 180 grados).
  • Si low.longitude = -180 grados y high.longitude = 180 grados, el viewport incluye todas las longitudes.
  • Si low.longitude = 180 grados y high.longitude = -180 grados, el rango de longitud está vacío.

  Se deben propagar low y high, y el cuadro representado no puede estar vacío. Un viewport vacío genera un error.

  Por ejemplo, este viewport encierra por completo la ciudad de Nueva York:

  "locationBias": {
    "rectangle": {
      "low": {
        "latitude": 40.477398,
        "longitude": -74.259087
      },
      "high": {
        "latitude": 40.91618,
        "longitude": -73.70018
      }
    }
  }

origin

Es el punto de origen desde el que se calcula la distancia en línea recta hasta el destino (se muestra como distanceMeters). Si se omite este valor, no se mostrará la distancia en línea recta. Se debe especificar como coordenadas de latitud y longitud:

"origin": {
    "latitude": 40.477398,
    "longitude": -74.259087
}

regionCode

Es el código de región que se usa para dar formato a la respuesta, especificado como un valor de dos caracteres de ccTLD ("dominio de nivel superior"). La mayoría de los códigos 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 "Reino Unido de Gran Bretaña e Irlanda del Norte").

Las sugerencias también se sesgan según los códigos de región. Google recomienda configurar el regionCode según la preferencia regional del usuario.

Si especificas un código de región no válido, la API mostrará un error INVALID_ARGUMENT. El parámetro puede afectar los resultados según la legislación aplicable.

Cuando configuras regionCode, las predicciones dentro de esa región pueden omitir el nombre del país del texto de la sugerencia, lo que significa que structuredFormat.secondaryText podría no estar presente. Por lo tanto, asegúrate de que tu aplicación controle los casos en los que secondaryText no esté definido o falte.

sessionToken

Los tokens de sesión son cadenas generadas por el usuario que realizan un seguimiento de las llamadas de Autocomplete (nuevo) como "sesiones". Autocomplete (nuevo) usa tokens de sesión para agrupar las etapas de consulta y selección de la búsqueda con autocompletado de un usuario en una sesión discreta para realizar la facturación correspondiente. Para obtener más información, consulta Tokens de sesión.

Elige parámetros para sesgar los resultados

Ejemplos de Autocomplete (nuevo)

Restringe la búsqueda a un área con locationRestriction

locationRestriction especifica el área en la que se realizará la búsqueda. No se devuelven resultados fuera del área especificada. En el siguiente ejemplo, se usa locationRestriction para limitar la solicitud a un círculo de 5,000 metros de radio centrado en San Francisco:

curl -X POST -d '{
  "input": "Art museum",
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7749,
        "longitude": -122.4194
      },
      "radius": 5000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

Todos los resultados de las áreas especificadas se incluyen en el array suggestions:

  {
    "suggestions": [
      {
        "placePrediction": {
          "place": "places/ChIJkQQVTZqAhYARHxPt2iJkm1Q",
          "placeId": "ChIJkQQVTZqAhYARHxPt2iJkm1Q",
          "text": {
            "text": "Asian Art Museum, Larkin Street, San Francisco, CA, USA",
            "matches": [
              {
                "startOffset": 6,
                "endOffset": 16
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "Asian Art Museum",
              "matches": [
                {
                  "startOffset": 6,
                  "endOffset": 16
                }
              ]
            },
            "secondaryText": {
              "text": "Larkin Street, San Francisco, CA, USA"
            }
          },
          "types": [
            "establishment",
            "museum",
            "point_of_interest"
          ]
        }
      },
      {
        "placePrediction": {
          "place": "places/ChIJI7NivpmAhYARSuRPlbbn_2w",
          "placeId": "ChIJI7NivpmAhYARSuRPlbbn_2w",
          "text": {
            "text": "de Young Museum, Hagiwara Tea Garden Drive, San Francisco, CA, USA",
            "matches": [
              {
                "endOffset": 15
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "de Young Museum",
              "matches": [
                {
                  "endOffset": 15
                }
              ]
            },
            "secondaryText": {
              "text": "Hagiwara Tea Garden Drive, San Francisco, CA, USA"
            }
          },
          "types": [
            "establishment",
            "point_of_interest",
            "tourist_attraction",
            "museum"
          ]
        }
      },
      /.../
    ]
  }

También puedes usar locationRestriction para restringir las búsquedas a un Viewport rectangular. En el siguiente ejemplo, se limita la solicitud al centro de San Francisco:

  curl -X POST -d '{
    "input": "Art museum",
    "locationRestriction": {
      "rectangle": {
        "low": {
          "latitude": 37.7751,
          "longitude": -122.4219
        },
        "high": {
          "latitude": 37.7955,
          "longitude": -122.3937
        }
      }
    }
  }' \
  -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
  https://places.googleapis.com/v1/places:autocomplete

Los resultados se encuentran en el array suggestions:

  {
    "suggestions": [
      {
        "placePrediction": {
          "place": "places/ChIJkQQVTZqAhYARHxPt2iJkm1Q",
          "placeId": "ChIJkQQVTZqAhYARHxPt2iJkm1Q",
          "text": {
            "text": "Asian Art Museum, Larkin Street, San Francisco, CA, USA",
            "matches": [
              {
                "startOffset": 6,
                "endOffset": 16
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "Asian Art Museum",
              "matches": [
                {
                  "startOffset": 6,
                  "endOffset": 16
                }
              ]
            },
            "secondaryText": {
              "text": "Larkin Street, San Francisco, CA, USA"
            }
          },
          "types": [
            "point_of_interest",
            "museum",
            "establishment"
          ]
        }
      },
      {
        "placePrediction": {
          "place": "places/ChIJyQNK-4SAhYARO2DZaJleWRc",
          "placeId": "ChIJyQNK-4SAhYARO2DZaJleWRc",
          "text": {
            "text": "International Art Museum of America, Market Street, San Francisco, CA, USA",
            "matches": [
              {
                "startOffset": 14,
                "endOffset": 24
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "International Art Museum of America",
              "matches": [
                {
                  "startOffset": 14,
                  "endOffset": 24
                }
              ]
            },
            "secondaryText": {
              "text": "Market Street, San Francisco, CA, USA"
            }
          },
          "types": [
            "museum",
            "point_of_interest",
            "tourist_attraction",
            "art_gallery",
            "establishment"
          ]
        }
      }
    ]
  }

Cómo sesgar la búsqueda a un área con locationBias

Con locationBias, la ubicación funciona como una personalización, lo que significa que se pueden mostrar resultados alrededor de la ubicación especificada, incluidos los resultados fuera del área especificada. En el siguiente ejemplo, se sesga la solicitud al centro de San Francisco:

curl -X POST -d '{
  "input": "Amoeba",
  "locationBias": {
    "circle": {
      "center": {
        "latitude": 37.7749,
        "longitude": -122.4194
      },
      "radius": 5000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

Ahora, los resultados contienen muchos más elementos, incluidos los resultados fuera del radio de 5,000 metros:

{
  "suggestions": [
    {
      "placePrediction": {
        "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "text": {
          "text": "Amoeba Music, Haight Street, San Francisco, CA, USA",
          "matches": [
            {
              "endOffset": 6
            }
          ]
        },
        "structuredFormat": {
          "mainText": {
            "text": "Amoeba Music",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "secondaryText": {
            "text": "Haight Street, San Francisco, CA, USA"
          }
        },
        "types": [
          "electronics_store",
          "point_of_interest",
          "store",
          "establishment",
          "home_goods_store"
        ]
      }
    },
    {
      "placePrediction": {
        "place": "places/ChIJr7uwwy58hYARBY-e7-QVwqw",
        "placeId": "ChIJr7uwwy58hYARBY-e7-QVwqw",
        "text": {
          "text": "Amoeba Music, Telegraph Avenue, Berkeley, CA, USA",
          "matches": [
            {
              "endOffset": 6
            }
          ]
        },
        "structuredFormat": {
          "mainText": {
            "text": "Amoeba Music",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "secondaryText": {
            "text": "Telegraph Avenue, Berkeley, CA, USA"
          }
        },
        "types": [
          "electronics_store",
          "point_of_interest",
          "establishment",
          "home_goods_store",
          "store"
        ]
      }
    },
    ...
  ]
}

También puedes usar locationBias para sesgar las búsquedas a un Viewport rectangular. En el siguiente ejemplo, se limita la solicitud al centro de San Francisco:

  curl -X POST -d '{
    "input": "Amoeba",
    "locationBias": {
      "rectangle": {
        "low": {
          "latitude": 37.7751,
          "longitude": -122.4219
        },
        "high": {
          "latitude": 37.7955,
          "longitude": -122.3937
        }
      }
    }
  }' \
  -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
  https://places.googleapis.com/v1/places:autocomplete

Aunque en la respuesta aparecen resultados de la búsqueda dentro del viewport rectangular, algunos resultados se encuentran fuera de los límites definidos debido a la personalización. Los resultados también se encuentran dentro del array suggestions:

  {
    "suggestions": [
      {
        "placePrediction": {
          "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko",
          "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko",
          "text": {
            "text": "Amoeba Music, Haight Street, San Francisco, CA, USA",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "Amoeba Music",
              "matches": [
                {
                  "endOffset": 6
                }
              ]
            },
            "secondaryText": {
              "text": "Haight Street, San Francisco, CA, USA"
            }
          },
          "types": [
            "point_of_interest",
            "store",
            "establishment"
          ]
        }
      },
      {
        "placePrediction": {
          "place": "places/ChIJr7uwwy58hYARBY-e7-QVwqw",
          "placeId": "ChIJr7uwwy58hYARBY-e7-QVwqw",
          "text": {
            "text": "Amoeba Music, Telegraph Avenue, Berkeley, CA, USA",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "Amoeba Music",
              "matches": [
                {
                  "endOffset": 6
                }
              ]
            },
            "secondaryText": {
              "text": "Telegraph Avenue, Berkeley, CA, USA"
            }
          },
          "types": [
            "point_of_interest",
            "store",
            "establishment"
          ]
        }
      },
      {
        "placePrediction": {
          "place": "places/ChIJRdmfADq_woARYaVhnfQSUTI",
          "placeId": "ChIJRdmfADq_woARYaVhnfQSUTI",
          "text": {
            "text": "Amoeba Music, Hollywood Boulevard, Los Angeles, CA, USA",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "Amoeba Music",
              "matches": [
                {
                  "endOffset": 6
                }
              ]
            },
            "secondaryText": {
              "text": "Hollywood Boulevard, Los Angeles, CA, USA"
            }
          },
          "types": [
            "point_of_interest",
            "store",
            "establishment"
          ]
        }
      },
    /.../
    ]
  }

Usa includedPrimaryTypes

Usa el parámetro includedPrimaryTypes para especificar hasta cinco valores de tipo de la tabla A, la tabla B, o solo (regions), o solo (cities). Un lugar debe coincidir con uno de los valores de tipo principal especificados para incluirse en la respuesta.

En el siguiente ejemplo, se especifica una cadena input de "Soccer" y se usa el parámetro includedPrimaryTypes para restringir los resultados a establecimientos del tipo "sporting_goods_store":

curl -X POST -d '{
  "input": "Soccer",
  "includedPrimaryTypes": ["sporting_goods_store"],
  "locationBias": {
    "circle": {
      "center": {
        "latitude": 37.7749,
        "longitude": -122.4194
      },
      "radius": 500.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

Si omites el parámetro includedPrimaryTypes, los resultados pueden incluir establecimientos de un tipo que no deseas, como "athletic_field".

Solicita predicciones de consultas

Las predicciones de consultas no se devuelven de forma predeterminada. Usa el parámetro de solicitud includeQueryPredictions para agregar predicciones de búsqueda a la respuesta. Por ejemplo:

curl -X POST -d '{
  "input": "Amoeba",
  "includeQueryPredictions": true,
  "locationBias": {
    "circle": {
      "center": {
        "latitude": 37.7749,
        "longitude": -122.4194
      },
      "radius": 5000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

El array suggestions ahora contiene predicciones de lugares y de búsquedas, como se muestra más arriba en Acerca de la respuesta. Cada predicción de consulta incluye el campo text, que contiene una cadena de búsqueda de texto recomendada. Puedes realizar una solicitud de Text Search (nueva) para obtener más información sobre cualquiera de las predicciones de búsqueda que se devuelven.

Usar origen

En este ejemplo, incluye origin en la solicitud como coordenadas de latitud y longitud. Cuando incluyes origin, Autocomplete (nuevo) incluye el campo distanceMeters en la respuesta, que contiene la distancia en línea recta desde el origin hasta el destino. En este ejemplo, se establece el origen en el centro de San Francisco:

curl -X POST -d '{
  "input": "Amoeba",
  "origin": {
    "latitude": 37.7749,
    "longitude": -122.4194
  },
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7749,
        "longitude": -122.4194
      },
      "radius": 5000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

La respuesta ahora incluye distanceMeters:

{
  "suggestions": [
    {
      "placePrediction": {
        "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "text": {
          "text": "Amoeba Music, Haight Street, San Francisco, CA, USA",
          "matches": [
            {
              "endOffset": 6
            }
          ]
        },
        "structuredFormat": {
          "mainText": {
            "text": "Amoeba Music",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "secondaryText": {
            "text": "Haight Street, San Francisco, CA, USA"
          }
        },
        "types": [
          "home_goods_store",
          "establishment",
          "point_of_interest",
          "store",
          "electronics_store"
        ],
        "distanceMeters": 3012
      }
    }
  ]
}

Cómo encontrar empresas que abrirán en el futuro

En el siguiente ejemplo, se muestra una solicitud de Autocomplete (nuevo) para empresas que abrirán en el futuro en New Meadows, Idaho:

curl -X POST \
-H "Content-Type: application/json" \
-H "X-Goog-Api-Key: API_KEY" \
-d '{
  "input": "Roberts Greenhouse and Tree Farm",
  "includeFutureOpeningBusinesses": true,
  "locationBias": {
    "circle": {
      "center": {"latitude": 44.9755100, "longitude": -116.2842180},
      "radius": 20
    }
  }
}' \
"https://places.googleapis.com/v1/places:autocomplete"

La respuesta incluye detalles sobre el lugar, pero no la fecha de apertura.

{
  "suggestions": [
    {
      "placePrediction": {
        "place": "places/ChIJp1-VoKWJplQRMz8g-7Wa3Do",
        "placeId": "ChIJp1-VoKWJplQRMz8g-7Wa3Do",
        "text": {
          "text": "Roberts Greenhouse and Tree Farm, McLain Street, New Meadows, ID, USA",
          "matches": [
            {
              "endOffset": 32
            }
          ]
        },
        "structuredFormat": {
          "mainText": {
            "text": "Roberts Greenhouse and Tree Farm",
            "matches": [
              {
                "endOffset": 32
              }
            ]
          },
          "secondaryText": {
            "text": "McLain Street, New Meadows, ID, USA"
          }
        },
        "types": [
          "garden_center",
          "establishment",
          "service",
          "store",
          "point_of_interest"
        ]
      }
    }
  ]
}

Falta la distancia en la respuesta

En ciertos casos, falta distanceMeters en el cuerpo de la respuesta, incluso cuando se incluye origin en la solicitud. Esto puede suceder en las siguientes situaciones:

• distanceMeters no se incluye en las predicciones de route.
• distanceMeters no se incluye cuando su valor es 0, que es el caso de las predicciones que están a menos de 1 metro de la ubicación de origin proporcionada.

Las bibliotecas cliente que intenten leer el campo distanceMeters de un objeto analizado mostrarán un campo con el valor 0. Para evitar confundir a los usuarios, no les muestres una distancia de cero.

Optimización de Autocomplete (nuevo)

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

A continuación, se indican algunos lineamientos generales:

• La forma más rápida de desarrollar una interfaz de usuario funcional es usar el widget de Autocomplete (nuevo) de la API de Maps JavaScript, el widget de Autocomplete (nuevo) del SDK de Places para Android o el widget de Autocomplete (nuevo) del SDK de Places para iOS.
• Comprende los campos de datos esenciales de Autocomplete (nuevo) 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 de Autocomplete (nuevo), usa máscaras de campo en los widgets de Place Details (nuevo) y Autocomplete (nuevo), que te permiten mostrar solo los campos de datos de Autocomplete (nuevo) que necesitas.

Optimización avanzada de los costos

Considera utilizar la implementación programática de Autocomplete (nuevo) para acceder a los precios del SKU: Autocomplete Request y solicitar resultados de la API de Geocoding sobre el lugar seleccionado en lugar de utilizar Place Details (nuevo). 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 (nueva).
• Si los usuarios seleccionan una predicción de autocompletar con un promedio de cuatro solicitudes de Autocomplete (New) o menos, el precio por solicitud puede ser más rentable que el precio por sesión.

La API de Geocoding podría ser una opción más rentable que Place Details (nueva) para tu aplicación, según el rendimiento de su uso de Autocomplete (nueva). La eficiencia de Autocomplete (New) 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 encontrar la cantidad promedio de solicitudes de la tabla, analiza cuántos caracteres escribe un usuario en promedio antes de seleccionar una predicción de Autocomplete (nuevo) en tu aplicación.

Autocomplete (nuevo) basado en sesiones con Place Details (nuevo)

Usa Autocomplete (nuevo) basado en sesiones con Place Details (nuevo).
Dado que tu aplicación requiere Place Details (nuevo), como el nombre del lugar, el estado de la empresa o el horario de atención, tu implementación de Autocomplete (nuevo) 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 SKUs de Places aplicables, según los campos de datos de lugar que solicites.¹

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 Autocomplete (nuevo) y Place Details (nuevo) en la predicción seleccionada. Asegúrate de especificar el parámetro fields para asegurarte de solicitar únicamente los campos de datos de Autocomplete (nuevo) que necesitas.

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

1. El ID de lugar de la respuesta de Autocomplete (nuevo)
2. Es el token de sesión que se utilizó en la solicitud de Autocomplete (nuevo).
3. El parámetro fields que especifica los campos de datos de Autocomplete (nuevo) que necesitas

Autocomplete (nuevo) por solicitud con la API de Geocoding

Implementa Autocomplete (nuevo) 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 más una llamada a la API de Geocoding sobre la predicción de lugar seleccionada cuesta menos que el precio por sesión de Autocomplete (nuevo).¹

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

Autocomplete basado en sesiones (nuevo) para aplicaciones que solo usan direcciones

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

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 Autocomplete (nuevo) y Place Details (nuevo) 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 Autocomplete (nuevo). Cuando solicites la predicción seleccionada a Place Details (nuevo), incluye los siguientes parámetros:

1. El ID de lugar de la respuesta de Autocomplete (nuevo)
2. Es el token de sesión que se utilizó en la solicitud de Autocomplete (nuevo).
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 Autocomplete (nuevo)
Puedes emplear estrategias como demorar una solicitud de Autocomplete (nuevo) hasta que el usuario escriba los primeros tres o cuatro caracteres para que tu aplicación realice menos solicitudes. Por ejemplo, si realizas solicitudes de Autocomplete (New) para cada carácter después de que el usuario escribe 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 de 4 solicitudes de Autocomplete (New) por solicitud + Geocoding.¹

Si retrasar las solicitudes puede hacer que tu solicitud programática promedio sea inferior a cuatro, puedes seguir las instrucciones para implementar Autocomplete (nuevo) 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.

Prácticas recomendadas para el rendimiento

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

• 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 Autocomplete (nuevo). 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 Autocomplete (nuevo) 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 Autocomplete (New), generalmente, porque ninguna de ellas indica el 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 (nuevo). 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 sublocales, como direcciones de unidades o departamentos específicos dentro de un edificio Por ejemplo, la dirección checa "Stroupežnického 3191/17, Praha" genera una predicción parcial en Autocomplete (nuevo).
  • 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

Sesgo de ubicación

Personaliza los resultados para un área específica pasando los parámetros location y radius. Esto le indica a Autocomplete (nuevo) 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 que se encuentran dentro de un país específico.

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 locationRestriction. Esto le indica a Autocomplete (nuevo) que devuelva solo los resultados de esa región.

Pruébalo

El Explorador de APIs te permite realizar solicitudes de ejemplo para que puedas familiarizarte con la API y sus opciones.

1. Selecciona el ícono de API api en el lado derecho de la página.

2. De manera opcional, edita los parámetros de solicitud.

3. Selecciona el botón Ejecutar. En el cuadro de diálogo, elige la cuenta que deseas usar para realizar la solicitud.

4. En el panel del Explorador de APIs, selecciona el ícono de pantalla completa fullscreen para expandir la ventana del Explorador de APIs.