Em nossa receita de geocoding, você aprendeu a usar fórmulas do Google Sheets para converter automaticamente os nomes de locais em coordenadas em dados de sua planilha. Neste artigo, você vai aprender a levar a geocoding um passo adiante, convertendo coordenadas em limites GeoJSON – descrições legíveis por máquina dos limites das regiões geográficas, como países ou províncias usando a API Koordinates. A API Koordinates pega coordenadas de latitude e longitude e retorna marcações de fronteira que estão nas coordenadas ou perto delas.

Na receita de geocoding, você usou funções embutidas como ImportXML, CONCATENATE e JOIN para obter as coordenadas de nomes de lugares através de fórmulas como esta:

=JOIN(",", ImportXML(CONCATENATE("http://open.mapquestapi.com/nominatim/v1/search?format=xml&q=",A2), "//place[1]/@lat | //place[1]/@lon"))

Essa fórmula é possível porque a API MapQuest utilizado nesse artigo retorna dados XML, que você pode consultar usando strings XPath como / //place[1]/@lat com a função embutida ImportXML.

Mas Koordinates, a API de dados geoespaciais que estamos usando neste artigo, retorna os resultados em JSON em vez de em XML, e o Google Docs não tem nenhuma das funções embutidas para atravessar objetos JSON. Por isso nós vamos ter que definir o nosso próprio.

Para começar, você precisa criar uma conta com Koordinates e obter uma chave de API. Para criar uma chave, faça o login, clique no seu nome na parte superior da página, selecione APIs e Web Services e, em seguida, clique em Aceitar termos e criar chave. Faça uma cópia da chave que é gerada, pois você poderá usá-la em breve.

Agora vá para sua planilha, acesse o menu Ferramentas e selecione editor Script. Clique em Fechar para se livrar da caixa de diálogo que aparece. Assim que estiver no editor de script , exclua o texto da caixa de edição e salve o arquivo, dando-lhe um nome memorável (talvez Koordinates API function).

Agora digite o seguinte na caixa de edição vazia, inserindo sua chave API no local indicado:

function koords (coordsString) {
 /* Block 1. Formats lat-long coordinates for Koordinates API call. */ 
 coordsString = coordsString.replace(/\s/, "") ;
 var coords = coordsString.split(",") ;
 var xy = "&x=" + coords[1] + "&y=" + coords[0] ;

 /* Block 2. Formats API call, makes API call, parses the result, 
    and stores the resulting object in "json". */
 var key = "YOUR API KEY GOES HERE, INSIDE THESE QUOTATION MARKS" ; 
 var url = "http://api.koordinates.com/api/vectorQuery.json/?key=" + key + "&layer=1103&geometry=true" ; 
 var data = UrlFetchApp.fetch(url + xy) ;
 var text = data.getContentText() ;
 var json = JSON.parse(text) ;

 /* Block 3. Traverses "json" to find boundary data and returns it. */ var result = json["vectorQuery"]["layers"]["1103"]["features"][0]["geometry"] ; return JSON.stringify(result) ; 

} ;

Vamos passar bloco por bloco desse código.

O primeiro bloco de código converte uma representação de strings de latitude-longitude para o formato que o Koordinates espera, com a longitude em primeiro lugar. Ele joga fora todos os espaços na string (replace), divide a string no caractere “,” e cola novamente na ordem inversa. Ele também o recebe configurado para ser inserido na chamada API Koordinates, colocando o valor de longitude após “&y=” e a longitude depois de “&x=” .

O próximo bloco configura a URL para a chamada de API e, em seguida, faz a chamada. Ele pede uma camada do mapa 1103, que é uma camada para os limites do país. Também solicita “geometria”, que significa polígonos reais (em vez de apenas metadados, o padrão). A string JSON resultante é analisada em um objeto JavaScript com JSON.parse e colocada na variável jason.

O JSON retornado pela API se parece com isto:

O polígono de conteúdo que queremos, a “geometry”, está enterrada afastada e profundamente dentro do objeto. Para chegar a ela, é preciso cavar através de várias camadas de atributos. Isso é o que o último bloco de código faz, pegando a “geometry” no primeiro item (número do item 0) na lista de “features” de objetos de mapa voltada para a consulta. Ele também transforma o resultado em uma string com JSON.stringify e retorna como o valor da função.

Tente chamar a sua nova função personalizada, dando-lhe o nome de uma célula que contém coordenadas latitude-longitude (aqui, F4):

=koords(F4)

Você deve receber em troca uma blob de dados JSON – a rica representação geométrica do país que contém o ponto em F4.

Agora você pode usar koords como uma função comum do Google Apps. Por exemplo, você pode empacotar a fórmula da lição anterior para criar uma nova fórmula que vai direto a partir de nomes de lugares aos limites GeoJSON .

=koords(JOIN(",", ImportXML(CONCATENATE("http://open.mapquestapi.com/nominatim/v1/search?format=xml&q=",A2), "//place[1]/@lat | //place[1]/@lon")))

Neste exemplo, usamos a camada de mapa 1103, que contém os limites do país. Mas Koordinates tem muitas outras camadas que você pode achar útil. Confira a lista de camadas para ver o que mais você pode fazer com a API Koordinates.

***

Artigo escrito por Neil Ashton, linguista computacional e editor do blog School of Data. Publicado originalmente no portal Escola de Dados – http://schoolofdata.org/2013/10/31/geocoding-geojson-boundaries-koordinates/