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

Biblioteca de geometria

  1. Visão geral
  2. Conceitos de geometria esférica
    1. Funções de distância e área
    2. Funções de navegação
  3. Codificação de geometria
  4. Funções de polígono e polilinha
    1. containsLocation()
    2. isLocationOnEdge()

Visão geral

Os conceitos deste documento são relacionados a recursos disponíveis apenas na biblioteca google.maps.geometry. Essa biblioteca não é carregada por padrão no carregamento da Maps JavaScript API e precisa ser especificada explicitamente usando o parâmetro de bootstrap libraries.

Consulte Visão geral das bibliotecas para obter mais informações.

A biblioteca de geometria da Google Maps JavaScript API fornece funções utilitárias para o cálculo de dados geométricos na superfície do planeta. A biblioteca inclui três espaços de nome:

  • spherical contém utilitários de geometria esférica que permitem calcular ângulos, distâncias e áreas de latitudes e longitudes.
  • encoding contém utilitários para codificar e decodificar caminhos de polilinha de acordo com o algoritmo de polilinha codificada.
  • poly contém funções utilitárias para cálculos envolvendo polígonos e polilinhas.

A biblioteca google.maps.geometry não contém nenhuma classe, mas contém métodos estáticos para os espaços de nome acima.

Conceitos de geometria esférica

As imagens na Google Maps JavaScript API são bidimensionais e "planas". No entanto, o planeta é tridimensional e é frequentemente aproximado como um esferoide oblato ou, mais simplesmente, uma esfera. Na Maps API, usamos uma esfera. Para representar o planeta em uma superfície plana bidimensional, como a tela do computador, a Maps API usa uma projeção.

Em projeções 2D, as aparências podem enganar. Como a projeção do mapa necessariamente exige alguma distorção, muitas vezes a geometria euclidiana simples não é aplicável. Por exemplo, a menor distância entre dois pontos em uma esfera não é uma linha reta, mas um grande círculo (um tipo de geodésica) e os ângulos que formam um triângulo na superfície de uma esfera somam mais de 180 graus.

Devido a essas diferenças, as funções geométricas em uma esfera (ou em sua projeção) precisam usar a geometria esférica para calcular construções como distância, rumo e área. Os utilitários para calcular essas construções geométricas especiais estão no espaço de nome google.maps.geometry.spherical da Maps API. Esse espaço de nome oferece métodos estáticos para calcular valores escalares de coordenadas esféricas (latitudes e longitudes).

Funções de distância e área

A distância entre dois pontos é o comprimento do caminho mais curto entre eles. Esse caminho mais curto é denominado geodésica. Em uma esfera, todas as geodésicas são segmentos de um grande círculo. Para calcular essa distância, chame computeDistanceBetween() passando dois objetos LatLng.

Também é possível usar computeLength() para calcular o comprimento de um determinado caminho no caso de várias localizações.

Os resultados de distância são expressos em metros.

Para calcular a área (em metros quadrados) de uma área poligonal, chame computeArea() passando uma matriz de objetos LatLng que definem um loop fechado.

Na navegação em uma esfera, um rumo é o ângulo de uma rota em relação a um ponto de referência fixo, normalmente o norte verdadeiro. Com a Google Maps API, um rumo é definido em graus em relação ao norte verdadeiro, medidos no sentido horário a partir do norte verdadeiro (0 graus). Calcule esse rumo entre duas localizações com o método computeHeading(), passando dois objetos from e to LatLng.

Considerando um determinado rumo, uma localização de origem e a distância a percorrer (em metros), você pode calcular as coordenadas do destino usando computeOffset().

Dados dois objetos LatLng e um valor entre 0 e 1, também é possível calcular um destino entre eles usando o método interpolate(), que executa interpolações lineares esféricas entre as duas localizações. O valor indica a distância fracionária a percorrer ao longo do caminho, da origem ao destino.

O exemplo a seguir cria duas polilinhas quando dois pontos no mapa são clicados, uma polilinha geodésica e uma linha "reta" conectando as duas localizações, e calcula o rumo para viajar entre os dois pontos:

// This example requires the Geometry library. Include the libraries=geometry
// parameter when you first load the API. For example:
// <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=geometry">

var marker1, marker2;
var poly, geodesicPoly;

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

  map.controls[google.maps.ControlPosition.TOP_CENTER].push(
      document.getElementById('info'));

  marker1 = new google.maps.Marker({
    map: map,
    draggable: true,
    position: {lat: 40.714, lng: -74.006}
  });

  marker2 = new google.maps.Marker({
    map: map,
    draggable: true,
    position: {lat: 48.857, lng: 2.352}
  });

  var bounds = new google.maps.LatLngBounds(
      marker1.getPosition(), marker2.getPosition());
  map.fitBounds(bounds);

  google.maps.event.addListener(marker1, 'position_changed', update);
  google.maps.event.addListener(marker2, 'position_changed', update);

  poly = new google.maps.Polyline({
    strokeColor: '#FF0000',
    strokeOpacity: 1.0,
    strokeWeight: 3,
    map: map,
  });

  geodesicPoly = new google.maps.Polyline({
    strokeColor: '#CC0099',
    strokeOpacity: 1.0,
    strokeWeight: 3,
    geodesic: true,
    map: map
  });

  update();
}

function update() {
  var path = [marker1.getPosition(), marker2.getPosition()];
  poly.setPath(path);
  geodesicPoly.setPath(path);
  var heading = google.maps.geometry.spherical.computeHeading(path[0], path[1]);
  document.getElementById('heading').value = heading;
  document.getElementById('origin').value = path[0].toString();
  document.getElementById('destination').value = path[1].toString();
}
<div id="map"></div>
<div id="floating-panel">
  Origin: <input type="text" readonly id="origin">
  Destination: <input type="text" readonly id="destination"><br>
  Heading: <input type="text" readonly id="heading"> degrees
</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;
}
#floating-panel {
  position: absolute;
  top: 10px;
  left: 25%;
  z-index: 5;
  background-color: #fff;
  padding: 5px;
  border: 1px solid #999;
  text-align: center;
  font-family: 'Roboto','sans-serif';
  line-height: 30px;
  padding-left: 10px;
}
<!-- Replace the value of the key parameter with your own API key. -->
<script src="https://maps.googleapis.com/maps/api/js?key=AIzaSyCkUOdZ5y7hMm0yrcCQoCvLwzdM6M8s5qk&libraries=geometry&callback=initMap"
    async defer></script>
// This example requires the Geometry library. Include the libraries=geometry
// parameter when you first load the API. For example:
// <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=geometry">

var marker1, marker2;
var poly, geodesicPoly;

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

  map.controls[google.maps.ControlPosition.TOP_CENTER].push(
      document.getElementById('info'));

  marker1 = new google.maps.Marker({
    map: map,
    draggable: true,
    position: {lat: 40.714, lng: -74.006}
  });

  marker2 = new google.maps.Marker({
    map: map,
    draggable: true,
    position: {lat: 48.857, lng: 2.352}
  });

  var bounds = new google.maps.LatLngBounds(
      marker1.getPosition(), marker2.getPosition());
  map.fitBounds(bounds);

  google.maps.event.addListener(marker1, 'position_changed', update);
  google.maps.event.addListener(marker2, 'position_changed', update);

  poly = new google.maps.Polyline({
    strokeColor: '#FF0000',
    strokeOpacity: 1.0,
    strokeWeight: 3,
    map: map,
  });

  geodesicPoly = new google.maps.Polyline({
    strokeColor: '#CC0099',
    strokeOpacity: 1.0,
    strokeWeight: 3,
    geodesic: true,
    map: map
  });

  update();
}

function update() {
  var path = [marker1.getPosition(), marker2.getPosition()];
  poly.setPath(path);
  geodesicPoly.setPath(path);
  var heading = google.maps.geometry.spherical.computeHeading(path[0], path[1]);
  document.getElementById('heading').value = heading;
  document.getElementById('origin').value = path[0].toString();
  document.getElementById('destination').value = path[1].toString();
}

Ver o exemplo (geometry-headings.html).

Métodos de codificação

Os caminhos na Google Maps JavaScript API são frequentemente especificados como uma Array de objetos LatLng. No entanto, essa matriz é volumosa demais para ser passada. Em vez disso, use o algoritmo de codificação de polilinha do Google para comprimir um determinado caminho, que pode ser posteriormente descomprimido usando decodificação.

A biblioteca geometry contém um espaço de nome encoding para utilitários que codificam e decodificam polilinhas.

O método estático encodePath() codifica o caminho especificado. Passe uma matriz de LatLng ou uma MVCArray (que é retornada por Polyline.getPath()).

Para descodificar um caminho codificado, basta chamar decodePath(), passando ao método a string codificada.

O exemplo a seguir exibe um mapa de Oxford, Mississippi. Um clique no mapa adiciona um ponto a uma polilinha. À medida que a polilinha é construída, a codificação é exibida abaixo.

// This example requires the Geometry library. Include the libraries=geometry
// parameter when you first load the API. For example:
// <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=geometry">

function initMap() {
  var map = new google.maps.Map(document.getElementById('map'), {
    zoom: 14,
    center: {lat: 34.366, lng: -89.519}
  });
  var poly = new google.maps.Polyline({
    strokeColor: '#000000',
    strokeOpacity: 1,
    strokeWeight: 3,
    map: map
  });

  // Add a listener for the click event
  google.maps.event.addListener(map, 'click', function(event) {
    addLatLngToPoly(event.latLng, poly);
  });
}

/**
 * Handles click events on a map, and adds a new point to the Polyline.
 * Updates the encoding text area with the path's encoded values.
 */
function addLatLngToPoly(latLng, poly) {
  var path = poly.getPath();
  // Because path is an MVCArray, we can simply append a new coordinate
  // and it will automatically appear
  path.push(latLng);

  // Update the text field to display the polyline encodings
  var encodeString = google.maps.geometry.encoding.encodePath(path);
  if (encodeString) {
    document.getElementById('encoded-polyline').value = encodeString;
  }
}
<div id="map"></div>
<div id="right-panel">
  <div>Encoding:</div>
  <textarea id="encoded-polyline"></textarea>
</div>
#right-panel {
  font-family: 'Roboto','sans-serif';
  line-height: 30px;
  padding-left: 10px;
}

#right-panel select, #right-panel input {
  font-size: 15px;
}

#right-panel select {
  width: 100%;
}

#right-panel i {
  font-size: 12px;
}
html, body {
  height: 100%;
  margin: 0;
  padding: 0;
}
#map {
  height: 100%;
  width: 50%;
  float: left;
}
#right-panel {
  width: 46%;
  float: left;
}
#encoded-polyline {
  height: 100px;
  width: 100%;
}
<!-- Replace the value of the key parameter with your own API key. -->
<script src="https://maps.googleapis.com/maps/api/js?key=AIzaSyCkUOdZ5y7hMm0yrcCQoCvLwzdM6M8s5qk&libraries=geometry&callback=initMap"
    async defer></script>
// This example requires the Geometry library. Include the libraries=geometry
// parameter when you first load the API. For example:
// <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=geometry">

function initMap() {
  var map = new google.maps.Map(document.getElementById('map'), {
    zoom: 14,
    center: {lat: 34.366, lng: -89.519}
  });
  var poly = new google.maps.Polyline({
    strokeColor: '#000000',
    strokeOpacity: 1,
    strokeWeight: 3,
    map: map
  });

  // Add a listener for the click event
  google.maps.event.addListener(map, 'click', function(event) {
    addLatLngToPoly(event.latLng, poly);
  });
}

/**
 * Handles click events on a map, and adds a new point to the Polyline.
 * Updates the encoding text area with the path's encoded values.
 */
function addLatLngToPoly(latLng, poly) {
  var path = poly.getPath();
  // Because path is an MVCArray, we can simply append a new coordinate
  // and it will automatically appear
  path.push(latLng);

  // Update the text field to display the polyline encodings
  var encodeString = google.maps.geometry.encoding.encodePath(path);
  if (encodeString) {
    document.getElementById('encoded-polyline').value = encodeString;
  }
}

Ver o exemplo (geometry-encodings.html).

Funções de polígono e polilinha

O espaço de nome poly da biblioteca de geometria contém funções utilitárias que determinam se um determinado ponto está dentro ou perto de um polígono ou polilinha.

containsLocation()

containsLocation(point:LatLng, polygon:Polygon)

Para saber se um determinado ponto está dentro de um polígono, passe o ponto e o polígono para google.maps.geometry.poly.containsLocation(). A função retorna true se o ponto está dentro ou na borda do polígono.

O código a seguir escreve "true" no console do navegador se o clique do usuário é feito dentro do triângulo definido. Caso contrário, escreve "false".

function initialize() {
  var mapOptions = {
    zoom: 5,
    center: new google.maps.LatLng(24.886, -70.269),
    mapTypeId: 'terrain'
  };

  var map = new google.maps.Map(document.getElementById('map'),
      mapOptions);

  var bermudaTriangle = new google.maps.Polygon({
    paths: [
      new google.maps.LatLng(25.774, -80.190),
      new google.maps.LatLng(18.466, -66.118),
      new google.maps.LatLng(32.321, -64.757)
    ]
  });

  google.maps.event.addListener(map, 'click', function(event) {
    console.log(google.maps.geometry.poly.containsLocation(event.latLng, bermudaTriangle));
  });
}

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

Outra versão desse código desenha um círculo vermelho no mapa se o clique é feito dentro do Triângulo das Bermudas. Caso contrário, o círculo é verde.

Ver o exemplo (poly-containsLocation)

isLocationOnEdge()

isLocationOnEdge(point:LatLng, poly:Polygon|Polyline, tolerance?:number)

Para determinar se um ponto está sobre ou perto de uma polilinha ou de uma borda de polígono, passe o ponto, a polilinha ou o polígono e, opcionalmente um valor de tolerância em graus para google.maps.geometry.poly.isLocationOnEdge(). A função retorna true se a distância entre o ponto e o ponto mais próximo na linha ou borda está dentro da tolerância especificada. A tolerância padrão é 10-9 graus.

function initialize() {
  var myPosition = new google.maps.LatLng(46.0, -125.9);

  var mapOptions = {
    zoom: 5,
    center: myPosition,
    mapTypeId: 'terrain'
  };

  var map = new google.maps.Map(document.getElementById('map'),
      mapOptions);

  var cascadiaFault = new google.maps.Polyline({
    path: [
      new google.maps.LatLng(49.95, -128.1),
      new google.maps.LatLng(46.26, -126.3),
      new google.maps.LatLng(40.3, -125.4)
    ]
  });

  cascadiaFault.setMap(map);

  if (google.maps.geometry.poly.isLocationOnEdge(myPosition, cascadiaFault, 10e-1)) {
    alert("Relocate!");
  }
}

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

Enviar comentários sobre…

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