Autocompletar (nuevo)

El servicio Autocomplete (nuevo) es un servicio web que muestra predicciones de lugares y consultas en respuesta a una solicitud HTTP. En la solicitud, especifica una cadena de búsqueda de texto y límites geográficos que controlen el área de búsqueda.

El servicio Autocomplete (nuevo) puede buscar coincidencias para palabras completas y subcadenas de la entrada para resolver 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 consultas en el momento.

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

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

Por ejemplo, puedes llamar a la API usando como entrada una cadena que contiene una entrada parcial del usuario, "piz siciliano", con el área de búsqueda limitada a San Francisco, CA. La respuesta contiene una lista de predicciones de lugares que coinciden con la cadena de búsqueda 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 muestran están diseñadas para presentarse al usuario con el fin de 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 lugar que se muestran.

La respuesta también puede contener una lista de predicciones de consulta que coinciden con la cadena y el área de búsqueda, como “Pizza y pasta sicilianas”. Cada predicción de consulta en la respuesta incluye el campo text que contiene una string de búsqueda de texto recomendada. Usa esa string como entrada a Text Search (nuevo) para realizar una búsqueda más detallada.

Solicitudes a Autocomplete (nuevo)

Una solicitud de Autocomplete (nuevo) es una solicitud HTTP POST a una URL que tiene 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

Cómo hacer una solicitud con la función Autocompletar (nuevo)

La API de Places es compatible con las APIs existentes de Autocomplete y Query Autocomplete. Si estás familiarizado con estas APIs, la versión preliminar de Autocomplete (nuevo) realiza los siguientes cambios:

  • El nuevo Autocomplete usa solicitudes HTTP POST. Pasa parámetros en el cuerpo de la solicitud o en los encabezados como parte de una solicitud HTTP POST. Por el contrario, con las APIs existentes, debes pasar los parámetros de URL mediante una solicitud HTTP GET.
  • El nuevo autocompletado admite claves de API y tokens OAuth como mecanismo de autenticación.
  • En el nuevo Autocomplete, solo se admite JSON como formato de respuesta.

En la siguiente tabla, se enumeran los parámetros de las APIs existentes de Autocomplete y Query Autocomplete que cambiaron de nombre o se modificaron para la nueva versión de Autocomplete, o bien los parámetros que ya no se admiten.

Parámetro actual Parámetro nuevo Notas
components includedRegionCodes
language languageCode
location locationBias
ipbias Si omites locationBias y locationRestriction, la API usa la personalización de IP de forma predeterminada.
offset inputOffset
radius locationBias o locationRestriction
region regionCode
stricbounds locationRestriction
sessiontoken sessionToken
types includedPrimaryTypes

Límites de uso

Durante la versión preliminar, solo puedes hacer un máximo de 600 consultas por minuto, por proyecto.

Opciones de asistencia para las versiones preliminares

Si bien Google no tiene la obligación de brindar asistencia para las versiones, características o funciones de Versión preliminar de los Servicios, consideraremos las solicitudes en estas etapas de desarrollo según cada caso.

  • Las versiones previas al lanzamiento no están cubiertas por el ANS de Google Maps Platform.
  • Se recomienda el uso de mecanismos de resguardo, en especial si usas una versión previa al lanzamiento en un entorno de producción. Estos son algunos ejemplos de situaciones de resguardo: cuota excedida, latencia y códigos de respuestas inesperados, o respuestas inesperadas en comparación con el Autocomplete existente.

Puedes usar la Herramienta de seguimiento de errores para solicitar funciones nuevas o sugerir modificaciones de las funciones existentes. Describe la funcionalidad específica que desees que se agregue y las razones por las que crees que es importante. Si es posible, incluye detalles específicos sobre tu caso de uso y las nuevas oportunidades que proporcionaría la función:

Si tienes alguna otra pregunta sobre las funciones, envía un correo electrónico a newplacesapi@google.com.

Acerca de la respuesta

Autocomplete (nuevo) muestra 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 la relevancia percibida. Cada lugar está representado por un campo placePrediction y cada consulta está representada por un campo queryPrediction.
  • El campo placePrediction contiene información detallada sobre la predicción de un solo lugar, como el ID de lugar y una descripción de texto.
  • 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

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

Parámetros opcionales

  • includedPrimaryTypes

    Un lugar solo puede tener un tipo principal asociado a los tipos Tabla A o Tabla B. Por ejemplo, el tipo principal podría ser "mexican_restaurant" o "steak_house".

    De forma predeterminada, la API muestra todos los lugares según el parámetro input, independientemente del valor del tipo principal asociado con el lugar. Si quieres restringir los resultados para que sean de un tipo o tipo primario determinados, pasa 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 que se incluya en la respuesta.

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

    • Se especifican más de cinco tipos.
    • Se especifican los tipos no reconocidos.

  • includeQueryPredictions

    Si es true, la respuesta incluye predicciones de lugares y consultas. 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, especificadas como un array de hasta 15 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 tanto locationRestriction como includedRegionCodes, los resultados se ubicarán en el área de intersección de las dos configuraciones.

  • inputOffset

    El desplazamiento del carácter 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 muestran. Si está vacío, el valor predeterminado es la longitud de input.

  • languageCode

    El idioma preferido en el que se mostrarán los resultados. Los resultados pueden estar en idiomas mixtos si el idioma utilizado en input es diferente del valor especificado en languageCode o si el lugar que se muestra no tiene una traducción del idioma local a languageCode.

    • Debes usar 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 el orden en el que se muestran. Esto también afecta la capacidad de la API para corregir errores de ortografía.
    • La API intenta proporcionar una dirección que sea legible tanto para el usuario como para la población local, a la vez que refleja la entrada del usuario. Las predicciones de lugar tienen un formato diferente según la entrada del usuario en cada solicitud.
      • Los términos coincidentes del parámetro input se eligen primero con nombres alineados con la preferencia de idioma que indica el parámetro languageCode cuando están disponibles, mientras que, de lo contrario, se usan los nombres que mejor coinciden con la entrada del usuario.
      • Las direcciones se formatean en el idioma local, en una secuencia de comandos que el usuario puede leer cuando es posible, solo después de que se hayan elegido los términos coincidentes para que coincidan con los términos del parámetro input.
      • Todas las demás direcciones se muestran en el idioma preferido, después de que se hayan elegido los términos coincidentes para que coincidan con los del parámetro input. Si un nombre no está 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 región en la que se especificarán los resultados, y como en locationBias, como en la región donde los resultados deben encontrarse cerca, pero pueden estar fuera del área.

    • locationBias

      Especifica un área de búsqueda. Esta ubicación sirve como sesgo, lo que significa que se pueden mostrar resultados en torno a la ubicación especificada, incluso resultados fuera del área especificada.

    • locationRestriction

      Especifica un área de búsqueda. No se muestran los resultados fuera del área especificada.

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

    • Un círculo se define por el punto central y el radio en metros. El radio debe ser entre 0.0 y 50,000.0, inclusive. El valor predeterminado es 0.0. Para locationRestriction, debes establecer el radio en un valor superior a 0.0. De lo contrario, la solicitud no muestra 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 por dos puntos altos y low diagonalmente opuestos. Una viewport se considera una región cerrada, lo que significa que incluye su límite. Los límites de latitud deben variar entre -90 y 90 grados inclusive, y los límites de longitud deben variar 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 estará vacío.

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

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

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

  • origin

    Punto de origen a partir del cual 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 deben especificar como coordenadas de latitud y longitud:

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

  • regionCode

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

    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 ley aplicable.

  • sessionToken

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

Ejemplos de autocompletado (nuevo)

Cómo usar locationRestriction y locationBias

La API utiliza la personalización de IP de forma predeterminada para controlar el área de búsqueda. Con la personalización de IP, la API utiliza la dirección IP del dispositivo para personalizar los resultados. De manera opcional, puedes usar locationRestriction o locationBias, pero no ambos, para especificar un área de búsqueda.

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": "Amoeba",
  "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 encuentran en el 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": [
          "home_goods_store",
          "establishment",
          "store",
          "point_of_interest",
          "electronics_store"
        ]
      }
    }
  ]
}

Con locationBias, la ubicación sirve como sesgo, lo que significa que se pueden mostrar resultados en torno a la ubicación especificada, incluidos los resultados fuera del área especificada. En el siguiente ejemplo, cambiarás la solicitud para usar locationBias:

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

Los resultados ahora contienen muchos más elementos, incluso resultados fuera del radio de 5000 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"
        ]
      }
    },
    ...
  ]
}

Usa includePrimaryTypes

Usa el parámetro includedPrimaryTypes para restringir los resultados de una solicitud de modo que sean de un tipo determinado, como se indica en la Tabla A y la Tabla B. Puedes especificar un array de hasta cinco valores. Si se omite, se muestran todos los tipos.

En el siguiente ejemplo, se especifica una cadena input de "Soccer" y se usa el parámetro includedPrimaryTypes para restringir los resultados a establecimientos de 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 consulta

Las predicciones de consulta no se muestran de forma predeterminada. Usa el parámetro de solicitud includeQueryPredictions para agregar predicciones de consulta 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 predicciones de consulta, como se muestra más arriba en la sección Acerca de la respuesta. Cada predicción de consulta incluye el campo text, que contiene una string de búsqueda de texto recomendada. Puedes realizar una solicitud de Text Search (nuevo) para obtener más información sobre cualquiera de las predicciones de consulta que se muestran.

Usar origen

En este ejemplo, se incluye origin en la solicitud como coordenadas de latitud y longitud. Cuando incluyes origin, la API incluye el campo distanceMeters en la respuesta que contiene la distancia en línea recta desde 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
      }
    }
  ]
}