Pronto!

Para começar a desenvolver, acesse nossa documentação do desenvolvedor.

Ativar a API do Google Places para Android

Para começar, orientaremos você pelo Console de Desenvolvedores do Google para realizar algumas atividades:

  1. Criar ou selecionar um projeto
  2. Ativar a Google Places API for Android
  3. Criar chaves apropriadas
Continuar

Place Autocomplete

O serviço de preenchimento automático na Google Places API for Android retorna sugestões de local em resposta a consultas de pesquisa do usuário. Enquanto o usuário digita, o serviço de preenchimento automático retorna sugestões de locais, como estabelecimentos, endereços e pontos de interesse.

É possível adicionar o preenchimento automático no aplicativo das seguintes formas:

Adicionar um widget de preenchimento automático

O widget de preenchimento automático é uma caixa de diálogo de pesquisa com o recurso do preenchimento automático integrado. Conforme o usuário insere termos de pesquisa, o widget apresenta uma lista de locais previstos para escolha. Quando o usuário seleciona um deles, uma instância de Place é retornada, que, em seguida, o aplicativo pode usar para obter detalhes sobre o local selecionado.

Há duas opções para se adicionar o widget de preenchimento automático ao seu aplicativo:

Opção 1: incorporar um PlaceAutocompleteFragment ou um SupportPlaceAutocompleteFragment

Para adicionar um PlaceAutocompleteFragment ao aplicativo, faça o seguinte:

  1. Adicione um fragmento ao layout XML da atividade.
  2. Adicione um detector à atividade ou ao fragmento.

Adicionar PlaceAutocompleteFragment a uma atividade

Para adicionar PlaceAutocompleteFragment a uma atividade, adicione um novo fragmento chamado de com.google.android.gms.location.places.ui.PlaceAutocompleteFragment a um layout XML. Por exemplo:

<fragment
  android:id="@+id/place_autocomplete_fragment"
  android:layout_width="match_parent"
  android:layout_height="wrap_content"
  android:name="com.google.android.gms.location.places.ui.PlaceAutocompleteFragment"
  />

Observação: Por padrão, o fragmento não tem borda nem plano de fundo. Para criar um visual consistente, aninhe o fragmento em outro elemento de layout, como na CardView.

Adicionar um PlaceSelectionListener a uma atividade

O PlaceSelectionListener lida com o retorno de um local em resposta à seleção do usuário. O código a seguir mostra como criar uma referência ao fragmento e adicionar um detector ao PlaceAutocompleteFragment:

PlaceAutocompleteFragment autocompleteFragment = (PlaceAutocompleteFragment)
getFragmentManager().findFragmentById(R.id.place_autocomplete_fragment);

autocompleteFragment.setOnPlaceSelectedListener(new PlaceSelectionListener() {
    @Override
    public void onPlaceSelected(Place place) {
        // TODO: obter informações sobre o local selecionado.
        Log.i(TAG, "Place: " + place.getName());
    }

    @Override
    public void onError(Status status) {
        // TODO: Solucionar o erro.
        Log.i(TAG, "Ocorreu um erro: " + status);
    }
  });

Usar SupportPlaceAutocompleteFragment (plataformas antigas)

A Google Places API requer a API de nível 12 ou posterior para oferecer suporte a objetos PlaceAutocompleteFragment. Se você pretende oferecer suporte a aplicativos anteriores à API de nível 12, terá acesso à mesma funcionalidade usando a classe SupportPlaceAutocompleteFragment. Você também deve incluir a Biblioteca de suporte. do Android v4. Para oferecer suporte a versões do Android anteriores à API de nível 12, faça o seguinte:

  • Estenda FragmentActivity ou AppCompatActivity na sua atividade principal.
  • Use SupportPlaceAutocompleteFragment em vez de PlaceAutocompleteFragment.
  • Use getSupportFragmentManager() em vez de getFragmentManager().

Opção 2: use um intent para inicializar a atividade de preenchimento automático

Se você quiser que o aplicativo use um fluxo de navegação diferente (por exemplo, para ativar a experiência de preenchimento automático por um ícone em vez de por um campo de pesquisa), ele deve inicializar o preenchimento automático usando um intent.

Observação: Essas etapas não são necessárias se você estiver incorporando um fragmento.

Para inicializar o widget de preenchimento automático usando um intent, faça o seguinte:

  1. Use PlaceAutocomplete.IntentBuilder para criar um intent, passando o modo PlaceAutocomplete desejado. O intent deve chamar startActivityForResult, passando um código de solicitação que identifica o intent.
  2. Neutralize o retorno de chamada de onActivityResult para receber o local selecionado.

Crie um intent de preenchimento automático

O exemplo abaixo mostra como usar PlaceAutocomplete.IntentBuilder para criar um intent para inicializar o widget de preenchimento automático como um intent:

int PLACE_AUTOCOMPLETE_REQUEST_CODE = 1;
...
try {
    Intent intent =
            new PlaceAutocomplete.IntentBuilder(PlaceAutocomplete.MODE_FULLSCREEN)
                    .build(this);
    startActivityForResult(intent, PLACE_AUTOCOMPLETE_REQUEST_CODE);
} catch (GooglePlayServicesRepairableException e) {
    // TODO: Solucionar o erro.
} catch (GooglePlayServicesNotAvailableException e) {
    // TODO: Solucionar o erro.
}

Ao usar um intent para inicializar o widget de preenchimento automático, você pode escolher entre os modos de exibição por sobreposição ou em tela cheia. As capturas de tela a seguir mostram cada modo de exibição:

When displayed in overlay mode, the autocomplete widget appears superimposed over the calling UI.
Figura 1: widget de preenchimento automático em modo de sobreposição (MODE_OVERLAY)
When displayed in fullscreen mode, the autocomplete widget fills the entire screen.
Figura 2: widget de preenchimento automático em modo tela cheia (MODE_FULLSCREEN)

Neutralizar o retorno de chamada de onActivityResult

Para receber notificação quando um usuário selecionar um local, o seu aplicativo deve neutralizar onActivityResult() da atividade, verificando se o código de solicitação passado para o intent está presente, como no exemplo abaixo.

@Override
protected void onActivityResult(int requestCode, int resultCode, Intent data) {
    if (requestCode == PLACE_AUTOCOMPLETE_REQUEST_CODE) {
        if (resultCode == RESULT_OK) {
            Place place = PlaceAutocomplete.getPlace(this, data);
            Log.i(TAG, "Place: " + place.getName());
        } else if (resultCode == PlaceAutocomplete.RESULT_ERROR) {
            Status status = PlaceAutocomplete.getStatus(this, data);
            // TODO: Solucionar o erro.
            Log.i(TAG, status.getStatusMessage());

        } else if (resultCode == RESULT_CANCELED) {
            // The user canceled the operation.
        }
    }
}

Restringir resultados do preenchimento automático

Você pode configurar o widget de preenchimento automático para dar preferência a resultados de uma região geográfica específica e/ou filtrar os resultados a um ou mais tipos de local.

Dar preferência a resultados de uma região específica

Para dar preferência a resultados de preenchimento automático de uma região geográfica específica:

  • Chame setBoundsBias() da instância de PlaceAutocompleteFragment do seu aplicativo ou da instância de IntentBuilder, passando um LatLngBounds. O exemplo de código a seguir mostra como chamar setBoundsBias() em uma instância de fragmento para dar preferência a sugestões de uma região de Sydney, Austrália, no preenchimento automático.
autocompleteFragment.setBoundsBias(new LatLngBounds(
        new LatLng(-33.880490, 151.184363),
        new LatLng(-33.858754, 151.229596)));

Filtrar resultados por tipo de local

Para restringir os resultados a um tipo de local específico no preenchimento automático, chame AutocompleteFilter.Builder para criar um novo AutocompleteFilter, chamando setTypeFilter() para ativar o filtro a usar. Em seguida, passe o filtro a um fragmento ou intent.

O exemplo de código a seguir mostra como configurar um AutocompleteFilter em um PlaceAutocompleteFragment para configurar um filtro para retornar somente resultados com endereço preciso.

AutocompleteFilter typeFilter = new AutocompleteFilter.Builder()
        .setTypeFilter(AutocompleteFilter.TYPE_FILTER_ADDRESS)
        .build();

autocompleteFragment.setFilter(typeFilter);

O exemplo de código a seguir mostra como configurar um AutocompleteFilter em um intent para configurar um filtro para só retornar resultados com endereço preciso.

AutocompleteFilter typeFilter = new AutocompleteFilter.Builder()
        .setTypeFilter(AutocompleteFilter.TYPE_FILTER_ADDRESS)
        .build();

Intent intent =
        new PlaceAutocomplete.IntentBuilder(PlaceAutocomplete.MODE_FULLSCREEN)
                .setFilter(typeFilter)
                .build(this);

Se quiser saber mais sobre tipos de local, acesse o guia de tipos de local e AutocompleteFilter.Builder.

Obter sugestões de local programaticamente

É possível criar uma IU de pesquisa personalizada como alternativa à IU fornecida pelo widget de preenchimento automático. Para tanto, o aplicativo precisa receber sugestões de local programaticamente. O aplicativo pode obter uma lista de nomes e/ou endereços de locais sugeridos pelo serviço de preenchimento automático ao chamar GeoDataApi.getAutocompletePredictions() passando os seguintes parâmetros:

  • Obrigatório: uma string query contendo o texto digitado pelo usuário.
  • Obrigatório: um objeto LatLngBounds polarizando os resultados a uma área específica definida por limites de latitude e longitude.
  • Opcional: um AutocompleteFilter contendo um conjunto de tipos de local, que pode ser usado para restringir os resultados a um ou mais tipos de local. Os tipos de local a seguir são compatíveis:

    • TYPE_FILTER_NONE – um filtro vazio. Todos os resultados são retornados.
    • TYPE_FILTER_GEOCODE – retorna apenas resultados de geocodificação, excluindo estabelecimentos. Use esta solicitação para obter resultados não ambíguos em casos em que o local especificado seja indeterminado.
    • TYPE_FILTER_ADDRESS – retorna somente resultados de preenchimento automático com endereço preciso. Use este tipo quando sabe que o usuário está buscando um endereço completo.
    • TYPE_FILTER_ESTABLISHMENT – retorna somente estabelecimentos.
    • TYPE_FILTER_REGIONS – retorna apenas locais que são de um dos seguintes tipos:

      • locality
      • sublocality
      • postal_code
      • country
      • administrative_area_level_1
      • administrative_area_level_2
    • TYPE_FILTER_CITIES – retorna apenas resultados que correspondam a locality ou administrative_area_level_3.

Para saber mais sobre tipos de local, consulte o guia sobre tipos de local e AutocompleteFilter.Builder.

O exemplo abaixo mostra uma chamada simplificada para [GeoDataApi.getAutocompletePredictions()](/android/reference/com/google/android/gms/location/places/GeoDataApi.html#getAutocompletePredictions(com.google.android.gms.common.api.GoogleApiClient, java.lang.String, com.google.android.gms.maps.model.LatLngBounds, com.google.android.gms.location.places.AutocompleteFilter)GeoDataApi.getAutocompletePredictions(). Para ver um exemplo completo, consulte os aplicativos de exemplo.

PendingResult<AutocompletePredictionBuffer> result =
    Places.GeoDataApi.getAutocompletePredictions(mGoogleApiClient, query,
        bounds, autocompleteFilter);

A API retorna um AutocompletePredictionBuffer em um PendingResult. O AutocompletePredictionBuffer contém uma lista de objetos AutocompletePrediction que representam locais sugeridos. Se não houver local conhecido que corresponda à consulta e respeite os critérios de filtro, o buffer pode ficar vazio.

Observação: Para evitar vazamento de memória, você deve liberar o objeto AutocompletePredictionBuffer quando o aplicativo não precisar mais dele. Leia mais sobre como manipular buffers.

É possível chamar os seguintes métodos para obter detalhes de cada local sugerido:

  • getFullText(CharacterStyle matchStyle) retorna todo o texto de uma descrição de local. Essa é uma combinação dos textos principal e secundário. Exemplo: “Torre Eiffel, Avenue Anatole France, Paris, França". Além disso, é possível este método destacar as seções da descrição que correspondem à pesquisa com o estilo que você quiser usando CharacterStyle. O parâmetro CharacterStyle é opcional. Defina-o como nulo se não quiser destacar nada.
  • getPrimaryText(CharacterStyle matchStyle) retorna o texto principal de descrição do local. Normalmente é o nome do local. Exemplos: “Torre Eiffel", e "123 Pitt Street".
  • getSecondaryText(CharacterStyle matchStyle) retorna o texto complementar de uma descrição de local. Isso é útil, por exemplo, se usado como uma segunda linha ao mostrar sugestões de preenchimento automático. Exemplos: "Avenue Anatole France, Paris, França" e "Sydney, Nova Gales do Sul".
  • getPlaceId() retorna o ID de local do local sugerido. Um ID de local é um identificador textual que distingue um local de outros, que pode ser usado para recuperar o objeto Place depois. Para saber mais sobre IDs de local na Google Places API for Android, acesse IDs e detalhes de local. Para conhecer o básico dos IDs de local, leia a Visão geral dos IDs de local.
  • getPlaceTypes() retorna a lista de tipos de local associada a este local.

Limites de uso

Exibir atribuições no aplicativo

  • Se o aplicativo usa o serviço de preenchimento automático programaticamente a IU também precisa exibir uma atribuição “Tecnologia do Google” ou aparecer em um mapa com o logotipo da Google.
  • Se o aplicativo usa o widget de preenchimento automático, não é preciso fazer mais nada (a atribuição exigida é exibida por padrão).
  • Se você recuperar e exibir mais informações do local depois de obter um local por ID, será necessário exibir atribuições de terceiros também.

Para conhecer mais detalhes, leia a documentação sobre atribuições.

Solução de problemas

Embora possam ocorrer diversos erros, geralmente a maioria deles que pode acontecer no aplicativo é causada por erros de configuração (por exemplo, uso da chave de API incorreta ou configuração incorreta dela) ou de cota (cota excedida). Consulte Limites de uso para saber mais sobre cotas.

Os erros que podem ocorrer pelo uso dos widgets de preenchimento automático são retornados no retorno de chamada de onActivityResult(). Chame PlaceAutocomplete.getStatus() para receber a mensagem de status do resultado.

Enviar comentários sobre…

location_on
Google Places API for Android