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

Camadas KML e GeoRSS

A KmlLayer renderiza elementos KML e GeoRSS em uma sobreposição de blocos da Google Maps JavaScript API.

Visão geral

A Google Maps JavaScript API permite os formatos de dados KML e GeoRSS para exibição de informações geográficas. Esses formatos de dados são exibidos no mapa usando um objeto KmlLayer. O construtor do objeto aceita o URL de um arquivo KML ou GeoRSS com acesso público.

A Maps JavaScript API converte os dados geográficos XML fornecidos em uma representação KML, exibida no mapa usando uma sobreposição de blocos Maps JavaScript API. Esse KML parece com (e, às vezes, comporta-se de maneira similar a) elementos de sobreposição Maps JavaScript API familiares. Os elementos <Placemark> do KML e point do GeoRSS são renderizados como marcadores. Por exemplo, elementos <LineString> são renderizados como polilinhas e elementos <Polygon> são renderizados como polígonos. De forma semelhante, elementos <GroundOverlay> são renderizados como imagens retangulares no mapa. No entanto, é importante destacar que esses objetos não são Markers, Polylines, Polygons ou GroundOverlays da Google Maps JavaScript API. Em vez disso, são renderizados em um único objeto no mapa.

Os objetos da KmlLayer são exibidos no mapa assim que sua propriedade map é definida. Remova esses objetos do mapa chamando setMap() e passando null. O objeto KmlLayer administra a renderização desses elementos filhos recuperando automaticamente os recursos apropriados para os limites especificados do mapa. À medida que os limites são alterados, os recursos da porta de visualização atual são automaticamente renderizados.

Como os componentes de uma KmlLayer são renderizados sob demanda, a camada permite administrar facilmente a renderização de milhares de marcadores, polilinhas e polígonos. Observe que não é possível acessar esses objetos envolvidos diretamente, embora todos ofereçam eventos de clique que retornam dados sobre cada um individualmente.

Opções de camada KML

O construtor KmlLayer() passa opcionalmente várias KmlLayerOptions:

  • map especifica o Map onde a KmlLayer é renderizada. Oculte uma KmlLayer definindo esse valor como null no método setMap().
  • preserveViewport especifica que o mapa não é ajustado aos limites do conteúdo da KmlLayer durante a exibição da camada. Por padrão, na exibição de uma KmlLayer, o zoom e a posição do mapa são alterados para mostrar todo o conteúdo da camada.
  • suppressInfoWindows indica que os recursos clicáveis na KmlLayer não acionam a exibição de objetos InfoWindow.

Além disso, após a renderização da KmlLayer, ela contém uma propriedade não alterável metadata com o nome, a descrição, o fragmento e o autor da camada em um literal de objeto KmlLayerMetadata. Examine essas informações usando o método getMetadata(). Como a renderização de objetos KmlLayer exige comunicação assíncrona com um servidor externo, escute o evento metadata_changed, que indica o preenchimento da propriedade.

O exemplo a seguir constrói uma KmlLayer usando o feed GeoRSS fornecido:

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

  var georssLayer = new google.maps.KmlLayer({
    url: 'http://api.flickr.com/services/feeds/geo/?g=322338@N20&lang=en-us&format=feed-georss'
  });
  georssLayer.setMap(map);
}
<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 map = new google.maps.Map(document.getElementById('map'), {
    zoom: 4,
    center: {lat: 49.496675, lng: -102.65625}
  });

  var georssLayer = new google.maps.KmlLayer({
    url: 'http://api.flickr.com/services/feeds/geo/?g=322338@N20&lang=en-us&format=feed-georss'
  });
  georssLayer.setMap(map);
}

Ver o exemplo de GeoRSS

O exemplo a seguir constrói uma KmlLayer usando o feed KML fornecido:

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

  var ctaLayer = new google.maps.KmlLayer({
    url: 'http://googlemaps.github.io/js-v2-samples/ggeoxml/cta.kml',
    map: map
  });
}
<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 map = new google.maps.Map(document.getElementById('map'), {
    zoom: 11,
    center: {lat: 41.876, lng: -87.624}
  });

  var ctaLayer = new google.maps.KmlLayer({
    url: 'http://googlemaps.github.io/js-v2-samples/ggeoxml/cta.kml',
    map: map
  });
}

Ver o exemplo de KML

Detalhes de recurso KML

Como o KML pode incluir um grande número de recursos, não é possível acessar dados de recurso diretamente no objeto KmlLayer. Em vez disso, à medida que os recursos são exibidos, eles são renderizados com a aparência de sobreposições clicáveis da Maps JavaScript API. O clique em recursos individuais, por padrão, exibe uma InfoWindow contendo as informações <title> e <description> do KML para o recurso clicado. Além disso, o clique em um recurso KML gera um KmlMouseEvent, que passa as seguintes informações:

  • position indica as coordenadas de latitude/longitude onde ancorar a InfoWindow desse recurso KML. Essa posição normalmente é a localização clicada para polígonos, polilinhas e GroundOverlays. Para marcadores, é a origem verdadeira.
  • pixelOffset indica o deslocamento da position acima para ancorar a "ponta" da InfoWindow. Para objetos poligonais, esse deslocamento é normalmente 0,0. Para marcadores, ele inclui a altura do marcador.
  • featureData contém uma estrutura JSON de KmlFeatureData.

Veja a seguir um exemplo de objeto KmlFeatureData:

{
  author: {
    email: "nobody@google.com",
    name: "Mr Nobody",
    uri: "http://example.com"
  },
  description: "description",
  id: "id",
  infoWindowHtml: "html",
  name: "name",
  snippet: "snippet"
}

O exemplo a seguir exibe o texto do recurso KML <Description> em um <div> lateral quando o recurso é clicado:

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

  var kmlLayer = new google.maps.KmlLayer({
    url: 'http://googlemaps.github.io/kml-samples/kml/Placemark/placemark.kml',
    suppressInfoWindows: true,
    map: map
  });

  kmlLayer.addListener('click', function(kmlEvent) {
    var text = kmlEvent.featureData.description;
    showInContentWindow(text);
  });

  function showInContentWindow(text) {
    var sidediv = document.getElementById('content-window');
    sidediv.innerHTML = text;
  }
}
<div id="map"></div>
<div id="content-window"></div>
html, body {
  height: 100%;
  margin: 0;
  padding: 0;
}
#map {
  float: left;
  height: 100%;
  width: 79%;
}
#content-window {
  float: left;
  font-family: 'Roboto','sans-serif';
  height: 100%;
  line-height: 30px;
  padding-left: 10px;
  width: 19%;
}
 <!-- 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 map = new google.maps.Map(document.getElementById('map'), {
    zoom: 12,
    center: {lat: 37.06, lng: -95.68}
  });

  var kmlLayer = new google.maps.KmlLayer({
    url: 'http://googlemaps.github.io/kml-samples/kml/Placemark/placemark.kml',
    suppressInfoWindows: true,
    map: map
  });

  kmlLayer.addListener('click', function(kmlEvent) {
    var text = kmlEvent.featureData.description;
    showInContentWindow(text);
  });

  function showInContentWindow(text) {
    var sidediv = document.getElementById('content-window');
    sidediv.innerHTML = text;
  }
}

Ver o exemplo de KML

Restrições de complexidade e tamanho para renderização de KML

A Google Maps JavaScript API tem limites no tamanho e na complexidade dos arquivos KML carregados. Veja um resumo dos limites atuais abaixo:

Observação: Estes limites estão sujeitos a alterações a qualquer momento.

Tamanho máximo do arquivo obtido (KML bruto, GeoRSS bruto ou KMZ compactado)
3 MB
Tamanho máximo do arquivo KML descompactado
10 MB
Número máximo de Links de rede
10
Número máximo de recursos do tamanho total do documento
1.000
Número de camadas KML
Há um limite no número de Camadas KML que podem ser exibidas em um único Google Map. Se você exceder este limite, nenhuma das suas camadas aparecerão no mapa e um erro será denunciado ao console JavaScript do navegador da Web. O limite é baseado em uma combinação de números das classes KMLLayer criadas e o comprimento total de todos os URLs usados para criar estas camadas. Cada nova KMLLayer que você cria tomará uma porção do limite para a camada e uma porção a mais do limite, dependendo do comprimento do URL de onde o arquivo KML foi carregado. Consequentemente, o número de camadas que você pode adicionar variará com o aplicativo; em média, é possível carregar entre 10 e 20 camadas sem exceder o limite. Se você mesmo assim atingir o limite, use um encurtador de URL (como https://goo.gl) para encurtar os URLS de KML. Como alternativa, crie um arquivo KML único contendo os NetworkLinks aos URLS do KML individuais.

Elementos KML suportados

A Google Maps JavaScript API suporta os seguintes elementos KML. O analisador de KML ignora silenciosamente, geralmente, tags XML que não entende.

  • Placemarks
  • Ícones
  • Pastas
  • HTML descritivo — substituição de entidade via <BalloonStyle> e <text>
  • KMZ (KML compactado, incluindo imagens anexadas)
  • Polilinhas e polígonos
  • Estilos para polilinhas e polígonos, incluindo cor, preenchimento e opacidade
  • Links de rede para importar dados dinamicamente
  • Sobreposições de solo e sobreposições de tela

A tabela a seguir fornece detalhes completos dos elementos KML suportados.

Elemento KML Suportado na API? Comentário
<address> no
<AddressDetails> não
<Alias> N/A <Model> não é permitido
<altitude> no
<altitudeMode> no
<atom:author> sim
<atom:link> sim
<atom:name> sim
<BalloonStyle> parcialmente somente <text> é permitido
<begin> N/A <TimeSpan> não é permitido
<bgColor> no
<bottomFov> N/A <PhotoOverlay> não é permitido
<Camera> no
<Change> parcialmente somente alterações de estilo são permitidas
<color> parcialmente inclui #AABBGGRR e #BBGGRR; não suportado em <IconStyle>, <ScreenOverlay> e <GroundOverlay>
<colorMode> no
<cookie> no
<coordinates> sim
<Create> no
<Data> sim
<Delete> no
<description> sim O conteúdo do HTML é suportado, mas é verificado para proteger contra ataques entre navegadores. As substituições de entidade do formulário $[dataName] não são suportados.
<displayMode> no
<displayName> no
<Document> parcialmente implicitamente, filhos não são suportados; nenhum efeito como filho de outros Recursos
<drawOrder> no
<east> sim
<end> N/A <TimeSpan> não é permitido
<expires> sim consulte a seção Resumo para obter detalhes
<ExtendedData> parcialmente somente <Data> sem tipo; <SimpleData>, <Schema> e substituições de entidade do formulário $[dataName] não são permitidos.
<extrude> no
<fill> sim
<flyToView> no
<Folder> sim
<geomColor> no obsoleto
<GeometryCollection> no obsoleto
<geomScale> no obsoleto
<gridOrigin> N/A <PhotoOverlay> não é permitido
<GroundOverlay> sim não pode ser rotacionado
<h> sim obsoleto
<heading> sim
hint sim target=... suportado
<hotSpot> sim
<href> sim
<httpQuery> no
<Icon> sim não pode ser rotacionado
<IconStyle> sim
<ImagePyramid> N/A <PhotoOverlay> não é permitido
<innerBoundaryIs> sim implicitamente da ordem <LinearRing>
<ItemIcon> N/A <ListStyle> não é permitido
<key> N/A <StyleMap> não é suportado
<kml> sim
<labelColor> no obsoleto
<LabelStyle> no
<latitude> sim
<LatLonAltBox> sim
<LatLonBox> sim
<leftFov> N/A <PhotoOverlay> não é permitido
<LinearRing> sim
<LineString> sim
<LineStyle> sim
<Link> sim
<linkDescription> no
<linkName> no
<linkSnippet> no
<listItemType> N/A <ListStyle> não é permitido
<ListStyle> no
<Location> N/A <Model> não é permitido
<Lod> sim
<longitude> sim
<LookAt> no
<maxAltitude> sim
<maxFadeExtent> sim
<maxHeight> N/A <PhotoOverlay> não é permitido
<maxLodPixels> sim
<maxSessionLength> no
<maxWidth> N/A <PhotoOverlay> não é permitido
<message> no
<Metadata> no obsoleto
<minAltitude> sim
<minFadeExtent> sim
<minLodPixels> sim
<minRefreshPeriod> no <NetworkLink>
<Model> no
<MultiGeometry> parcialmente renderizado, mas exibido como recursos separados no painel do lado esquerdo
<name> sim
<near> N/A <PhotoOverlay> não é permitido
<NetworkLink> sim  
<NetworkLinkControl> parcialmente <Update> e <expires> parcialmente suportados. A API ignora as configurações de expiração nos cabeçalhos HTTP, mas não usa as configurações de expiração especificadas no KML. Na ausência de configurações de expiração ou dentro do intervalo de validade, o Google Maps pode armazenar em cache os dados obtidos da Internet por durações não especificadas. Uma nova obtenção de dados da Internet pode ser forçada renomeando o documento e obtendo-o com um URL diferente, ou garantindo que o documento contenha configurações de expiração adequadas.
<north> sim
<open> sim
<Orientation> N/A <Model> não é permitido
<outerBoundaryIs> sim implicitamente da ordem <LinearRing>
<outline> sim
<overlayXY> no
<Pair> N/A <StyleMap> não é suportado
<phoneNumber> no
<PhotoOverlay> no
<Placemark> sim
<Point> sim
<Polygon> sim
<PolyStyle> sim
<range> sim
<refreshInterval> parcialmente Somente <Link>; não em <Icon>
<refreshMode> sim Os cabeçalhos HTTP não são suportados para o modo "onExpire". Consulte as notas em <Update> e <expires> acima.
<refreshVisibility> no
<Region> sim
<ResourceMap> N/A <Model> não é permitido
<rightFov> N/A <PhotoOverlay> não é permitido
<roll> N/A <Camera> e <Model> não são permitidos
<rotation> no
<rotationXY> no
<Scale> N/A <Model> não é permitido
<scale> no
<Schema> no
<SchemaData> no
<ScreenOverlay> sim não pode ser rotacionado
<screenXY> no
<shape> N/A <PhotoOverlay> não é permitido
<SimpleData> N/A <SchemaData> não são permitidos
<SimpleField> N/A <Schema> não são permitidos
<size> sim
<Snippet> sim
<south> sim
<state> N/A <ListStyle> não é compatível
<Style> sim
<StyleMap> no efeitos de rollover (destaque) não são suportados
<styleUrl> N/A <StyleMap> não é suportado
<targetHref> parcialmente suportado em <Update>, não em <Alias>
<tessellate> no
<text> sim a substituição de $[geDirections] não é suportada
<textColor> no
<tileSize> N/A <PhotoOverlay> não é permitido
<tilt> no
<TimeSpan> no
<TimeStamp> no
<topFov> N/A <PhotoOverlay> não é permitido
<Update> parcialmente somente alterações de estilo, não <Create> ou <Delete>
<Url> sim obsoleto
<value> sim
<viewBoundScale> no
<viewFormat> no
<viewRefreshMode> parcialmente "onStop" é suportado
<viewRefreshTime> sim
<ViewVolume> N/A <PhotoOverlay> não é permitido
<visibility> parcialmente sim em <Folder> - marcadores filhos herdam a visibilidade
<w> sim obsoleto
<west> sim
<when> N/A <TimeStamp> não é permitido
<width> sim
<x> sim obsoleto
<y> sim obsoleto

Enviar comentários sobre…

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