Preenchimento automático (novo)

Introdução

O Autocomplete (novo) é um serviço da Web que retorna previsões de lugares e de consultas em resposta a uma solicitação HTTP. Na solicitação, especifique uma string de pesquisa de texto e os limites geográficos que controlam a área de pesquisa.

O Autocomplete (New) pode trazer palavras completas e substrings da entrada, sugerindo nomes e endereços de lugares, além de Plus Codes. À medida que a pessoa digita, os aplicativos enviam consultas e sugerem previsões de local e consulta instantaneamente.

A resposta do Autocomplete (novo) pode conter dois tipos de previsões:

• Previsões de lugares: lugares, como empresas, endereços e pontos de interesse, com base na string de texto de entrada e na área de pesquisa especificadas. As previsões de lugar são retornadas por padrão.
• Previsões de consulta: strings de consulta que correspondem à string de texto de entrada e à área de pesquisa. As previsões de consulta não são retornadas por padrão. Use o parâmetro de solicitação includeQueryPredictions para adicionar previsões de consulta à resposta.

Por exemplo, você chama o Autocomplete (novo) usando como entrada uma string que contém uma entrada parcial do usuário, "Sicilian piz", com a área de pesquisa limitada a São Francisco, CA. A resposta contém uma lista de previsões de lugares que correspondem à string e à área de pesquisa, como o restaurante "Sicilian Pizza Kitchen", além de detalhes sobre o local.

As previsões de lugar retornadas são projetadas para serem apresentadas ao usuário para ajudá-lo a selecionar o lugar pretendido. Faça uma solicitação do Place Details (novo) para receber mais informações sobre qualquer uma das previsões de lugar retornadas.

A resposta também pode conter uma lista de previsões de consulta que correspondem à string e à área de pesquisa, como "Pizza e massa siciliana". Cada previsão de consulta na resposta inclui o campo text, que contém uma string de Text Search recomendada. Use essa string como entrada para o Text Search (novo) para realizar uma pesquisa mais detalhada.

O APIs Explorer permite fazer solicitações em tempo real para que você se familiarize com a API e as opções dela:

Solicitações do Autocomplete (novo)

Uma solicitação do Autocomplete (New) é uma solicitação HTTP POST para um URL no formato:

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

Transmita todos os parâmetros no corpo da solicitação JSON ou nos cabeçalhos como parte da solicitação POST. Exemplo:

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 aceitos

Sobre a resposta

O Autocomplete (novo) retorna um objeto JSON como resposta. Na resposta:

• A matriz suggestions contém todos os lugares e consultas previstos em ordem, com base na relevância percebida. Cada lugar é representado por um campo placePrediction, e cada consulta é representada por um campo queryPrediction.
• Um campo placePrediction contém informações detalhadas sobre uma única previsão de lugar, incluindo o ID de lugar e a descrição de texto.
  • Para corresponder melhor à entrada do usuário fornecida no parâmetro input, a descrição de texto de uma previsão de lugar pode incluir nomes alternativos para lugares, ruas e outros componentes de endereço. Esses nomes alternativos podem ser diferentes dos nomes retornados nos campos displayName e de endereço dos resultados do Place Details para o mesmo ID de lugar.
  • Nesse contexto, os nomes alternativos de alguns lugares podem estar em um idioma diferente do esperado com base no parâmetro languageCode, dependendo de quais nomes correspondem mais à entrada do usuário.
• Um campo queryPrediction contém informações detalhadas sobre uma única previsão de consulta.

O objeto JSON completo está no 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 obrigatórios

entrada

A string de texto em que a pesquisa será feita. Especifique palavras completas e substrings, nomes de lugares, endereços e Plus Codes. O serviço Autocomplete (novo) retorna as correspondências possíveis de acordo com essa string e ordena os resultados com base na relevância.

Parâmetros opcionais

FieldMask

Especifique a lista de campos a serem retornados na resposta criando uma máscara de campo de resposta. Transmita a máscara de campo de resposta ao método usando o cabeçalho HTTP X-Goog-FieldMask.

Especifique uma lista separada por vírgulas de campos de sugestão a serem retornados. Por exemplo, para recuperar o suggestions.placePrediction.text.text e o suggestions.queryPrediction.text.text da sugestão.

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

Use * para recuperar todos os campos.

  X-Goog-FieldMask: *

includeFutureOpeningBusinesses

Se for true, retorna empresas que devem abrir no futuro. O padrão é false.

includedPrimaryTypes

Um lugar só pode ter um único tipo principal entre os tipos listados na Tabela A ou na Tabela B. Por exemplo, o tipo principal pode ser "mexican_restaurant" ou "steak_house".

Por padrão, a API retorna todos os lugares com base no parâmetro input, independentemente do valor do tipo principal associado ao lugar. Restrinja os resultados a um ou mais tipos principais transmitindo o parâmetro includedPrimaryTypes.

Use esse parâmetro para especificar até cinco valores de tipo da Tabela A ou da Tabela B. Um lugar precisa corresponder a um dos valores de tipo principal especificados para ser incluído na resposta.

Esse parâmetro também pode incluir (regions) ou (cities). A coleção de tipos (regions) filtra áreas ou divisões, como bairros e códigos postais. A coleção de tipos (cities) filtra os lugares que o Google identifica como uma cidade.

A solicitação será rejeitada com um erro INVALID_REQUEST se:

• Mais de cinco tipos foram especificados.
• Qualquer tipo for especificado além de (cities) ou (regions).
• Tipos não reconhecidos são especificados.

includePureServiceAreaBusinesses

Se definido como true, a resposta inclui empresas que visitam ou entregam diretamente aos clientes, mas não têm um local físico. Se definido como false, a API vai retornar apenas empresas com um local físico.

includeQueryPredictions

Se for true, a resposta vai incluir previsões de lugar e de consulta. O valor padrão é false, o que significa que a resposta inclui apenas previsões de lugar.

includedRegionCodes

Inclua apenas resultados da lista de regiões especificadas, apresentadas como uma matriz de até 15 valores de dois caracteres de ccTLD ("domínio de nível superior"). Se omitido, nenhuma restrição será aplicada à resposta. Por exemplo, para limitar as regiões à Alemanha e à França:

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

Se você especificar locationRestriction e includedRegionCodes, os resultados vão estar na área de interseção das duas configurações.

inputOffset

O deslocamento de caracteres Unicode baseado em zero que indica a posição do cursor em input. A posição do cursor pode influenciar as previsões retornadas. Se estiver vazio, o padrão será o comprimento de input.

languageCode

O idioma preferencial para retornar os resultados. Os resultados podem estar em idiomas mistos se o idioma usado em input for diferente do valor especificado por languageCode ou se o lugar retornado não tiver uma tradução do idioma local para languageCode.

• Use os códigos de idioma IETF BCP-47 para especificar o idioma de preferência.
• Se languageCode não for fornecido, a API vai usar o valor especificado no cabeçalho Accept-Language. Se nenhum for especificado, o padrão será en. Se você especificar um código de idioma inválido, a API vai retornar um erro INVALID_ARGUMENT.
• O idioma preferencial tem uma pequena influência no conjunto de resultados que a API escolhe retornar e na ordem em que eles são retornados. Isso também afeta a capacidade da API de corrigir erros de ortografia.
• As previsões de lugar são formatadas de maneira diferente, dependendo da entrada do usuário em cada solicitação.
  • Os termos correspondentes no parâmetro input são escolhidos primeiro, usando nomes alinhados com a preferência de idioma indicada pelo parâmetro languageCode, quando disponível. Caso contrário, são usados nomes que melhor correspondem à entrada do usuário.
  • Os nomes de lugares podem ser formatados usando nomes alternativos para corresponder aos termos no parâmetro input, incluindo nomes em idiomas diferentes daquele indicado pelo parâmetro languageCode.
  • Os endereços são formatados no idioma local, em um script legível para o usuário, quando possível, somente depois que os termos correspondentes forem selecionados para corresponder aos termos no parâmetro input.
  • Todos os outros endereços são retornados no idioma preferencial, depois que os termos correspondentes são escolhidos para corresponder aos termos no parâmetro input. Se um nome não estiver disponível no idioma preferido, a API vai usar a correspondência mais próxima.

locationBias ou locationRestriction

É possível especificar locationBias ou locationRestriction, mas não ambos, para definir a área de pesquisa. Pense em locationRestriction como a especificação da região em que os resultados precisam estar e em locationBias como a especificação da região em que os resultados precisam estar próximos, mas podem estar fora da área.

• locationBias

  Especifica uma área para pesquisar. Esse local serve como uma polarização, o que significa que os resultados em torno do local especificado podem ser retornados, incluindo resultados fora da área especificada.

• locationRestriction

  Especifica uma área para pesquisar. Os resultados fora da área especificada não são retornados.

Especifique a região locationBias ou locationRestriction como uma janela de visualização retangular ou como um círculo.

• Um círculo é definido pelo ponto central e pelo raio em metros. O raio precisa estar entre 0,0 e 50.000,0, inclusive. O valor padrão é 0,0. Para locationRestriction, é preciso definir o raio como um valor maior que 0.0. Caso contrário, a solicitação não vai retornar resultados.

  Exemplo:

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

• Um retângulo é uma janela de visualização de latitude e longitude, representada como dois pontos low e altos diagonalmente opostos. Uma janela de visualização é considerada uma região fechada, ou seja, inclui o limite. Os limites de latitude precisam estar entre -90 e 90 graus, e os limites de longitude precisam estar entre -180 e 180 graus:

  • Se low = high, a janela de visualização consiste nesse único ponto.
  • Se low.longitude > high.longitude, o intervalo de longitude será invertido (a janela de visualização cruza a linha de longitude de 180 graus).
  • Se low.longitude = -180 graus e high.longitude = 180 graus, a janela de visualização inclui todas as longitudes.
  • Se low.longitude = 180 graus e high.longitude = -180 graus, o intervalo de longitude fica vazio.

  low e high precisam ser preenchidos, e a caixa representada não pode estar vazia. Uma janela de visualização vazia resulta em um erro.

  Por exemplo, esta janela de visualização inclui totalmente a cidade de Nova York:

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

origem

O ponto de origem para calcular a distância em linha reta até o destino (retornado como distanceMeters). Se esse valor for omitido, a distância em linha reta não será retornada. Precisa ser especificado como coordenadas de latitude e longitude:

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

regionCode

O código de região usado para formatar a resposta, especificado como um valor de dois caracteres de ccTLD ("domínio de nível superior"). A maioria dos códigos ccTLD é idêntica aos códigos ISO 3166-1, com algumas exceções notáveis. Por exemplo, o ccTLD do Reino Unido é "uk" (.co.uk), enquanto o código ISO 3166-1 é "gb" (tecnicamente para a entidade "Reino Unido da Grã-Bretanha e Irlanda do Norte").

As sugestões também são influenciadas pelos códigos de região. O Google recomenda definir o regionCode de acordo com a preferência regional do usuário.

Se você especificar um código de região inválido, a API vai retornar um erro INVALID_ARGUMENT. O parâmetro pode afetar os resultados com base na legislação aplicável.

Quando você define regionCode, as previsões dentro dessa região podem omitir o nome do país do texto da sugestão, o que significa que structuredFormat.secondaryText pode não estar presente. Portanto, verifique se o aplicativo processa casos em que secondaryText é indefinido ou está ausente.

sessionToken

Os tokens de sessão são strings geradas pelo usuário que rastreiam as chamadas do Autocomplete (New) como "sessões". O Autocomplete (novo) usa tokens de sessão para agrupar as fases de consulta e seleção de uma pesquisa de preenchimento automático do usuário em uma sessão discreta para fins de faturamento. Para mais informações, consulte Tokens de sessão.

Escolher parâmetros para influenciar os resultados

Exemplos do Autocomplete (novo)

Restringir a pesquisa a uma área usando locationRestriction

locationRestriction especifica a área a ser pesquisada. Os resultados fora da área especificada não são retornados. No exemplo a seguir, use locationRestriction para limitar a solicitação a um círculo de 5.000 metros de raio centralizado em 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 os resultados das áreas especificadas estão contidos na matriz 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"
          ]
        }
      },
      /.../
    ]
  }

Também é possível usar locationRestriction para restringir as pesquisas a uma janela de visualização retangular. O exemplo a seguir limita a solicitação ao centro de São 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

Os resultados estão contidos na matriz 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"
          ]
        }
      }
    ]
  }

Polarizar a pesquisa para uma área usando locationBias

Com locationBias, o local serve como uma tendência, o que significa que os resultados ao redor do local especificado podem ser retornados, incluindo resultados fora da área especificada. No exemplo a seguir, você envia uma solicitação para o 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

Os resultados agora contêm muito mais itens, incluindo resultados fora do raio 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"
        ]
      }
    },
    ...
  ]
}

Você também pode usar locationBias para priorizar pesquisas em uma janela de visualização retangular. O exemplo a seguir limita a solicitação ao centro de São 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

Embora os resultados da pesquisa dentro da janela de visualização retangular apareçam na resposta, alguns resultados estão fora dos limites definidos devido à polarização. Os resultados também estão contidos na matriz 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"
          ]
        }
      },
    /.../
    ]
  }

Usar includedPrimaryTypes

Use o parâmetro includedPrimaryTypes para especificar até cinco valores de tipo da Tabela A, da Tabela B, ou apenas (regions), ou apenas (cities). Um lugar precisa corresponder a um dos valores de tipo principal especificados para ser incluído na resposta.

No exemplo a seguir, você especifica uma string input de "Soccer" e usa o parâmetro includedPrimaryTypes para restringir os resultados a estabelecimentos do 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

Se você omitir o parâmetro includedPrimaryTypes, os resultados poderão incluir estabelecimentos de um tipo que você não quer, como "athletic_field".

Solicitar previsões de consulta

As previsões de consulta não são retornadas por padrão. Use o parâmetro de solicitação includeQueryPredictions para adicionar previsões de consulta à resposta. Exemplo:

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

A matriz suggestions agora contém previsões de lugar e de consulta, conforme mostrado acima em Sobre a resposta. Cada previsão de consulta inclui o campo text, que contém uma string de pesquisa de texto recomendada. É possível fazer uma solicitação de Text Search (novo) para mais informações sobre qualquer uma das previsões de consulta retornadas.

Usar origem

Neste exemplo, inclua origin na solicitação como coordenadas de latitude e longitude. Quando você inclui origin, o Autocomplete (novo) inclui o campo distanceMeters na resposta, que contém a distância em linha reta do origin até o destino. Este exemplo define a origem como o centro de São 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

A resposta agora inclui 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
      }
    }
  ]
}

Encontrar empresas que vão abrir no futuro

O exemplo a seguir mostra uma solicitação do Autocomplete (novo) para empresas que serão abertas no futuro em 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"

A resposta inclui detalhes sobre o local, mas não a data de abertura.

{
  "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"
        ]
      }
    }
  ]
}

Distância ausente na resposta

Em alguns casos, distanceMeters não aparece no corpo da resposta, mesmo quando origin está incluído na solicitação. Isso pode acontecer nos seguintes cenários:

• distanceMeters não está incluído nas previsões de route.
• distanceMeters não será incluído quando o valor for 0, que é o caso de previsões que estão a menos de 1 metro do local origin fornecido.

As bibliotecas de cliente que tentarem ler o campo distanceMeters de um objeto analisado vão retornar um campo com o valor 0. Para evitar enganar os usuários, não mostre uma distância de zero para eles.

Otimização do Autocomplete (novo)

Esta seção descreve as práticas recomendadas para você aproveitar ao máximo o serviço Autocomplete (New).

Aqui estão algumas diretrizes gerais:

• A maneira mais rápida de desenvolver uma interface do usuário funcional é usar o widget do Autocomplete (novo) da API Maps JavaScript, o widget do Autocomplete (novo) do SDK do Places para Android ou o widget do Autocomplete (novo) do SDK do Places para iOS.
• Entender os campos de dados essenciais do Autocomplete (New) desde o início.
• Os campos de direcionamento de local e restrição de local são opcionais, mas podem afetar bastante a performance do preenchimento automático.
• Use o tratamento de erros para garantir que o aplicativo faça uma degradação simples se a API retornar um erro.
• Verifique se o app continua funcionando quando não há seleção e que oferece às pessoas uma maneira de continuar.

Práticas recomendadas de otimização de custos

Otimização básica de custos

Para otimizar o custo do uso do serviço Autocomplete (novo), use máscaras de campo nos widgets Place Details (novo) e Autocomplete (novo) para retornar apenas os campos de dados do Autocomplete (novo) necessários.

Otimização avançada de custos

Faça a implementação programática do Autocomplete (New) para acessar os preços da SKU: Autocomplete Request e pedir resultados da API Geocoding sobre o lugar selecionado em vez do Place Details (New). O preço por solicitação combinado com a API Geocoding vai ser mais econômico que o preço por sessão se as duas condições a seguir forem atendidas:

• Se você só precisa da latitude e longitude ou do endereço do local selecionado pela pessoa, a API Geocoding fornece essas informações por menos do que uma chamada do Place Details (New).
• Se os usuários selecionarem uma previsão de preenchimento automático em média com quatro solicitações desse tipo (novo), o preço por solicitação poderá ser mais econômico que o custo por sessão.

A API Geocoding pode ser uma opção mais econômica que o Place Details (novo) para seu aplicativo, dependendo da performance do Autocomplete (novo). A eficiência do Autocomplete (New) de cada aplicativo varia de acordo com o que as pessoas inserem, onde o aplicativo está sendo usado e se as práticas recomendadas de otimização de performance foram seguidas.

Para encontrar o número médio de solicitações para a tabela, analise quantos caracteres um usuário digita em média antes de selecionar uma previsão do Autocomplete (novo) no seu aplicativo.

Autocomplete (novo) com base em sessões com Place Details (novo)

Use o Autocomplete (novo) com base em sessões com o Place Details (novo).
Como seu aplicativo requer o Place Details (New), como o nome do lugar, o status da empresa ou o horário de funcionamento, sua implementação do Autocomplete (New) precisa usar um token de sessão (de forma programática ou integrado aos widgets do JavaScript, Android ou iOS) por sessão, além das SKUs do Places aplicáveis, dependendo de quais campos de dados de lugar você solicitar.¹

Implementação do widget
O gerenciamento de sessões é integrado automaticamente aos widgets do JavaScript, Android ou iOS. Isso inclui as solicitações do Autocomplete (novo) e do Place Details (novo) na previsão selecionada. Especifique o parâmetro fields para garantir que você está pedindo apenas os campos de dados do Autocomplete (New) necessários.

Implementação programática
Use um token de sessão com suas solicitações do Autocomplete (New). Ao solicitar Place Details (New) sobre a previsão selecionada, inclua os seguintes parâmetros:

1. O ID de lugar da resposta do Autocomplete (novo)
2. O token de sessão usado na solicitação do Autocomplete (novo)
3. O parâmetro fields especificando os campos de dados do Autocomplete (New) necessários.

Preenchimento automático (novo) por solicitação com a API Geocoding

Implementar o Autocomplete (novo) de forma programática sem tokens de sessão e chamar a API Geocoding na previsão de lugar selecionada.
A API Geocoding oferece endereços e coordenadas de latitude/longitude. Fazer quatro solicitações do Autocomplete, além de uma chamada da API Geocoding sobre a previsão de lugar selecionada, é mais barato do que o custo por sessão do Autocomplete (novo).¹

Convém usar as práticas recomendadas de performance para ajudar as pessoas a conseguir a previsão que querem usando ainda menos caracteres.

Autocomplete (novo) com base em sessões para aplicativos que usam apenas endereços

Use o Autocomplete (novo) com base em sessões com o Place Details (novo).
Como o número médio de solicitações que você espera fazer antes que um usuário selecione uma previsão do Autocomplete (novo) excede o custo do preço por sessão, sua implementação do Autocomplete (novo) deve usar um token de sessão para as solicitações do Autocomplete (novo) e a solicitação associada do Place Details (novo) por sessão. ¹

Implementação do widget
O gerenciamento de sessões é integrado automaticamente aos widgets do JavaScript, Android ou iOS. Isso inclui as solicitações do Autocomplete (novo) e do Place Details (novo) na previsão selecionada. Especifique o parâmetro fields para garantir que você está pedindo apenas os campos necessários.

Implementação programática
Use um token de sessão com suas solicitações do Autocomplete (New). Ao solicitar Place Details (New) sobre a previsão selecionada, inclua os seguintes parâmetros:

1. O ID de lugar da resposta do Autocomplete (novo)
2. O token de sessão usado na solicitação do Autocomplete (novo)
3. O parâmetro fields que especifica campos como endereço e geometria

Considere atrasar as solicitações do Autocomplete (New)
É possível adiar uma solicitação do Autocomplete (New) até que a pessoa digite os três ou quatro primeiros caracteres, fazendo com que o aplicativo gere menos solicitações. Por exemplo, se você fizer solicitações do Autocomplete (New) para cada caractere depois que o usuário digitar o terceiro caractere, e ele digitar sete caracteres e selecionar uma previsão para a qual você faz uma solicitação da API Geocoding, o custo total será de 4 solicitações do Autocomplete (New) + Geocoding.¹

Se for possível usar o atraso de solicitações para deixar sua solicitação programática média abaixo de quatro, siga as orientações para ter uma performance eficiente no Autocomplete (New) com a API Geocoding. Atrasar solicitações pode ser percebido como latência pelo usuário, que talvez queira ver previsões a cada vez que pressionar uma nova tecla.

Convém usar as práticas recomendadas de performance para ajudar as pessoas a conseguir a previsão que querem usando ainda menos caracteres.

Práticas recomendadas de desempenho

As diretrizes a seguir descrevem como otimizar a performance do Autocomplete (New):

• Adicione restrições de país, direcionamento de local e preferência de idioma (para implementações programáticas) à implementação do Autocomplete (New). A preferência de idioma não é necessária com widgets porque eles usam o que está definido no navegador ou no dispositivo móvel do usuário.
• Se o Autocomplete (New) estiver acompanhado por um mapa, é possível direcionar o local por janela de visualização do mapa.
• Quando a pessoa não escolhe uma das previsões do Autocomplete (New), geralmente porque nenhuma delas é o endereço que ela quer, você pode reutilizar a entrada original para tentar receber resultados mais relevantes:
  • Se quiser que o usuário insira apenas informações de endereço, reutilize a entrada original dele em uma chamada para a API Geocoding.
  • Se quiser que o usuário insira consultas para um lugar específico por nome ou endereço, use uma solicitação do Place Details (New). Se os resultados forem esperados apenas em uma região específica, use o direcionamento de local.
  Outros cenários em que é melhor voltar para a API Geocoding são:
  • Usuários que inserem endereços de subpremissas, como endereços de unidades ou apartamentos específicos em um prédio. Por exemplo, o endereço tcheco "Stroupežnického 3191/17, Praha" gera uma previsão parcial no Autocomplete (novo).
  • Usuários que digitam endereços com prefixos de trechos de via, como "23-30 29th St, Queens", na cidade de Nova York, ou "47-380 Kamehameha Hwy, Kaneohe", na ilha de Kauai, no Havaí.

Polarização de local

Direcione os resultados para uma área específica transmitindo um parâmetro location e um parâmetro radius. Isso instrui o Autocomplete (New) a priorizar os resultados dentro da área definida. Os resultados fora da área definida ainda podem ser exibidos. Use o parâmetro includedRegionCodes para filtrar os resultados e mostrar apenas os lugares em um país específico.

Restrição de local

Restrinja os resultados a uma área especificada transmitindo um parâmetro locationRestriction.

Também é possível restringir os resultados à região definida por location e um parâmetro radius adicionando o parâmetro locationRestriction. Isso instrui o Autocomplete (New) a retornar apenas resultados dentro dessa região.

Confira!

O APIs Explorer permite que você faça solicitações de amostra para se familiarizar com a API e as opções dela.

1. Selecione o ícone da API api no lado direito da página.

2. Se quiser, edite os parâmetros da solicitação.

3. Selecione o botão Executar. Na caixa de diálogo, escolha a conta que você quer usar para fazer a solicitação.

4. No painel do APIs Explorer, selecione o ícone de tela cheia fullscreen para expandir a janela do APIs Explorer.