Autocompletar (nuevo)

Selecciona la plataforma: Android iOS JavaScript Servicio web

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

El servicio Autocomplete (nuevo) puede coincidir con palabras completas y de la entrada, resolver nombres de lugares, direcciones y Plus Codes. Por lo tanto, 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 (nueva) puede contener dos tipos de predicciones:

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

Por ejemplo, llamas 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, California. La respuesta contiene un 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 del lugar que se muestran están diseñadas para que se las presente al usuario y, así, ayudar a a ellos a la hora de seleccionar el lugar deseado. Puedes crear un Place Details (nuevo) para obtener más información sobre cualquiera de las predicciones de lugares devueltas.

La respuesta también puede contener una lista de predicciones de consulta que coincidan con cadena de búsqueda y área de búsqueda, como "Pizza siciliana y Pasta". Cada predicción de consulta en la incluye el campo text, que contiene una cadena de búsqueda de texto recomendada. Usar eso una cadena como entrada para Text Search (nueva) para realizar 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 el Opciones de API:

Pruébalo

Solicitudes a Autocomplete (nuevas)

Una solicitud de Autocomplete (nueva) es una solicitud HTTP POST a una URL en el formulario:

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

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 consultas de predicción en orden. según la relevancia percibida. Cada lugar está representado por un placePrediction y cada consulta está representada por un campo queryPrediction.
  • El campo placePrediction contiene información detallada sobre un solo la predicción del sitio, incluido el ID del lugar y la descripción del texto.
  • El campo queryPrediction contiene información detallada sobre un solo para la predicción de consultas.

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) devuelve 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 de los tipos que se indican en En la Tabla A o Tabla B. Por ejemplo: el tipo principal puede ser "mexican_restaurant" o "steak_house".

    De forma predeterminada, la API muestra todos los lugares según el parámetro input, sin importar del valor de tipo primario asociado con el lugar. Restringir los resultados para que sean de un determinado tipo primario o tipos primarios pasando el parámetro includedPrimaryTypes.

    Usa este parámetro para especificar hasta cinco valores de tipo de la Tabla A. Tabla B. Un lugar debe coincide con uno de los valores de tipo principal especificado que se incluirán en la respuesta.

    Este parámetro también puede incluir, en cambio, uno de (regions) o (cities). El conjunto de tipos (regions) filtra las áreas o divisiones, como vecindarios y códigos postales. El conjunto de tipos (cities) filtra los lugares que Google identifica como ciudad.

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

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

  • includeQueryPredictions

    Si es true, la respuesta incluye las predicciones de lugar y de consulta. Predeterminado el valor es false, lo que significa que la respuesta solo incluye predicciones de lugares.

  • includedRegionCodes

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

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

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

  • inputOffset

    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 muestran. Si está vacía, el valor predeterminado es el de input.

  • languageCode

    El idioma preferido en el que se mostrarán los resultados. Es posible que los resultados estén en varios idiomas. si el idioma que se usa en input es diferente del valor especificado por languageCode o si el lugar que se muestra no tiene una traducción del idioma local al languageCode.

    • Debes usar IETF Códigos de idioma según la norma 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 devuelve un INVALID_ARGUMENT error.
    • El idioma preferido influye poco en el conjunto de resultados que que la API elige devolver y el orden en el que se muestran. Esto también afecta la capacidad de la API de 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 y, al mismo tiempo, reflejará las entradas de los usuarios. Las predicciones de lugares tienen un formato diferente según la entrada del usuario en cada solicitud.
      • Los términos coincidentes del parámetro input se eligen primero, utilizando los nombres alineados. con la preferencia de idioma indicada por el parámetro languageCode cuando disponibles, mientras que, de lo contrario, usarán nombres que coincidan mejor con la entrada del usuario.
      • Las direcciones tienen el formato del idioma local, en una secuencia de comandos legible para el usuario cuando sea posible, solo después de que se hayan seleccionado los términos coincidentes para que coincidan con los términos del Parámetro input.
      • Todas las demás direcciones se devuelven en el idioma preferido, una vez que los términos coincidentes han se eligió para que coincida con los términos del parámetro input. Si un nombre no es disponible en el idioma preferido, la API usa la coincidencia más cercana.

  • locationBias o locationRestriction

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

    • locationBias

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

    • locationRestriction

      Especifica un área de búsqueda. Los resultados fuera del área especificada no se muestran que se devuelven.

    Especifica la región locationBias o locationRestriction como un una ventana gráfica 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 50, 000.0 inclusive. El valor predeterminado es 0.0. Para locationRestriction, debe establecer el radio en un valor superior a 0.0. De lo contrario, la solicitud muestra ningún resultado.

      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 en diagonal opuesta a low y puntos superiores. Un viewport se considera un región cerrada, lo que significa que incluye su límite. Los límites de latitud debe variar entre -90 y 90 grados inclusive, y los límites de longitud debe oscilar entre -180 y 180 grados inclusive:

      • Si low = high, el viewport consta de ese solo 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 intervalo de longitud está vacío.

      Se deben completar tanto low como high, 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 al destino (se muestra como distanceMeters). Si este valor es se omite, no se devolverá la distancia en línea recta. Se debe especificar como coordenadas de latitud y longitud:

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

  • regionCode

    El código de región que se usa para dar formato a la respuesta, especificado como una ccTLD ("dominio de nivel superior") un valor 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 el código ISO 3166-1 es "gb" (técnicamente para el del "Reino Unido de Gran Bretaña e Irlanda del Norte").

    Si especificas un código de región no válido, la API muestra un 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 Autocomplete Llamadas (nuevas) como "sesiones". Autocomplete (nuevo) usa tokens de sesión para agrupar las fases de consulta y selección de una búsqueda de autocompletado del usuario en una sesión discreta para facturación. Para obtener más información, consulta Tokens de sesión.

Ejemplos de Autocomplete (nuevo)

Cómo usar locationRestriction y locationBias

La API usa la personalización de IP de forma predeterminada para controlar el área de búsqueda. Con la personalización de IP, la API utiliza el 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 que se buscará. Resultados fuera del área especificada no se devuelven. En el siguiente ejemplo, se usa locationRestriction para limitar la solicitud a un círculo de 5000 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 que se encuentran dentro 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 un sesgo, lo que significa que se obtienen resultados alrededor de la se puede obtener la ubicación especificada, incluso resultados fuera del área especificada. En la próxima Por ejemplo, debes cambiar 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 especificar hasta cinco valores de tipo de Tabla A, Tabla B, o solo (regions) o solo (cities). Un lugar debe coincidir con uno de los valores especificados valores de tipo primario que se incluirán en la respuesta.

En el siguiente ejemplo, especificas una cadena input de “Fútbol” y usar 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 consulta no se muestran de forma predeterminada. Usa el includeQueryPredictions request 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 consultas. 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 crear un Text Search (nueva) para obtener más información sobre cualquiera de las predicciones de consulta devueltas.

Usar origen

En este ejemplo, incluye origin en la solicitud como coordenadas de latitud y longitud. Cuando incluyes origin, la API incluye el campo distanceMeters en el 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
      }
    }
  ]
}

Pruébalo

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

  1. Selecciona el ícono de la API, Expande el Explorador de APIs., en el lado derecho de la página.
  2. De manera opcional, expande Mostrar parámetros estándar y establece el parámetro fields a la máscara de campo.
  3. De manera opcional, edita el Cuerpo de la solicitud.
  4. Selecciona el botón Ejecutar. En la ventana emergente, elige la cuenta que deseas usar para realizar la solicitud.

  5. En el panel Explorador de APIs, selecciona el ícono de expansión, Expande el Explorador de APIs., para expandir la ventana del Explorador de API