Preenchimento automático (novo)

Introdução

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

O preenchimento automático (novo) pode corresponder a palavras completas e substrings da entrada, resolvendo nomes de lugares, endereços e Plus Codes. À medida que a pessoa digita, os aplicativos enviam consultas e sugerem previsões de local e de consulta instantaneamente.

A resposta do preenchimento automático (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 lugares 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 (New) usando como entrada uma string que contém uma entrada parcial do usuário, "pizza siciliana", 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 de pesquisa e à área de pesquisa, como o restaurante "Sicilian Pizza Kitchen", além de detalhes sobre o lugar.

As previsões de lugar retornadas são projetadas para serem apresentadas ao usuário e ajudá-lo a selecionar o lugar desejado. Você pode fazer uma solicitação de 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 de pesquisa e à área de pesquisa, como "Sicilian Pizza & Pasta". Cada previsão de consulta na resposta inclui o campo text com uma string de pesquisa de texto recomendada. Use essa string como entrada para a Pesquisa de texto (novo) e faça uma pesquisa mais detalhada.

Com o APIs Explorer, você pode fazer solicitações em tempo real para se familiarizar com a API e as opções dela:

Solicitações de Autocomplete (novo)

Uma solicitação de 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 preenchimento automático (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 do lugar e a descrição do texto.
• Um campo queryPrediction contém informações detalhadas sobre uma única previsão de consulta.

O objeto JSON completo tem este 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 (New) 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 da 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: *

• 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, independente do valor do tipo principal associado ao lugar. Para restringir os resultados a um determinado tipo principal ou tipos principais, transmita 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, em vez disso, um de (regions) ou (cities). Os filtros de coleção do tipo (regions) são para áreas ou divisões, como bairros e códigos postais. A coleção de tipos (cities) filtra lugares que o Google identifica como uma cidade.

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

  • Mais de cinco tipos foram especificados.
  • Qualquer tipo é especificado além de (cities) ou (regions).
  • Todos os 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 true, a resposta vai incluir previsões de lugar e de consulta. O valor padrão é false, ou seja, a resposta inclui apenas previsões de lugares.

• includedRegionCodes

  Inclui apenas resultados da lista de regiões especificadas, apresentadas como uma matriz de até 15 valores de dois caracteres 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 do caractere Unicode com base 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 de preferência em que os resultados serão retornados. 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 códigos de idioma IETF BCP-47 para especificar o idioma de preferência.
  • Se languageCode não for fornecido, a API 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 preferido 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.
  • A API tenta fornecer um endereço legível para o usuário e a população local, refletindo a entrada do usuário. 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 endereços são formatados no idioma local, em um script legível pelo usuário, quando possível, somente depois que os termos correspondentes são escolhidos para corresponder aos termos no parâmetro input.
    • Todos os outros endereços são retornados no idioma preferido, 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 usará a correspondência mais próxima.

• locationBias ou locationRestriction

  Você pode especificar locationBias ou locationRestriction, mas não ambos, para definir a área de pesquisa. Pense em locationRestriction como a região em que os resultados precisam estar e locationBias como a 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 resultados ao redor 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 por um ponto central e um raio em metros. O raio precisa estar entre 0,0 e 50.000,0, incluindo esses dois valores. O valor padrão é 0,0. Para locationRestriction, defina 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-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 de longitude entre -180 e 180 graus:

    • Se low = high, a janela de visualização consistirá 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 vai incluir todas as longitudes.
    • Se low.longitude = 180 graus e high.longitude = -180 graus, o intervalo de longitude fica vazio.

    Os campos 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 envolve 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 de onde 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 regional 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 de 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 tendenciosas com base nos códigos regionais. 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.

• sessionToken

  Os tokens de sessão são strings geradas pelo usuário que rastreiam 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 de preenchimento automático (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, você usa locationRestriction para limitar a solicitação a um círculo de 5.000 metros de raio centrado em São 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"
          ]
        }
      },
      /.../
    ]
  }

Você também pode 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 um direcionamento, 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ê direciona a solicitação para o centro de São 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"
        ]
      }
    },
    ...
  ]
}

Também é possível usar locationBias para direcionar 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": "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 (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 consultas

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 Pesquisa de texto (nova) 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 preenchimento automático (novo) inclui o campo distanceMeters na resposta, que contém a distância em linha reta de 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
      }
    }
  ]
}

Distância ausente na resposta

Em alguns casos, distanceMeters fica faltando 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 é incluído quando o valor é 0, o que acontece com previsões que estão a menos de um 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 confundir os usuários, não mostre uma distância zero.

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 Preenchimento automático (novo) da API Maps JavaScript, o widget Preenchimento automático (novo) do SDK do Places para Android ou o widget Preenchimento automático (novo) do SDK do Places para iOS.
• Entender os campos de dados essenciais do preenchimento automático (novo) 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 (New), use máscaras de campo nos widgets Place Details (New) e Autocomplete (New) para retornar apenas os campos de dados do Autocomplete (New) necessários.

Otimização avançada de custos

Faça a implementação programática do Autocomplete (New) para acessar SKU: preços de solicitação do Autocomplete e peça 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/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, o preço por solicitação poderá ser mais econômico que o custo por sessão.

Seu aplicativo requer outras informações além do endereço e da latitude/longitude da previsão selecionada?

Práticas recomendadas de desempenho

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

• 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 preenchimento automático (novo) 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 (novo), 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 de detalhes do lugar (novo). 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 subunidades, 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 preenchimento automático (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í.

Tendência de local

Influencie os resultados para uma área especificada transmitindo um parâmetro location e um parâmetro radius. Isso instrui o preenchimento automático (novo) a preferir mostrar resultados dentro da área definida. Os resultados fora da área definida ainda podem ser exibidos. Use o parâmetro components 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.

Você também pode restringir os resultados à região definida por location e um parâmetro radius, adicionando o parâmetro locationRestriction. Isso instrui o preenchimento automático (novo) a retornar apenas resultados nessa região.

Confira!

Com o APIs Explorer, você pode fazer 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.