Tutorial do KML

KML é um formato de arquivo usado para exibir dados geográficos em um navegador da Terra, como Google Earth, Google Maps e Google Maps para celular. O KML utiliza uma estrutura de tags com elementos e atributos aninhados e se baseia no padrão XML. Todas as tags diferenciam maiúscula de minúscula e precisam aparecer exatamente como estão listadas na Referência de KML. A Referência indica quais tags são opcionais. Em determinado elemento, as tags devem aparecer na ordem mostrada na referência.

Se você não conhece KML, explore este documento e os arquivos de amostra que o acompanham (SamplesInEarth e SamplesInMaps) para começar a aprender sobre a estrutura básica de um arquivo KML e as tags mais usadas. A primeira seção descreve os elementos que podem ser criados com a interface de usuário do Google Earth. Esses elementos incluem marcadores, descrições, superposições de solo, caminhos e polígonos. A segunda seção descreve os elementos que exigem a criação de KML com um editor de texto. Quando um arquivo de texto é salvo com a extensão .kml ou .kmz, os navegadores da Terra sabem como exibi-lo.

Dica: para ver o "código" KML de um elemento no Google Earth, basta clicar com o botão direito do mouse no elemento no Visualizador em 3D do Google Earth e selecionar "Copiar". Em seguida, cole o conteúdo da área de transferência em qualquer editor de texto. O elemento visual exibido no Google Earth é convertido em seu equivalente de texto KML. Experimente esse elemento.

Todos os exemplos descritos aqui estão no arquivo Amostras de KML. Comece fazendo download desse arquivo para exibir os exemplos no Google Earth.

Para obter mais informações

A Referência de KML 2.2 fornece detalhes sobre o formato de arquivo KML. Se você estiver familiarizado com XML, também se interessará pelo Esquema KML 2.2.

Para obter uma discussão sobre como usar alguns dos principais elementos em KML, consulte o Guia do desenvolvedor.

Sumário

Documentos KML básicos
Documentos KML avançados
Tipos KML MIME

Documentos KML básicos

O tipo mais simples de documento KML é aquele que pode ser criado diretamente no Google Earth; ou seja, não é necessário editar ou criar qualquer KML em um editor de texto. Marcadores, superposições de solo, caminhos e polígonos podem ser criados diretamente no Google Earth.

Marcadores

Um marcador é um dos elementos mais usados no Google Earth. Ele marca uma posição na superfície da Terra, usando um alfinete amarelo como ícone. O marcador mais simples inclui apenas um elemento <Point>, que especifica o local do marcador. É possível especificar um nome e um ícone personalizado para o marcador e também adicionar outros elementos de geometria a ele.

Abra o arquivo Amostras de KML no Google Earth e expanda a subpasta de marcadores. Essa pasta inclui três tipos diferentes de marcador: simples, flutuante e excluído. O código KML para o marcador simples parece com o seguinte:

<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://www.opengis.net/kml/2.2"> <Placemark>
 <name>Simple placemark</name>
 <description>Attached to the ground. Intelligently places itself at the height of the underlying terrain.</description>
 <Point>
 <coordinates>-122.0822035425683,37.42228990140251,0</coordinates>
 </Point>
 </Placemark> </kml>

A estrutura desse arquivo é dividida da seguinte maneira:

Um cabeçalho XML. Essa é a linha 1 de todo arquivo KML. Nenhum espaço ou caractere pode aparecer antes dessa linha.
Uma declaração de namespace KML. Essa é a linha 2 de todo arquivo KML 2.2.
Um objeto Placemark que contém os seguintes elementos:
- Um nome que é usado como o rótulo do marcador
- Uma descrição que aparece no "balão" anexado ao marcador
- Um ponto que especifica a posição do marcador na superfície da Terra (longitude, latitude e altitude opcional)

Se você quer saber onde está o marcador, ele está no Edifício 41 do Google, onde desenvolvemos o Google Earth!

O que os usuários normalmente pensam ser um "marcador" no Google Earth é na verdade um elemento <Placemark> com um filho <Point> em KML. Um marcador de ponto é a única maneira de desenhar um ícone e rótulo no Visualizador em 3D do Google Earth. Por padrão, o ícone é o alfinete amarelo conhecido. Em KML, um <Placemark> pode conter um ou mais elementos de geometria, como um LineString, Polygon ou Model Mas somente um <Placemark> com um ponto pode ter um ícone e um rótulo. O ponto é usado para colocar o ícone, mas não há representação gráfica do próprio ponto.

HTML descritivo em marcadores

O arquivo Amostras de KML tem um exemplo de quase tudo o que você pode fazer com o texto do marcador. É possível adicionar links, tamanhos, estilos e cores de fontes e especificar o alinhamento de texto e tabelas. Para ver a lista completa, copie e cole o exemplo de marcador "HTML descritivo" (na pasta "Estilos e marcação") em um editor de texto.

Marcação automática no Google Earth (versão 4.0 e posteriores)

O Google Earth 4.0 possui um elemento de marcação automática que converte automaticamente textos, como www.google.com, em hiperlinks ativos nos quais o usuário pode clicar. O texto dentro da tag <description>, a tag <Snippet> e o elemento <text> de <BalloonStyle> são transformados automaticamente em hiperlinks HTTP padrão. Não é necessário adicionar as tags <a href=...>.

Como usar o elemento CDATA

Para escrever HTML padrão em uma tag <description>, você pode colocá-la em uma tag CDATA. Se não fizer isso, os colchetes precisarão ser escritos como referências de entidade para impedir que o Google Earth analise o HTML incorretamente (por exemplo, o símbolo > é escrito como >, e o símbolo < como <). Esse é um elemento padrão de XML e não é exclusivo do Google Earth.

Considere a diferença entre a marcação HTML com tags CDATA e sem CDATA. Primeiro, veja a <description> com tags CDATA:

<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://www.opengis.net/kml/2.2"> <Document> <Placemark> <name>CDATA example</name> <description> <![CDATA[ <h1>CDATA Tags are useful!</h1> <p><font color="red">Text is <i>more readable</i> and <b>easier to write</b> when you can avoid using entity references.</font></p> ]]> </description> <Point> <coordinates>102.595626,14.996729</coordinates> </Point> </Placemark> </Document> </kml>

E veja a <description> sem tags CDATA, de modo que os caracteres especiais precisam usar referências de entidade:

<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://www.opengis.net/kml/2.2"> <Document> <Placemark> <name>Entity references example</name> <description> &lt;h1&gt;Entity references are hard to type!&lt;/h1&gt; &lt;p&gt;&lt;font color="green"&gt;Text is &lt;i&gt;more readable&lt;/i&gt; and &lt;b&gt;easier to write&lt;/b&gt; when you can avoid using entity references.&lt;/font&gt;&lt;/p&gt; </description> <Point> <coordinates>102.594411,14.998518</coordinates> </Point> </Placemark> </Document> </kml>

Superposições de solo

As superposições de solo permitem "aplicar" uma imagem no terreno da Terra. O elemento <Icon> contém o link para o arquivo .jpg com a imagem de superposição. Veja um exemplo de superposição de solo no arquivo Amostras de KML, que mostra o Vulcão Etna entrando em erupção em 2001:

<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://www.opengis.net/kml/2.2"> <Folder>
 <name>Ground Overlays</name>
 <description>Examples of ground overlays</description>
 <GroundOverlay>
 <name>Large-scale overlay on terrain</name>
 <description>Overlay shows Mount Etna erupting on July 13th, 2001.</description>
 <Icon>
 <href>http://developers.google.com/kml/documentation/images/etna.jpg</href>
 </Icon>
 <LatLonBox>
 <north>37.91904192681665</north>
 <south>37.46543388598137</south>
 <east>15.35832653742206</east>
 <west>14.60128369746704</west>
 <rotation>-0.1556640799496235</rotation>
 </LatLonBox>
 </GroundOverlay>
 </Folder> </kml>

Observe que o arquivo começa com as mesmas duas linhas que o primeiro exemplo: o cabeçalho XML e a declaração de namespace de KML.

Esse exemplo usa uma pasta (intitulada "Superposições de solo") como um mecanismo para agrupar e marcar seu conteúdo. A pasta é exibida no painel "Lugares" quando você carrega o arquivo Amostras KML no Google Earth.

O posicionamento de uma superposição de solo é controlado pela tag <LatLonBox>. Os valores de limitação são fornecidos para as latitudes Norte e Sul, e as longitudes, Leste e Oeste. Além disso, os valores de rotação são fornecidos para imagens cujo eixo y não coincidem com a grade Norte. Esse exemplo usa uma imagem JPEG para a superposição. O Google Earth também suporta os formatos BMP, GIF, TIFF, TGA e PNG.

Caminhos

É possível criar diferentes tipos de caminhos no Google Earth, e é fácil ser criativo com seus dados. Em KML, um caminho é criado por um elemento <LineString>. Observe o exemplo "Absolute Extruded" na pasta "Paths" e veja como a forma foi gerada pelo seguinte código:

<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://www.opengis.net/kml/2.2"> <Document>
 <name>Paths</name>
 <description>Examples of paths. Note that the tessellate tag is by default
 set to 0. If you want to create tessellated lines, they must be authored
 (or edited) directly in KML.</description> <Style id="yellowLineGreenPoly">
 <LineStyle>
 <color>7f00ffff</color>
 <width>4</width>
 </LineStyle>
 <PolyStyle>
 <color>7f00ff00</color>
 </PolyStyle>
 </Style> <Placemark>
 <name>Absolute Extruded</name>
 <description>Transparent green wall with yellow outlines</description>
 <styleUrl>#yellowLineGreenPoly</styleUrl>
 <LineString>
 <extrude>1</extrude>
 <tessellate>1</tessellate>
 <altitudeMode>absolute</altitudeMode>
 <coordinates> -112.2550785337791,36.07954952145647,2357
 -112.2549277039738,36.08117083492122,2357
 -112.2552505069063,36.08260761307279,2357
 -112.2564540158376,36.08395660588506,2357
 -112.2580238976449,36.08511401044813,2357
 -112.2595218489022,36.08584355239394,2357
 -112.2608216347552,36.08612634548589,2357
 -112.262073428656,36.08626019085147,2357
 -112.2633204928495,36.08621519860091,2357
 -112.2644963846444,36.08627897945274,2357
 -112.2656969554589,36.08649599090644,2357 </coordinates>
 </LineString> </Placemark>
 </Document> </kml>

Perceba como é realmente apenas uma linha desenhada na altitude acima do solo. A tag <tessellate> divide a linha em pedaços menores e a tag <extrude> estende a linha até o solo.

Polígonos

É possível usar polígonos para criar edifícios simples e outras formas. Confira a pasta "Polígonos" no arquivo Amostras de KML para ver exemplos.

O exemplo de Pentágono é gerado desenhando formas internas e externas simples e forçando-as até o solo. Veja o código:

<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://www.opengis.net/kml/2.2"> <Placemark>
 <name>The Pentagon</name>
 <Polygon>
 <extrude>1</extrude>
 <altitudeMode>relativeToGround</altitudeMode>
 <outerBoundaryIs>
 <LinearRing>
 <coordinates>
 -77.05788457660967,38.87253259892824,100 
 -77.05465973756702,38.87291016281703,100 
 -77.05315536854791,38.87053267794386,100 
 -77.05552622493516,38.868757801256,100 
 -77.05844056290393,38.86996206506943,100 
 -77.05788457660967,38.87253259892824,100
 </coordinates>
 </LinearRing>
 </outerBoundaryIs>
 <innerBoundaryIs>
 <LinearRing>
 <coordinates>
 -77.05668055019126,38.87154239798456,100 
 -77.05542625960818,38.87167890344077,100 
 -77.05485125901024,38.87076535397792,100 
 -77.05577677433152,38.87008686581446,100 
 -77.05691162017543,38.87054446963351,100 
 -77.05668055019126,38.87154239798456,100
 </coordinates>
 </LinearRing>
 </innerBoundaryIs>
 </Polygon>
 </Placemark> </kml>

2 Documentos KML avançados

Esta seção descreve alguns dos elementos KML que devem ser criados usando um editor de texto, como estilos compartilhados para geometria, ícones destacados para marcadores e superposições de tela. O processo de criação de KML "manualmente" é um pouco mais avançado que o uso da interface do Google Earth para criar e modificar elementos, mas com um pouco de prática a maioria dos usuários se sente confortável para editar arquivos KML e adicionar esses efeitos.

Estilos para geometria

Depois de criar elementos no Google Earth e examinar o código KML gerado pelo Google Earth, você perceberá como os estilos são uma parte importante da forma como seus dados são exibidos. Usuários avançados aprenderão a definir seus próprios estilos.

Se você definir um estilo no início de um documento KML e também definir um código para ele, poderá usar esse estilo em Geometria, Marcadores e Superposições definidos em outras partes do documento. Como mais de um elemento pode usar o mesmo estilo, os estilos definidos e usados dessa maneira são chamados de estilos compartilhados. Você define determinado estilo uma vez, e depois poderá fazer referência a ele várias vezes, usando o elemento <styleUrl>. Se a definição de estilo estiver dentro do mesmo arquivo, coloque um sinal de # antes do código de estilo. Se a definição de estilo estiver em um arquivo externo, inclua o URL completo no elemento <styleUrl>.

O arquivo Amostras de KML contém diversos estilos compartilhados, cada um definido com um código no início do arquivo. É mais fácil se seus códigos forem strings descritivas para que você possa saber facilmente qual é seu efeito. Veja um exemplo de estilo ("transBluePoly") que define uma cor azul transparente para as faces do polígono e uma largura de linha de 1,5 (e a cor padrão branca) para as bordas do polígono. Esse estilo é usado pelo Edifício 41 no exemplo do Campus do Google (na pasta "Polígonos"):

<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://www.opengis.net/kml/2.2">
 <Document>
 <Style id="transBluePoly">
 <LineStyle>
 <width>1.5</width>
 </LineStyle>
 <PolyStyle>
 <color>7dff0000</color>
 </PolyStyle>
 </Style> <Placemark>
 <name>Building 41</name>
 <styleUrl>#transBluePoly</styleUrl>
 <Polygon>
 <extrude>1</extrude>
 <altitudeMode>relativeToGround</altitudeMode>
 <outerBoundaryIs>
 <LinearRing>
 <coordinates> -122.0857412771483,37.42227033155257,17
 -122.0858169768481,37.42231408832346,17
 -122.085852582875,37.42230337469744,17
 -122.0858799945639,37.42225686138789,17
 -122.0858860101409,37.4222311076138,17
 -122.0858069157288,37.42220250173855,17
 -122.0858379542653,37.42214027058678,17
 -122.0856732640519,37.42208690214408,17
 -122.0856022926407,37.42214885429042,17
 -122.0855902778436,37.422128290487,17
 -122.0855841672237,37.42208171967246,17
 -122.0854852065741,37.42210455874995,17
 -122.0855067264352,37.42214267949824,17
 -122.0854430712915,37.42212783846172,17
 -122.0850990714904,37.42251282407603,17
 -122.0856769818632,37.42281815323651,17
 -122.0860162273783,37.42244918858722,17
 -122.0857260327004,37.42229239604253,17
 -122.0857412771483,37.42227033155257,17 </coordinates>
 </LinearRing>
 </outerBoundaryIs>
 </Polygon>
 </Placemark>
 </Document>
</kml>

O elemento <Style> é filho de <Placemark> (não da geometria que ele afeta).

Estilos para ícones destacados

O "Ícone destacado" na pasta "Estilos e marcação" mostra como criar um efeito de passagem do mouse com KML. O documento define dois estilos: um para "normalPlacemark" e outro para "highlightPlacemark" (exibido quando o cursor passa sobre o ícone). O elemento <StyleMap> tem dois pares de chave/valor que mapeiam cada estilo de ícone para um estado de ícone. Há dois estados de ícone: normal e highlight.

As etapas básicas mostradas aqui são as seguintes:

Defina um <Style> para o ícone normal do marcador e atribua um código a ele (aqui, "normal Placemark"). O <Style> inclui um <Icon> com um <href> para a imagem real a ser usada, como mostrado abaixo.
Defina um <Style> para o ícone de destaque do marcador e atribua um código a ele (aqui, "highlightPlacemark").
Crie o elemento <StyleMap> e atribua um código a ele (aqui, "exampleStyleMap"). O marcador fará referência a esse código.
No elemento <StyleMap>, especifique "#normalPlacemark" para o estado normal.
No elemento <StyleMap>, especifique "#highlightPlacemark" para o estado destacado.
No marcador, adicione um elemento <styleUrl> que faz referência a "#exampleStyleMap".

<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://www.opengis.net/kml/2.2">
 <Document>
 <name>Highlighted Icon</name>
 <description>Place your mouse over the icon to see it display the new icon</description>
 <Style id="highlightPlacemark">
 <IconStyle>
 <Icon>
 <href>http://maps.google.com/mapfiles/kml/paddle/red-stars.png</href>
 </Icon>
 </IconStyle>
 </Style>
 <Style id="normalPlacemark">
 <IconStyle>
 <Icon>
 <href>http://maps.google.com/mapfiles/kml/paddle/wht-blank.png</href>
 </Icon>
 </IconStyle>
 </Style>
 <StyleMap id="exampleStyleMap">
 <Pair>
 <key>normal</key>
 <styleUrl>#normalPlacemark</styleUrl>
 </Pair>
 <Pair>
 <key>highlight</key>
 <styleUrl>#highlightPlacemark</styleUrl>
 </Pair>
 </StyleMap>
 <Placemark>
 <name>Roll over this icon</name>
 <styleUrl>#exampleStyleMap</styleUrl>
 <Point>
 <coordinates>-122.0856545755255,37.42243077405461,0</coordinates>
 </Point>
 </Placemark>
 </Document>
</kml>

Superposições de tela

Superposições de tela não podem ser criadas diretamente no Google Earth e são mais difíceis de criar que superposições de solo. Um conjunto abrangente de amostras está incluído na pasta "Superposições de tela" no arquivo Amostras de KML.

Como exemplo, ative a pasta "Absolute Positioning: Top left" no arquivo Amostras de KML e você verá uma superposição de tela no lado superior esquerdo da janela de visualização. Ele foi criado com o seguinte código KML:

<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://www.opengis.net/kml/2.2">
 <ScreenOverlay>
 <name>Absolute Positioning: Top left</name>
 <Icon>
 <href>http://developers.google.com/kml/documentation/images/top_left.jpg</href>
 </Icon>
 <overlayXY x="0" y="1" xunits="fraction" yunits="fraction"/>
 <screenXY x="0" y="1" xunits="fraction" yunits="fraction"/>
 <rotationXY x="0" y="0" xunits="fraction" yunits="fraction"/>
 <size x="0" y="0" xunits="fraction" yunits="fraction"/>
 </ScreenOverlay>
</kml>

O posicionamento é controlado pelo mapeamento de um ponto na imagem especificada por <overlayXY> para um ponto na tela especificada por <screenXY>. Nesse caso, o canto superior esquerdo da imagem (0,1) foi feito coincidente com o mesmo ponto na tela.

Confira os outros exemplos na pasta para ver como é possível obter outras posições fixas e para criar imagens que ficam dimensionadas dinamicamente com o tamanho da tela. xunits e yunits também podem ser especificados como "pixels" para controle de precisão. Para obter mais detalhes, consulte a Referência de KML 2.2.

Links de rede

Um link de rede contém um elemento <Link> com um <href> (uma referência de hipertexto) que carrega um arquivo. O <href> pode ser uma especificação de arquivo local ou um URL absoluto. Apesar do nome, um <NetworkLink> não carrega necessariamente arquivos da rede.

O <href> em um link especifica a localização de qualquer um dos seguintes itens:

Um arquivo de imagem usado por ícones em estilos de ícone, superposições de solo e superposições de tela
Um arquivo de modelo usado no elemento <Model>
Um arquivo KML ou KMZ carregado por um link de rede

O arquivo especificado pode ser um arquivo local ou um arquivo em um servidor remoto. Em sua forma mais simples, os links de rede são uma maneira útil de dividir um arquivo KML grande em arquivos menores e mais facilmente gerenciáveis no mesmo computador.

Até o momento, todos os nossos exemplos exigiram que o código KML fosse entregue ao Google Earth a partir da máquina local. Os links de rede permitem fornecer conteúdo a partir de um local remoto e são usados normalmente para distribuir dados para uma grande quantidade de usuários. Dessa forma, se for necessário corrigir os dados, eles deverão ser alterados apenas no local de origem, e todos os usuários receberão os dados atualizados automaticamente.

Scripts CGI para KML

Além de apontar para arquivos que contêm dados estáticos, o <href> de um link de rede pode apontar para dados gerados dinamicamente, por exemplo, por um script CGI localizado em um servidor de rede. Com algum conhecimento de uma linguagem de script, como PHP, Python ou Perl, é possível criar um script que forneça um fluxo (ou arquivo) de dados KML para cada link de rede.

Duas coisas são necessárias para fornecer KML por meio de um CGI de rede:

Quando uma chamada é feita no cliente (Google Earth) para o servidor, o servidor precisa (1) retornar um código de resposta de HTTP 200 e (2) definir o tipo de conteúdo da resposta como text/plain ou application/vnd.google-earth.kml+xml.

A resposta deve ser um KML válido. Para aplicativos complexos, a manipulação adequada de erros é muito importante.

Dica: uma maneira simples de lidar com erros é analisar o erro do servidor como o texto para o nome de uma pasta. Por exemplo, é possível fazer com que o servidor retorne <Folder><name>database inaccessible</name></Folder> como uma string. Isso é mais informativo (e mais simples) que deixar a conexão cair.

Os exemplos a seguir usam Python, mas são igualmente válidos em qualquer outra linguagem de script.

Como gerar um marcador aleatório

O script Python a seguir gera valores inteiros aleatórios para latitude e longitude e insere esses valores no elemento <coordinates> de um <Point>. Sempre que o link de rede é atualizado, o script Python é executado novamente e gera KML com novos valores de latitude e longitude.

#!/usr/bin/python


import random

latitude = random.randrange(-90, 90)
longitude = random.randrange(-180, 180)
kml = (
   '<?xml version="1.0" encoding="UTF-8"?>\n'
   '<kml xmlns="http://www.opengis.net/kml/2.2">\n'
   '<Placemark>\n'
   '<name>Random Placemark</name>\n'
   '<Point>\n'
   '<coordinates>%d,%d</coordinates>\n'
   '</Point>\n'
   '</Placemark>\n'
   '</kml>'
   ) %(longitude, latitude)
print 'Content-Type: application/vnd.google-earth.kml+xml\n'
print kml

Veja um exemplo de arquivo KML contendo um link de rede que carrega esse script Python:

<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://www.opengis.net/kml/2.2">
 <Folder>
 <name>Network Links</name>
 <visibility>0</visibility>
 <open>0</open>
 <description>Network link example 1</description>
 <NetworkLink>
 <name>Random Placemark</name>
 <visibility>0</visibility>
 <open>0</open>
 <description>A simple server-side script that generates a new random
 placemark on each call</description>
 <refreshVisibility>0</refreshVisibility>
 <flyToView>0</flyToView>
 <Link>
 <href>http://yourserver.com/cgi-bin/randomPlacemark.py</href>
 </Link>
 </NetworkLink>
 </Folder>
</kml>

Consultas de atualização baseadas em visualização

Um link de rede padrão é um link unidirecional: os dados fluem somente do servidor para o Google Earth. A atualização baseada em visualização permite comunicação bidirecional. Quando a atualização baseada em visualização está ativa, o Google Earth retorna as coordenadas da visualização para o servidor em um período especificado. Isso pode ocorrer a cada n segundos, minutos ou horas ou assim que determinado período de tempo passar depois que a visualização parar de se mover. Consulte <viewRefreshMode>, na Referência de KML 2.2.

As coordenadas retornam ao servidor por meio de um HTTP GET que anexa as coordenadas da seguinte forma (essas são as informações da caixa delimitadora padrão):

GET /path/to/sever/script/query?BBOX=[longitude_west, latitude_south, longitude_east, latitude_north] HTTP/1.1

Se a solicitação tiver sido feita enquanto o usuário estava olhando para San Francisco, as coordenadas terão a seguinte aparência:

GET /path/to/server/script/query?BBOX=-122.497790,37.730385,-122.380087,37.812331 HTTP/1.1

Esse elemento pode ser usado para alguns aplicativos muito criativos, mas, para começar, um exemplo simples é apresentado abaixo.

Como controlar um ponto diretamente na sua visualização

O seguinte script Python do lado do servidor analisa a mensagem de retorno enviada pelo Google Earth e responde com um marcador no centro da tela. Sempre que o link de rede é atualizado, um novo marcador é gerado.

#!/usr/bin/python


import cgi

url = cgi.FieldStorage()
bbox = url['BBOX'].value
bbox = bbox.split(',')
west = float(bbox[0])
south = float(bbox[1])
east = float(bbox[2])
north = float(bbox[3])

center_lng = ((east - west) / 2) + west
center_lat = ((north - south) / 2) + south

kml = ( 
   '<?xml version="1.0" encoding="UTF-8"?>\n'
   '<kml xmlns="http://www.opengis.net/kml/2.2">\n'
   '<Placemark>\n'
   '<name>View-centered placemark</name>\n'
   '<Point>\n'
   '<coordinates>%.6f,%.6f</coordinates>\n'
   '</Point>\n'
   '</Placemark>\n'
   '</kml>'
   ) %(center_lng, center_lat)

print 'Content-Type: application/vnd.google-earth.kml+xml\n'
print kml

E este é o KML para o link de rede que carrega o script Python:

<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://www.opengis.net/kml/2.2">
 <Folder>
 <name>Network Links</name>
 <visibility>0</visibility>
 <open>0</open>
 <description>Network link example 2</description>
 <NetworkLink>
 <name>View Centered Placemark</name>
 <visibility>0</visibility>
 <open>0</open>
 <description>The view-based refresh allows the remote server to calculate
 the center of your screen and return a placemark.</description>
 <refreshVisibility>0</refreshVisibility>
 <flyToView>0</flyToView>
 <Link>
 <href>http://yourserver.com/cgi-bin/viewCenteredPlacemark.py</href>
 <refreshInterval>2</refreshInterval>
 <viewRefreshMode>onStop</viewRefreshMode>
 <viewRefreshTime>1</viewRefreshTime>
 </Link>
 </NetworkLink>
 </Folder>
</kml>

O princípio ilustrado neste exemplo pode ser usado para alguns aplicativos muito complexos. Por exemplo, se você tiver um banco de dados de informações geográficas, poderá extrair as coordenadas do visualizador, fazer uma chamada para o banco de dados para obter dados específicos da visualização e retorná-lo ao Google Earth como KML.

3 Tipos KML MIME

Ao responder a uma solicitação do Google Earth (ou qualquer navegador da Terra), um servidor KML deve seguir determinado conjunto de regras para que o Google Earth possa interpretar corretamente suas respostas.

Após a conclusão, o servidor deve retornar um código de resposta de HTTP 200 e definir o tipo de conteúdo da resposta como um tipo MIME apropriado, conforme descrito aqui.

O Google Earth lê arquivos KML e KMZ. O tipo MIME para arquivos KML é

application/vnd.google-earth.kml+xml

O tipo MIME para arquivos KMZ é

application/vnd.google-earth.kmz

Para Apache, adicione estas linhas ao arquivo httpd.conf:

AddType application/vnd.google-earth.kml+xml .kml
AddType application/vnd.google-earth.kmz .kmz

Consulte a documentação da Microsoft para obter detalhes sobre como configurar tipos MIME no IIS da Microsoft.

O corpo da resposta deve conter dados KML válidos, incluindo a declaração XML (<?xml version="1.0" encoding="UTF-8"?>). Se o servidor retornar um KML inválido, o link de rede será interrompido, desativado e mostrará uma mensagem de erro.

Próximos passos

Pronto para mais? Confira o Guia do desenvolvedor, que descreve os principais elementos de KML. Além disso, navegue na Referência de KML para obter informações sobre elementos específicos.