Pronto!

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

Ativar a Google Maps JavaScript API

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

  1. Criar ou selecionar um projeto
  2. Ativar a Google Maps JavaScript API e serviços relacionados
  3. Criar chaves apropriadas
Continuar

Marcadores

Introdução

Um marcador identifica uma localização no mapa. Por padrão, um marcador usa uma imagem padrão. Os marcadores podem exibir imagens personalizadas. Nesse caso, são normalmente denominados "ícones". Os marcadores e os ícones são objetos do tipo Marker. Defina um ícone personalizado no construtor do marcador ou chamando setIcon() no marcador. Veja mais sobre a personalização da imagem de marcador abaixo.

Falando genericamente, os marcadores são um tipo de sobreposição. Para obter informações sobre outros tipos de sobreposição, consulte Desenho no mapa.

Os marcadores foram projetados para serem interativos. Por exemplo, eles recebem por padrão eventos de 'click' que permitem definir um ouvinte de eventos para exibir uma janela de informações com informações personalizadas. Permita que usuários movam um marcador no mapa definindo a propriedade draggable do marcador como true. Para obter mais informações sobre marcadores arrastáveis, consulte abaixo.

Adicionar um marcador

O construtor google.maps.Marker aceita um único literal de objeto Marker options, especificando as propriedades iniciais do marcador.

Os campos a seguir são particularmente importantes e são normalmente definidos na construção de um marcador:

  • position (obrigatório) especifica um LatLng que identifica a localização inicial do marcador. Uma forma de recuperar um LatLng é usando o serviço de Geocodificação.
  • map (opcional ) especifica o Map onde o marcador é posicionado. Se você não especifica o mapa na construção do marcador, o marcador é criado, mas não anexado (ou exibido) no mapa. Adicione o marcador posteriormente chamando o método setMap() do marcador.

O exemplo a seguir adiciona um marcador simples a um mapa em Uluru, no centro da Austrália:

function initMap() {
  var myLatLng = {lat: -25.363, lng: 131.044};

  var map = new google.maps.Map(document.getElementById('map'), {
    zoom: 4,
    center: myLatLng
  });

  var marker = new google.maps.Marker({
    position: myLatLng,
    map: map,
    title: 'Hello World!'
  });
}
<div id="map"></div>
/* Always set the map height explicitly to define the size of the div
 * element that contains the map. */
#map {
  height: 100%;
}
/* Optional: Makes the sample page fill the window. */
html, body {
  height: 100%;
  margin: 0;
  padding: 0;
}
 <!-- Replace the value of the key parameter with your own API key. -->
<script async defer
src="https://maps.googleapis.com/maps/api/js?key=AIzaSyCkUOdZ5y7hMm0yrcCQoCvLwzdM6M8s5qk&callback=initMap">
</script>
function initMap() {
  var myLatLng = {lat: -25.363, lng: 131.044};

  var map = new google.maps.Map(document.getElementById('map'), {
    zoom: 4,
    center: myLatLng
  });

  var marker = new google.maps.Marker({
    position: myLatLng,
    map: map,
    title: 'Hello World!'
  });
}

No exemplo acima, o marcador é posicionado no mapa durante a construção do marcador usando a propriedade map nas opções do marcador. Como alternativa, adicione o marcador diretamente ao mapa usando o método setMap() do marcador, como mostrado no exemplo a seguir:

var myLatlng = new google.maps.LatLng(-25.363882,131.044922);
var mapOptions = {
  zoom: 4,
  center: myLatlng
}
var map = new google.maps.Map(document.getElementById("map"), mapOptions);

var marker = new google.maps.Marker({
    position: myLatlng,
    title:"Hello World!"
});

// To add the marker to the map, call setMap();
marker.setMap(map);

O title do marcador é exibido como uma dica de ferramenta.

Se você não quer passar Marker options no construtor do marcador, passe um objeto vazio {} no último argumento do construtor.

Ver o exemplo (marker-simple.html).

Remover um marcador

Para remover um marcador do mapa, chame o método setMap() passando null como argumento.

marker.setMap(null);

Observe que o método acima não exclui o marcador. Ele simplesmente remove o marcador do mapa. Em vez disso, para excluir o marcador, remova-o do mapa e defina o próprio marcador como null.

Para gerenciar um conjunto de marcadores, crie uma matriz para mantê-los. Quando precisar removê-los, use a matriz para chamar setMap() em cada marcador da matriz, um por vez. Exclua os marcadores removendo-os do mapa e definindo o length da matriz como 0, o que remove todas as referências para os marcadores.

Ver o exemplo (marker-remove.html).

Animar um marcador

Anime marcadores para que eles exibam movimento dinâmico em diversas circunstâncias. Para especificar como o marcador é animado, use a propriedade animation do marcador, que tem o tipo google.maps.Animation. Os valores de Animation a seguir são permitidos:

  • DROP indica que o marcador deve cair da parte superior do mapa até a localização final quando colocado pela primeira vez no mapa. A animação termina quando o marcador fica imóvel e o valor de animation volta para null. Normalmente, esse tipo de animação é especificado durante a criação do Marker.
  • BOUNCE indica que o marcador deve saltar no local. O marcador continua a saltar até que a propriedade animation seja definida explicitamente como null.

Inicie uma animação em um marcador existente chamando setAnimation() no objeto Marker.

// The following example creates a marker in Stockholm, Sweden using a DROP
// animation. Clicking on the marker will toggle the animation between a BOUNCE
// animation and no animation.

var marker;

function initMap() {
  var map = new google.maps.Map(document.getElementById('map'), {
    zoom: 13,
    center: {lat: 59.325, lng: 18.070}
  });

  marker = new google.maps.Marker({
    map: map,
    draggable: true,
    animation: google.maps.Animation.DROP,
    position: {lat: 59.327, lng: 18.067}
  });
  marker.addListener('click', toggleBounce);
}

function toggleBounce() {
  if (marker.getAnimation() !== null) {
    marker.setAnimation(null);
  } else {
    marker.setAnimation(google.maps.Animation.BOUNCE);
  }
}
<div id="map"></div>
/* Always set the map height explicitly to define the size of the div
 * element that contains the map. */
#map {
  height: 100%;
}
/* Optional: Makes the sample page fill the window. */
html, body {
  height: 100%;
  margin: 0;
  padding: 0;
}
 <!-- Replace the value of the key parameter with your own API key. -->
<script async defer
src="https://maps.googleapis.com/maps/api/js?key=AIzaSyCkUOdZ5y7hMm0yrcCQoCvLwzdM6M8s5qk&callback=initMap">
</script>
// The following example creates a marker in Stockholm, Sweden using a DROP
// animation. Clicking on the marker will toggle the animation between a BOUNCE
// animation and no animation.

var marker;

function initMap() {
  var map = new google.maps.Map(document.getElementById('map'), {
    zoom: 13,
    center: {lat: 59.325, lng: 18.070}
  });

  marker = new google.maps.Marker({
    map: map,
    draggable: true,
    animation: google.maps.Animation.DROP,
    position: {lat: 59.327, lng: 18.067}
  });
  marker.addListener('click', toggleBounce);
}

function toggleBounce() {
  if (marker.getAnimation() !== null) {
    marker.setAnimation(null);
  } else {
    marker.setAnimation(google.maps.Animation.BOUNCE);
  }
}

Ver o exemplo (marker-animations.html).

Se há vários marcadores, não os coloque no mapa de uma vez. Use setTimeout() para espaçar as animações dos marcadores usando um padrão como este:

function drop() {
  for (var i =0; i < markerArray.length; i++) {
    setTimeout(function() {
      addMarkerMethod();
    }, i * 200);
  }
}

Ver o exemplo (marker-animations-iteration.html).

Personalizar uma imagem de marcador

Se quiser exibir um número ou uma letra em um marcador, é possível usar um rótulo de marcador: Para maior personalização, defina um ícone a ser exibido em vez da imagem padrão do marcador. A definição de um ícone envolve a configuração de várias propriedades que determinam o comportamento visual do marcador.

As seções abaixo descrevem rótulos, ícones simples, ícones complexos e símbolos (ícones vetoriais) de marcador.

Rótulos de marcador

Um rótulo de marcador é um número ou uma letra que aparece dentro de um marcador. A imagem do marcador nesta seção exibe um rótulo de marcador com a letra "B" nele. Especifique um rótulo de marcador como uma string ou um objeto MarkerLabel que inclui uma string e outras propriedades de rótulo.

Ao criar um marcador, especifique uma propriedade label no objeto MarkerOptions. Como alternativa, chame setLabel() no objeto Marker para definir o rótulo em um marcador existente.

O exemplo a seguir exibe marcadores rotulados quando o usuário clica no mapa:

// In the following example, markers appear when the user clicks on the map.
// Each marker is labeled with a single alphabetical character.
var labels = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ';
var labelIndex = 0;

function initialize() {
  var bangalore = { lat: 12.97, lng: 77.59 };
  var map = new google.maps.Map(document.getElementById('map'), {
    zoom: 12,
    center: bangalore
  });

  // This event listener calls addMarker() when the map is clicked.
  google.maps.event.addListener(map, 'click', function(event) {
    addMarker(event.latLng, map);
  });

  // Add a marker at the center of the map.
  addMarker(bangalore, map);
}

// Adds a marker to the map.
function addMarker(location, map) {
  // Add the marker at the clicked location, and add the next-available label
  // from the array of alphabetical characters.
  var marker = new google.maps.Marker({
    position: location,
    label: labels[labelIndex++ % labels.length],
    map: map
  });
}

google.maps.event.addDomListener(window, 'load', initialize);
<div id="map"></div>
/* Always set the map height explicitly to define the size of the div
 * element that contains the map. */
#map {
  height: 100%;
}
/* Optional: Makes the sample page fill the window. */
html, body {
  height: 100%;
  margin: 0;
  padding: 0;
}
<!-- Replace the value of the key parameter with your own API key. -->
<script src="https://maps.googleapis.com/maps/api/js?key=AIzaSyCkUOdZ5y7hMm0yrcCQoCvLwzdM6M8s5qk"></script>
// In the following example, markers appear when the user clicks on the map.
// Each marker is labeled with a single alphabetical character.
var labels = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ';
var labelIndex = 0;

function initialize() {
  var bangalore = { lat: 12.97, lng: 77.59 };
  var map = new google.maps.Map(document.getElementById('map'), {
    zoom: 12,
    center: bangalore
  });

  // This event listener calls addMarker() when the map is clicked.
  google.maps.event.addListener(map, 'click', function(event) {
    addMarker(event.latLng, map);
  });

  // Add a marker at the center of the map.
  addMarker(bangalore, map);
}

// Adds a marker to the map.
function addMarker(location, map) {
  // Add the marker at the clicked location, and add the next-available label
  // from the array of alphabetical characters.
  var marker = new google.maps.Marker({
    position: location,
    label: labels[labelIndex++ % labels.length],
    map: map
  });
}

google.maps.event.addDomListener(window, 'load', initialize);

Ver o exemplo (marker-labels.html).

Ícones simples

No caso mais básico, um ícone pode simplesmente indicar uma imagem a ser usada em vez do ícone padrão de alfinete do Google Maps. Para especificar esse ícone, defina a propriedade icon do marcador como o URL de uma imagem. A Google Maps JavaScript API dimensionará o ícone automaticamente.

// This example adds a marker to indicate the position of Bondi Beach in Sydney,
// Australia.
function initMap() {
  var map = new google.maps.Map(document.getElementById('map'), {
    zoom: 4,
    center: {lat: -33, lng: 151}
  });

  var image = 'https://developers.google.com/maps/documentation/javascript/examples/full/images/beachflag.png';
  var beachMarker = new google.maps.Marker({
    position: {lat: -33.890, lng: 151.274},
    map: map,
    icon: image
  });
}
<div id="map"></div>
/* Always set the map height explicitly to define the size of the div
 * element that contains the map. */
#map {
  height: 100%;
}
/* Optional: Makes the sample page fill the window. */
html, body {
  height: 100%;
  margin: 0;
  padding: 0;
}
 <!-- Replace the value of the key parameter with your own API key. -->
<script async defer
src="https://maps.googleapis.com/maps/api/js?key=AIzaSyCkUOdZ5y7hMm0yrcCQoCvLwzdM6M8s5qk&callback=initMap">
</script>
// This example adds a marker to indicate the position of Bondi Beach in Sydney,
// Australia.
function initMap() {
  var map = new google.maps.Map(document.getElementById('map'), {
    zoom: 4,
    center: {lat: -33, lng: 151}
  });

  var image = 'https://developers.google.com/maps/documentation/javascript/examples/full/images/beachflag.png';
  var beachMarker = new google.maps.Marker({
    position: {lat: -33.890, lng: 151.274},
    map: map,
    icon: image
  });
}

Ver o exemplo (icon-simple.html).

Ícones complexos

Especifique formas complexas para indicar regiões clicáveis e como o ícone deve ser exibido em relação a outras sobreposições (a "ordem de empilhamento"). Para os ícones especificados dessa maneira, defina a propriedade icon deles como um objeto do tipo Icon.

Os objetos Icon definem uma imagem. Eles também definem o size do ícone, a origin do ícone (por exemplo, se a imagem é parte de uma imagem maior em um sprite) e a anchor onde o ponto de acesso do ícone está localizado (baseado na origem).

Se você está usando um label com um marcador personalizado, pode personalizar o rótulo com a propriedade labelOrigin no objeto Icon.

// The following example creates complex markers to indicate beaches near
// Sydney, NSW, Australia. Note that the anchor is set to (0,32) to correspond
// to the base of the flagpole.

function initMap() {
  var map = new google.maps.Map(document.getElementById('map'), {
    zoom: 10,
    center: {lat: -33.9, lng: 151.2}
  });

  setMarkers(map);
}

// Data for the markers consisting of a name, a LatLng and a zIndex for the
// order in which these markers should display on top of each other.
var beaches = [
  ['Bondi Beach', -33.890542, 151.274856, 4],
  ['Coogee Beach', -33.923036, 151.259052, 5],
  ['Cronulla Beach', -34.028249, 151.157507, 3],
  ['Manly Beach', -33.80010128657071, 151.28747820854187, 2],
  ['Maroubra Beach', -33.950198, 151.259302, 1]
];

function setMarkers(map) {
  // Adds markers to the map.

  // Marker sizes are expressed as a Size of X,Y where the origin of the image
  // (0,0) is located in the top left of the image.

  // Origins, anchor positions and coordinates of the marker increase in the X
  // direction to the right and in the Y direction down.
  var image = {
    url: 'https://developers.google.com/maps/documentation/javascript/examples/full/images/beachflag.png',
    // This marker is 20 pixels wide by 32 pixels high.
    size: new google.maps.Size(20, 32),
    // The origin for this image is (0, 0).
    origin: new google.maps.Point(0, 0),
    // The anchor for this image is the base of the flagpole at (0, 32).
    anchor: new google.maps.Point(0, 32)
  };
  // Shapes define the clickable region of the icon. The type defines an HTML
  // <area> element 'poly' which traces out a polygon as a series of X,Y points.
  // The final coordinate closes the poly by connecting to the first coordinate.
  var shape = {
    coords: [1, 1, 1, 20, 18, 20, 18, 1],
    type: 'poly'
  };
  for (var i = 0; i < beaches.length; i++) {
    var beach = beaches[i];
    var marker = new google.maps.Marker({
      position: {lat: beach[1], lng: beach[2]},
      map: map,
      icon: image,
      shape: shape,
      title: beach[0],
      zIndex: beach[3]
    });
  }
}
<div id="map"></div>
/* Always set the map height explicitly to define the size of the div
 * element that contains the map. */
#map {
  height: 100%;
}
/* Optional: Makes the sample page fill the window. */
html, body {
  height: 100%;
  margin: 0;
  padding: 0;
}
 <!-- Replace the value of the key parameter with your own API key. -->
<script async defer
src="https://maps.googleapis.com/maps/api/js?key=AIzaSyCkUOdZ5y7hMm0yrcCQoCvLwzdM6M8s5qk&callback=initMap">
</script>
// The following example creates complex markers to indicate beaches near
// Sydney, NSW, Australia. Note that the anchor is set to (0,32) to correspond
// to the base of the flagpole.

function initMap() {
  var map = new google.maps.Map(document.getElementById('map'), {
    zoom: 10,
    center: {lat: -33.9, lng: 151.2}
  });

  setMarkers(map);
}

// Data for the markers consisting of a name, a LatLng and a zIndex for the
// order in which these markers should display on top of each other.
var beaches = [
  ['Bondi Beach', -33.890542, 151.274856, 4],
  ['Coogee Beach', -33.923036, 151.259052, 5],
  ['Cronulla Beach', -34.028249, 151.157507, 3],
  ['Manly Beach', -33.80010128657071, 151.28747820854187, 2],
  ['Maroubra Beach', -33.950198, 151.259302, 1]
];

function setMarkers(map) {
  // Adds markers to the map.

  // Marker sizes are expressed as a Size of X,Y where the origin of the image
  // (0,0) is located in the top left of the image.

  // Origins, anchor positions and coordinates of the marker increase in the X
  // direction to the right and in the Y direction down.
  var image = {
    url: 'https://developers.google.com/maps/documentation/javascript/examples/full/images/beachflag.png',
    // This marker is 20 pixels wide by 32 pixels high.
    size: new google.maps.Size(20, 32),
    // The origin for this image is (0, 0).
    origin: new google.maps.Point(0, 0),
    // The anchor for this image is the base of the flagpole at (0, 32).
    anchor: new google.maps.Point(0, 32)
  };
  // Shapes define the clickable region of the icon. The type defines an HTML
  // <area> element 'poly' which traces out a polygon as a series of X,Y points.
  // The final coordinate closes the poly by connecting to the first coordinate.
  var shape = {
    coords: [1, 1, 1, 20, 18, 20, 18, 1],
    type: 'poly'
  };
  for (var i = 0; i < beaches.length; i++) {
    var beach = beaches[i];
    var marker = new google.maps.Marker({
      position: {lat: beach[1], lng: beach[2]},
      map: map,
      icon: image,
      shape: shape,
      title: beach[0],
      zIndex: beach[3]
    });
  }
}

Ver o exemplo (icon-complex.html).

Converter objetos MarkerImage para o tipo Icon

Até a versão 3.10 da Google Maps JavaScript API, ícones complexos eram definidos como objetos MarkerImage. O literal de objeto Icon foi adicionado na versão 3.10 e substitui MarkerImage a partir da versão 3.11. Os literais de objeto Icon permitem os mesmos parâmetros que MarkerImage, possibilitando converter facilmente MarkerImage em um Icon removendo o construtor, empacotando os parâmetros anteriores com {} e adicionando os nomes de cada parâmetro. Por exemplo:

var image = new google.maps.MarkerImage(
    place.icon,
    new google.maps.Size(71, 71),
    new google.maps.Point(0, 0),
    new google.maps.Point(17, 34),
    new google.maps.Size(25, 25));

se torna

var image = {
  url: place.icon,
  size: new google.maps.Size(71, 71),
  origin: new google.maps.Point(0, 0),
  anchor: new google.maps.Point(17, 34),
  scaledSize: new google.maps.Size(25, 25)
};

Símbolos

Além de imagens rasterizadas, um marcador permite a exibição de caminhos de vetor, denominados Symbols. Para exibir um caminho de vetor, passe um literal de objeto Symbol com o caminho desejado para a propriedade icon do marcador. Use um dos caminhos predefinidos em google.maps.SymbolPath ou defina um caminho personalizado usando a notação de caminho SVG.

Para obter mais informações, consulte a documentação de símbolos.

Tornar um marcador arrastável

Para permitir que usuários arrastem um marcador para uma localização diferente no mapa, defina draggable como true nas opções do marcador.

var myLatlng = new google.maps.LatLng(-25.363882,131.044922);
var mapOptions = {
  zoom: 4,
  center: myLatlng
}
var map = new google.maps.Map(document.getElementById("map"), mapOptions);

// Place a draggable marker on the map
var marker = new google.maps.Marker({
    position: myLatlng,
    map: map,
    draggable:true,
    title:"Drag me!"
});

Enviar comentários sobre…

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