Pronto!

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

Ative a Google Maps Android API

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

  1. Criar ou selecionar um projeto
  2. Ative a Google Maps Android API
  3. Criar chaves apropriadas
Continuar

Marcadores

Os marcadores indicam localizações únicas no mapa. Você pode personalizar os marcadores alterando a cor padrão ou substituindo o ícone do marcador com uma imagem personalizada. As janelas de informações podem fornecer contexto adicional a um marcador.

Exemplos de código

O repositório ApiDemos no GitHub inclui um exemplo que demonstra vários recursos de marcador:

Introdução

Os marcadores identificam localizações no mapa. O marcador padrão usa um ícone padrão com a mesma aparência do marcador do Google Maps. É possível alterar a cor, a imagem ou o ponto de controle do ícone por meio da API. Os marcadores são objetos do tipo Marker, adicionados ao mapa com o método GoogleMap.addMarker(markerOptions).

Os marcadores foram projetados para serem interativos. Por padrão, recebem eventos de click e são frequentemente usados com ouvintes de eventos para exibir janelas de informações. A definição da propriedade draggable do marcador como true permite que o usuário altere a posição do marcador. Use um pressionamento longo para ativar a capacidade de mover o marcador.

Por padrão, quando um usuário toca um marcador, a barra de ferramentas do mapa é exibida no canto inferior direito do mapa, proporcionando ao usuário um rápido acesso ao aplicativo móvel do Google Maps. Você pode desativar a barra de ferramentas. Para obter mais informações, consulte o guia dos controles.

Primeiros passos com marcadores

Este episódio de Maps Live cobre os fundamentos da adição de marcadores ao mapa usando a Google Maps Android API.

Adicionar um marcador

O exemplo a seguir demonstra como adicionar um marcador a um mapa. O marcador é criado nas coordenadas 10,10 e, quando clicado, exibe a string "Hello world" em uma janela de informações.

@Override
public void onMapReady(GoogleMap map) {
    map.addMarker(new MarkerOptions()
        .position(new LatLng(10, 10))
        .title("Hello world"));
}

Exibir informações adicionais sobre um marcador

Um requisito comum é exibir informações adicionais sobre um lugar ou local quando o usuário toca em um marcador no mapa. Consulte o guia de janelas de informações.

Associar dados a um marcador

É possível armazenar um objeto de dados arbitrários com um marcador usando Marker.setTag() e recuperar o objeto de dados usando Marker.getTag(), conforme mostrado neste código de exemplo.

/**
 * A demo class that stores and retrieves data objects with each marker.
 */
public class MarkerDemoActivity extends FragmentActivity implements
        OnMarkerClickListener,
        OnMapReadyCallback {

    private static final LatLng PERTH = new LatLng(-31.952854, 115.857342);
    private static final LatLng SYDNEY = new LatLng(-33.87365, 151.20689);
    private static final LatLng BRISBANE = new LatLng(-27.47093, 153.0235);

    private Marker mPerth;
    private Marker mSydney;
    private Marker mBrisbane;

    private GoogleMap mMap;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.marker_demo);

        SupportMapFragment mapFragment =
                (SupportMapFragment) getSupportFragmentManager().findFragmentById(R.id.map);
        mapFragment.getMapAsync(this);
    }

    /** Chamado quando o mapa está pronto. */
    @Override
    public void onMapReady(GoogleMap map) {
        mMap = map;

        // Add some markers to the map, and add a data object to each marker.
        mPerth = mMap.addMarker(new MarkerOptions()
                .position(PERTH)
                .title("Perth");
        mPerth.setTag(0);

        mSydney = mMap.addMarker(new MarkerOptions()
                .position(SYDNEY)
                .title("Sydney");
        mSydney.setTag(0);

        mBrisbane = mMap.addMarker(new MarkerOptions()
                .position(BRISBANE)
                .title("Brisbane");
        mBrisbane.setTag(0);

        // Set a listener for marker click.
        mMap.setOnMarkerClickListener(this);
    }

    /** Chamado quando o usuário clica em um marcador. */
    @Override
    public boolean onMarkerClick(final Marker marker) {

        // Retrieve the data from the marker.
        Integer clickCount = (Integer) marker.getTag();

        // Check if a click count was set, then display the click count.
        if (clickCount != null) {
            clickCount = clickCount + 1;
            marker.setTag(clickCount);
            Toast.makeText(this,
                           marker.getTitle() +
                           " has been clicked " + clickCount + " times.",
                           Toast.LENGTH_SHORT).show();
        }

        // Return false to indicate that we have not consumed the event and that we wish
        // for the default behavior to occur (which is for the camera to move such that the
        // marker is centered and for the marker's info window to open, if it has one).
        return false;
    }
}

Eis alguns exemplos de cenários quando é útil armazenar e recuperar dados com marcadores:

  • O seu aplicativo pode oferecer vários tipos de marcadores e você quer tratá-los de forma diferente quando o usuário clica neles. Para fazer isto, é possível armazenar uma String com o marcador indicando o tipo.
  • Você pode estar fazendo interface com um sistema que tem identificadores de registro únicos, onde os marcadores representam registros específicos neste sistema.
  • Os dados do marcador podem indicar uma prioridade a ser usada ao decidir o índice Z de um marcador.

Tornar um marcador arrastável

É possível reposicionar um marcador após ser adicionado ao mapa, desde que a propriedade draggable seja definida como true. Pressione longamente o marcador para ativar o recurso de arrastar. Quando você tirar o dedo da tela, o marcador permanecerá nessa posição.

Por padrão, os marcadores não são arrastáveis. É preciso definir explicitamente o marcador como arrastável com MarkerOptions.draggable(boolean) antes de adicioná-lo ao mapa ou com Marker.setDraggable(boolean) após a adição ao mapa. Você pode detectar eventos de arrastar no marcador da forma descrita em Eventos de arrasto de marcador.

O fragmento a seguir adiciona um marcador arrastável em Perth, Austrália.

static final LatLng PERTH = new LatLng(-31.90, 115.86);
Marker perth = mMap.addMarker(new MarkerOptions()
                          .position(PERTH)
                          .draggable(true));

Personalizar um marcador

Esse vídeo mostra formas de usar marcadores para visualizar localizações em um mapa.

Os marcadores podem definir uma imagem personalizada para exibição em vez do ícone padrão. A definição de um ícone envolve a configuração de várias propriedades que afetam o comportamento visual do marcador.

Os marcadores permitem a personalização por meio destas propriedades:

Position (obrigatória)
O valor de LatLng para a posição do marcador no mapa. Essa é a única propriedade obrigatória para um objeto Marker.
Anchor
O ponto da imagem que será colocado na posição LatLng do marcador. Por padrão, é o meio da parte inferior da imagem.
Alpha
Define a opacidade do marcador. O valor padrão é 1.0.
Title
Uma string exibida na janela de informações quando o usuário toca o marcador.
Snippet
Texto adicional exibido abaixo do título.
Icon
Um bitmap exibido em vez da imagem padrão do marcador.
Draggable
Defina como true para permitir que o usuário mova o marcador. O valor padrão é false.
Visível
Defina como false para que o marcador fique invisível. O valor padrão é true.
Flat or Billboard orientation
Por padrão, os marcadores são orientados em relação à tela e não giram nem se inclinam com a câmera. Os marcadores planos são orientados em relação à superfície do planeta, e giram e se inclinam com a câmera. O tamanho dos tipos de marcador não se altera juntamente com o zoom. Use GroundOverlays se quiser esse efeito.
Rotação
A orientação do marcador, especificada em graus no sentido horário. A posição padrão é alterada se o marcador é plano. A posição padrão para um marcador plano é alinhada ao norte. Quando o marcador não é plano, a posição padrão aponta para cima e a rotação faz com que o marcador esteja sempre voltado à câmera.

O fragmento abaixo cria um único marcador com o ícone padrão.

static final LatLng MELBOURNE = new LatLng(-37.813, 144.962);
Marker melbourne = mMap.addMarker(new MarkerOptions()
                          .position(MELBOURNE));

Personalizar a cor do marcador

É possível personalizar a cor da imagem padrão do marcador passando um objeto BitmapDescriptor para o método icon(). Você pode usar um conjunto de cores predefinidas no objeto BitmapDescriptorFactory ou definir uma cor de marcador personalizada com o método BitmapDescriptorFactory.defaultMarker(float hue). A tonalidade é um valor entre 0 e 360, representando pontos em uma paleta de cores.

static final LatLng MELBOURNE = new LatLng(-37.813, 144.962);
Marker melbourne = mMap.addMarker(new MarkerOptions()
                          .position(MELBOURNE)
                          .icon(BitmapDescriptorFactory.defaultMarker(BitmapDescriptorFactory.HUE_AZURE)));

Personalizar a opacidade do marcador

Você pode controlar a opacidade de um marcador com o método MarkerOptions.alpha(). O alfa deve ser especificado como um número flutuante entre 0.0 e 1.0, onde 0 significa totalmente transparente e 1, totalmente opaco.

static final LatLng MELBOURNE = new LatLng(-37.813, 144.962);
Marker melbourne = mMap.addMarker(new MarkerOptions()
                          .position(MELBOURNE)
                          .alpha(0.7f));

Personalizar a imagem do marcador

Você pode substituir a imagem padrão do marcador por uma imagem personalizada, denominada frequentemente de ícone. Os ícones personalizados são sempre configurados como BitmapDescriptor e definidos usando um dos métodos na classe BitmapDescriptorFactory.

fromAsset(String assetName)
Cria um marcador personalizado usando o nome de uma imagem Bitmap no diretório de ativos.
fromBitmap(Bitmap image)
Cria um marcador personalizado usando uma imagem em bitmap.
fromFile(String fileName)
Cria um ícone personalizado usando o nome de um arquivo de imagem Bitmap localizado no armazenamento interno.
fromPath(String absolutePath)
Cria um marcador personalizado de um caminho de arquivo absoluto de uma imagem Bitmap.
fromResource(int resourceId)
Cria um marcador personalizado usando o ID de recurso de uma imagem Bitmap.

O fragmento abaixo cria um marcador com um ícone personalizado.

  private static final LatLng MELBOURNE = new LatLng(-37.813, 144.962);
  private Marker melbourne = mMap.addMarker(new MarkerOptions()
                            .position(MELBOURNE)
                            .title("Melbourne")
                            .snippet("Population: 4,137,400")
                            .icon(BitmapDescriptorFactory.fromResource(R.drawable.arrow)));

Comprimir um marcador

Normalmente, os ícones de marcador são desenhados orientados em relação à tela. A rotação, a inclinação ou o zoom do mapa não altera a orientação do marcador. É possível definir a orientação de um marcador como plana em relação ao planeta. Os marcadores orientados dessa forma giram quando o mapa gira e alteram a perspectiva quando o mapa é inclinado. Os marcadores planos retêm o tamanho quando o zoom do mapa é aumentado ou diminuído.

Para alterar a orientação do marcador, defina a propriedade flat do marcador como true.

static final LatLng PERTH = new LatLng(-31.90, 115.86);
Marker perth = mMap.addMarker(new MarkerOptions()
                          .position(PERTH)
                          .flat(true));

Girar um marcador

Você pode girar um marcador em volta de seu ponto de controle com o método Marker.setRotation(). A rotação é medida em graus na direção horária em relação à posição padrão. Quando o marcador está plano no mapa, a posição padrão é norte. Quando o marcador não é plano, a posição padrão aponta para cima e a rotação faz com que o marcador esteja sempre voltado à câmera.

O exemplo a seguir gira o marcador 90°. A definição do ponto de controle como 0.5,0.5 faz com que o marcador seja girado em torno do centro em vez da base.

static final LatLng PERTH = new LatLng(-31.90, 115.86);
Marker perth = mMap.addMarker(new MarkerOptions()
                          .position(PERTH)
                          .anchor(0.5,0.5)
                          .rotation(90.0));

Índice Z do marcador

O índice Z especifica a ordem de empilhamento deste marcador, relativo a outros marcadores no mapa. Um marcador com índice Z alto é arrastado para o topo dos marcadores com índices Z menores. O valor padrão do índice Z é 0.

Defina o índice Z no objeto de opções do marcador chamando MarkerOptions.zIndex(), conforme mostrado no snippet de código a seguir:

@Override
public void onMapReady(GoogleMap map) {
    map.addMarker(new MarkerOptions()
        .position(new LatLng(10, 10))
        .title("Marker z1")
        .zIndex(1.0f));
}

É possível acessar o índice Z do marcador chamando Marker.getZIndex() e é possível alterá-lo chamando Marker.setZIndex().

Os marcadores sempre são delineados acima de camadas de bloco e outras sobreposições que não são marcadores (sobreposição de solo, polilinhas, polígonos e outras formas) independentemente do índice Z das outras sobreposições. Os marcadores são considerados em um grupo de índice Z separado em comparação a outras sobreposições.

Leia sobre o efeito do índice Z nos eventos de clique abaixo.

Lidar com eventos de marcador

A Maps API permite escutar e responder a eventos de marcador. Para escutar esses eventos, você deve definir o ouvinte correspondente no objeto GoogleMap ao qual os marcadores pertencem. Quando o evento ocorre em um dos marcadores no mapa, o retorno de chamada do ouvinte será invocado com o objeto Marker correspondente passado como parâmetro. Para comparar esse objeto Marker com a sua própria referência para um objeto Marker, você precisa usar equals() e não ==.

É possível escutar os seguintes eventos:

Eventos de clique de marcador

Você pode usar um OnMarkerClickListener para escutar eventos de clique no marcador. Para definir esse ouvinte no mapa, chame GoogleMap.setOnMarkerClickListener(OnMarkerClickListener). Quando um usuário clica em um marcador, onMarkerClick(Marker) é chamado e o marcador é passado como argumento. Esse método retorna um booleano que indica se você consumiu um evento (ou seja, quer suprimir o comportamento padrão). Se o método retornar false, o comportamento padrão ocorrerá em adição ao comportamento personalizado. O comportamento padrão para um evento de clique de marcador é mostrar a janela de informações (se disponível) e mover a câmera para que o marcador fique centralizado no mapa.

Efeito do índice Z em eventos de clique:

  • Quando um usuário clica em um conjunto de marcadores, o evento de clique é acionado para o marcador com o maior índice Z.
  • Só é possível acionar um evento por clique. Em outras palavras, o clique não é repassado aos marcadores ou outras sobreposições com valores de índice Z inferiores.
  • Clicar em um conjunto de marcadores faz com que os cliques subsequentes passem pelo conjunto, selecionado cada um por vez. A ordem do ciclo prioriza o índice Z e, em seguida, a proximidade ao ponto do clique.
  • Se o usuário clica fora da proximidade do conjunto, a API recalcula o conjunto e redefine o estado do ciclo de clique para que comece do início.
  • O evento de clique passa pelos conjuntos de marcadores para outras formas e sobreposições antes de reiniciar o ciclo.
  • Considera-se que os marcadores estão em um grupo de índice Z separado de outras sobreposições ou formas (polilinhas, polígonos, círculos e/ou sobreposições de solo), independentemente do índice Z de outras sobreposições. Se vários marcadores, sobreposições ou formas forem sobrepostas entre si, o evento de clique percorre o conjunto de marcadores primeiro e depois é acionado para outras sobreposições ou figuras clicáveis com base nos valores de índice Z.

Eventos de arrastar marcador

Você pode usar um OnMarkerDragListener para escutar eventos de arrastar em um marcador. Para definir esse ouvinte no mapa, chame GoogleMap.setOnMarkerDragListener. Para que um usuário arraste um marcador, é preciso pressionar longamente o marcador. Quando o usuário tirar o dedo da tela, o marcador permanecerá nessa posição. Quando um marcador é arrastado, onMarkerDragStart(Marker) é chamado inicialmente. Enquanto um marcador é arrastado, onMarkerDrag(Marker) é chamado constantemente. Quando o arrastar termina, onMarkerDragEnd(Marker) é chamado. Você pode obter a posição do marcador a qualquer momento chamando Marker.getPosition().

Observação: por padrão, um marcador não é arrastável. Um marcador precisa ser definido explicitamente como arrastável antes que possa ser arrastado por um usuário. Isso pode ser feito com MarkerOptions.draggable(boolean) antes de adicionar o marcador ao mapa ou Marker.setDraggable(boolean) depois de adicioná-lo ao mapa.

Enviar comentários sobre…

Google Maps Android API
Google Maps Android API
Precisa de ajuda? Acesse nossa página de suporte.