Converter KML para CSV

O KML foi feito para desenhar num globo. Um arquivo de marcadores carrega muito mais do que posições — um estilo para cada ícone, uma descrição em HTML, uma árvore de pastas que os agrupa. Mas boa parte dos arquivos KML em circulação são na verdade uma lista disfarçada de mapa: quarenta endereços de filiais, um conjunto de pontos de pesquisa, os lugares que alguém marcou no Google Earth ao longo de um ano.

Para esse arquivo, um CSV é o recipiente mais honesto. Cada marcador vira uma linha de nome e coordenadas, que é o que um geocodificador, um otimizador de rota ou uma importação de CRM realmente consome. Tudo que fazia dele um desenho fica para trás, e essa é uma perda deliberada, não uma limitação: uma coluna para a URL de um ícone não ajudaria ninguém.

O KML escreve uma coordenada como `longitude,latitude,altitude`, numa única sequência de texto. Quase todo outro formato dessa família nomeia latitude primeiro, e essa inversão é o jeito mais comum de uma conversão de KML dar errado: o par é transposto, então São Paulo em -46,6 e -23,5 sai como -23,5 e -46,6 e cai no meio do oceano.

A conversão inverte a ordem, então as colunas do CSV são `latitude` e depois `longitude`. Vale conferir em vez de simplesmente confiar, e a checagem leva um segundo: para qualquer ponto no Brasil, a latitude fica entre aproximadamente -34 e 5, e a longitude entre -74 e -34 — se a primeira coluna de coordenada estiver fora dessa faixa e a segunda dentro, algo trocou a ordem antes.

Um KML se aninha. Um documento contém pastas, que contêm mais pastas e, por fim, os marcadores que carregam a geometria. O leitor percorre essa árvore inteira em vez de olhar só o primeiro nível, porque um KML exportado de uma ferramenta de mapas costuma colocar seus marcadores três níveis abaixo.

O que essa varredura não faz é preservar a estrutura de pastas. Um marcador dentro de `Locais / Fase 2 / Confirmados` sai como uma linha indistinguível de uma no nível superior, porque o CSV tem uma única coluna de nome e ela pertence ao marcador. Se o agrupamento é a informação, ele precisa estar codificado nos nomes dos marcadores antes de converter.

Um marcador com um ponto vira uma linha do tipo `waypoint`. Um marcador com uma linha vira uma sequência de linhas do tipo `track`, uma por vértice, todas compartilhando o nome do marcador. Esses dois casos cobrem a grande maioria do KML em circulação e ambos atravessam com os nomes intactos.

Duas coisas não produzem nada, e vale saber disso antes de converter. Um polígono — uma região sombreada, um limite de propriedade — guarda o contorno dentro de elementos aninhados que este leitor não percorre, então uma área não contribui com linha nenhuma. Um KML feito inteiramente de áreas falha com a mensagem de que nenhuma trilha ou marcador foi encontrado, o que é preciso e não é um problema do arquivo.

Uma linha simples é uma forma sem noção de quando. Se o KML veio de uma exportação de GPS em vez de um desenho, ele pode carregar em vez disso a extensão do Google que guarda listas paralelas de horários e posições. O leitor trata isso como um caso distinto, e os horários caem na coluna `time`.

O sinal de que você tem um desses é a coluna `time` estar preenchida. Se toda célula ali estiver vazia, a origem tinha linhas simples, e nenhum conversor consegue recuperar horários que um arquivo nunca guardou.

O terceiro valor numa coordenada KML é altitude em metros, e a conversão escreve isso na coluna `elevation` quando presente. O que ela não faz é consultar o elemento irmão que diz como a altitude deve ser interpretada — fixada ao solo, relativa a ele, ou absoluta.

Isso importa porque o padrão do Google Earth é fixar ao solo, modo em que o valor de altitude é ignorado inteiramente e frequentemente é escrito como zero. Então um KML desenhado à mão sobre terreno acidentado tende a produzir uma coluna de elevação cheia de zeros que significam "na superfície", não "ao nível do mar". Trate uma coluna de zeros como ausente, não como dado.

A saída coloca toda linha `waypoint` antes de toda linha `track`, independente da ordem em que apareceram no documento. É uma conveniência para o caso comum: um KML de marcadores converte para um arquivo cujas linhas são todas waypoints, e um KML misto com marcadores e uma rota desenhada entrega os marcadores no topo.

O custo é que a ordem do documento não é preservada entre os dois tipos. Se a sequência das feições no KML carregava significado, essa ordenação precisa vir dos nomes dos marcadores ou da coluna `time`, não do número da linha. Dentro de cada tipo, a ordem original é mantida exatamente.

Nomes de marcador são o campo mais propenso a quebrar um CSV ingênuo, porque são texto livre escrito por uma pessoa. `Depósito 3, Entrada dos Fundos` contém o delimitador. O escritor coloca entre aspas qualquer valor contendo vírgula, aspas ou quebra de linha, e duplica aspas internas, exatamente como o padrão RFC 4180 pede.

Coordenadas nunca precisam de aspas, então o arquivo continua legível num editor de texto. Se você estiver conferindo a saída visualmente, os nomes entre aspas são as linhas que vale a pena olhar.

O KML define um elemento de endereço num marcador, e o Google Earth preenche isso quando um marcador foi criado buscando um lugar em vez de clicando no globo. Isso não é lido aqui, então a saída carrega nome e coordenadas e nada parecido com um endereço postal mesmo onde o documento de origem tinha um.

Para a maioria dos destinos isso não é uma perda, porque uma latitude e longitude é uma chave mais forte que uma linha de endereço, e todo serviço de rota e geocodificação aceita isso diretamente. Onde um endereço é realmente necessário, ele precisa vir de uma etapa de geocodificação reversa sobre as coordenadas.

A conversão roda inteiramente nesta aba do navegador — o KML é lido, percorrido e reescrito localmente, e nenhuma requisição carrega ele para lugar nenhum. Não existe conta, fila ou política de retenção para ler, porque não há nada num servidor para reter.

O motivo de se importar é o que uma lista de marcadores costuma ser. Um KML de pontos frequentemente é uma lista de clientes, um conjunto de endereços de entrega ou a localização de ativos que alguém prefere não publicar. Converter para CSV torna isso mais portátil e mais legível ao mesmo tempo, então a saída merece o mesmo cuidado que a planilha da qual ela vai fazer parte.