Visualizador de mapa JSON: mostre coordenadas de um JSON no mapa

O que este visualizador faz

Muitos dados de localização nunca chegam como arquivo GIS. Eles chegam como JSON comum: a resposta de uma API de clima, uma lista de lojas de um localizador, uma exportação de um app de entregas ou um arquivo que um desenvolvedor manda para você. Cada registro tem uma latitude e uma longitude em algum lugar, mas uma ferramenta de mapas que espera GeoJSON não consegue lê-lo, e abrir o arquivo em uma planilha perde a estrutura aninhada.

Este visualizador lê esse JSON do jeito que ele é. Ele percorre o documento inteiro procurando listas de registros, transforma objetos aninhados em nomes de campo como `location.lat` e reconhece os nomes comuns de latitude e longitude, além de campos únicos que guardam os dois valores, como arrays `[lng, lat]` ou textos `"lat, lng"`. Cada registro com coordenadas válidas aparece no mapa. A barra lateral mostra quantos registros não tinham coordenadas ou tinham valores fora do intervalo válido, e avisa quando latitude e longitude parecem trocadas.

Criei este visualizador para aquele momento em que alguém manda um JSON e pergunta "onde ficam estes lugares?". Você confere os dados em segundos, colore os pontos por qualquer campo, clica em um ponto para ler o registro completo e baixa o resultado como GeoJSON para um GIS ou como CSV para uma planilha. O arquivo é lido no seu navegador e nunca é enviado.

Formatos de JSON que o visualizador entende

O JSON real tem muitos formatos. Estes são os que o visualizador lê sem nenhuma configuração. Em cada caso ele mostra a lista de registros que encontrou, e você pode escolher outra se o arquivo tiver várias.

[{ "name": "Berlin", "lat": 52.52, "lng": 13.405 }]

{ "data": { "cities": [{ "name": "Paris", "latitude": 48.8566, "longitude": 2.3522 }] } }

[{ "name": "Rome", "location": { "lat": 41.9028, "lon": 12.4964 } }]

[{ "id": 7, "coordinates": [2.1686, 41.3874] }]

[{ "stop": "Central", "latlng": "59.3293, 18.0686" }]

{ "BER": { "lat": 52.52, "lng": 13.405 }, "PAR": { "lat": 48.86, "lng": 2.35 } }

{"lat": 38.72, "lng": -9.14}
{"lat": 41.16, "lng": -8.63}

Números guardados como texto, como "52.52", e números com vírgula decimal, como "52,52", também são lidos. Arrays dentro de um registro, como uma lista de etiquetas, ficam como texto JSON na janela de informação e na exportação.

Quais nomes de campo são reconhecidos

O visualizador compara a última parte de cada nome de campo, então `lat`, `location.lat` e `data.geo.lat` contam todos. Maiúsculas e minúsculas não importam. Se nada combinar, você escolhe os campos no painel Coordinates.

Latitude

lat, latitude, lat_dd, y, ycoord, point_y, decimalLatitude, gps_lat, geo_lat e formas parecidas.

Longitude

lng, lon, long, longitude, lon_dd, x, xcoord, point_x, decimalLongitude, gps_lon, geo_lng e formas parecidas.

Um campo com os dois

Nomes que terminam em coordinates, coords, position, latlng, lnglat, location, geo, point, center ou gps, quando o valor é um array de dois números ou um texto "a, b".

Escolha entre candidatos

Cada par possível de latitude e longitude é testado nos primeiros 300 registros. Vence o par com mais valores dentro de ±90 e ±180, um par com o mesmo objeto pai ganha um bônus, e x/y perdem os empates para nomes lat/lng de verdade.

Ordem de um par

lnglat, lonlat e coordinates significam longitude primeiro. latlng e latlon significam latitude primeiro. Para outros nomes, vence a ordem com mais valores válidos. Se as duas servirem, arrays são lidos como [lng, lat] e textos como "lat, lng".

Detalhes técnicos

Isto é exatamente o que o visualizador aceita e produz.

Entrada

Arquivos .json, .jsonl e .ndjson de até 50 MB, ou JSON colado na caixa Paste JSON.

Não é para GeoJSON nem TopoJSON

Se o arquivo já for GeoJSON ("type": "FeatureCollection") ou TopoJSON ("type": "Topology"), aparece uma mensagem que indica o Visualizador de GeoJSON ou o Visualizador de TopoJSON deste site.

Listas de registros

Arrays em que pelo menos metade dos itens são objetos, em qualquer profundidade até 8 níveis, e objetos cujos valores são todos registros. As listas com coordenadas aparecem primeiro, depois as maiores.

Coordenadas válidas

Latitude entre −90 e 90, longitude entre −180 e 180, em graus decimais (WGS84). Registros fora desses intervalos são contados e não aparecem no mapa.

Aviso de troca

Se um registro está fora do intervalo, mas seria válido com latitude e longitude trocadas, o visualizador o conta e oferece um botão Swap.

Colorir por campo

Qualquer campo com até 10 valores diferentes pode colorir os pontos, com legenda e contagem por valor.

Desempenho

Os pontos são desenhados em um canvas, então dezenas de milhares de registros continuam fluidos em um notebook comum.

Exportação

GeoJSON com cada campo como propriedade, ou CSV com latitude e longitude como as duas primeiras colunas e os campos achatados depois.

Privacidade

O arquivo é lido no seu navegador. Só os blocos do mapa base vêm da internet.

Como colocar JSON em um mapa, passo a passo

Este é o fluxo completo com o exemplo incluído: 25 cidades europeias dentro de uma resposta aninhada no estilo de uma API, com as coordenadas em um objeto `location` e um registro sem localização.

1

Passo 1: Abra o visualizador

O mapa abre com um mapa base de ruas. Use Upload, Paste JSON ou arraste um arquivo para o mapa. Aqui eu cliquei em Sample Data.

2

Passo 2: Confira o que foi encontrado

O painel Records mostra a lista escolhida (`data.cities`), quantos registros estão no mapa e quantos não tinham coordenadas. No exemplo, um registro tem `"location": null`, então aparecem 24 de 25.

3

Passo 3: Confirme os campos de coordenadas

O painel Coordinates mostra os campos detectados, aqui `location.lat` e `location.lng`. Mude para "One field" para dados com um único campo `[lng, lat]` ou `"lat, lng"`, e use Swap se os pontos caírem no lugar errado.

4

Passo 4: Colora os pontos por um campo

Escolha um campo em "Color by field". Aqui `capital` separa as capitais das outras cidades, com legenda e contagem para cada valor.

5

Passo 5: Leia um registro

Clique em qualquer ponto para ver as coordenadas exatas e todos os campos do registro, incluindo valores aninhados e arrays.

6

Passo 6: Exporte

Baixe os pontos como GeoJSON para QGIS, ArcGIS ou um mapa web, ou como CSV para Excel e Planilhas Google.

Outras formas de levar dados JSON para um mapa

Este visualizador é o jeito mais rápido de olhar um arquivo JSON. Quando você precisa da mesma tarefa dentro de um fluxo de trabalho, estas são as ferramentas que eu uso.

A mesma tarefa em código

Os três exemplos leem o arquivo de exemplo usado acima, pulam o registro sem localização e mantêm os outros campos.

# Python: pandas flattens nested JSON, GeoPandas builds the points
import json
import pandas as pd
import geopandas as gpd

with open("cities.json") as f:
    data = json.load(f)

df = pd.json_normalize(data["data"]["cities"])   # columns: location.lat, location.lng
df = df.dropna(subset=["location.lat", "location.lng"])
gdf = gpd.GeoDataFrame(
    df, geometry=gpd.points_from_xy(df["location.lng"], df["location.lat"]), crs="EPSG:4326"
)
gdf.to_file("cities.geojson", driver="GeoJSON")

# jq on the command line: JSON records to a GeoJSON FeatureCollection
jq '{type: "FeatureCollection", features: [
      .data.cities[] | select(.location != null) | {
        type: "Feature",
        properties: del(.location),
        geometry: { type: "Point", coordinates: [.location.lng, .location.lat] }
      }]}' cities.json > cities.geojson

// JavaScript + Leaflet: note the order, Leaflet wants [lat, lng]
const res = await fetch("cities.json");
const json = await res.json();
for (const c of json.data.cities) {
  if (!c.location) continue;
  L.marker([c.location.lat, c.location.lng]).bindPopup(c.name).addTo(map);
}

Minha opinião: use este visualizador para entender um JSON novo e conferir suas coordenadas. Depois que você conhece a estrutura, poucas linhas de Python ou jq transformam o arquivo em GeoJSON sempre que os dados mudarem.

Como o visualizador funciona

Isto é o que acontece entre soltar um arquivo e ver os pontos. Cada passo roda no seu navegador.

1. Analisar o texto. O texto é analisado como JSON. Se isso falhar e o arquivo tiver várias linhas, cada linha é analisada como JSON Lines. Uma marca de ordem de bytes no início é removida.
2. Recusar arquivos que têm seu próprio visualizador. GeoJSON e TopoJSON são reconhecidos pelo type e enviados ao visualizador certo deste site, porque já contêm geometria de verdade.
3. Encontrar as listas de registros. O visualizador percorre o documento até 8 níveis de profundidade e reúne cada array formado principalmente por objetos, e cada objeto cujos valores são todos registros. Cada registro é achatado em caminhos com ponto.
4. Detectar as coordenadas. Os nomes de campo são comparados com as listas acima. Cada par candidato é testado em até 300 registros, e vence o par com mais valores válidos. Se nenhum par servir, campos únicos com dois números são testados.
5. Montar os pontos. Cada registro é lido com os campos escolhidos. Números em texto são convertidos, valores fora de ±90 / ±180 são contados e pulados, e registros que serviriam se trocados são contados à parte.
6. Desenhar, colorir e exportar. Os pontos são desenhados em uma camada canvas e o mapa dá zoom neles. Mudar um campo, a ordem ou a cor redesenha o mapa na hora. As exportações usam exatamente os registros que você vê.

A detecção é só uma primeira sugestão. Cada escolha pode ser mudada na barra lateral, e o mapa atualiza assim que você muda, então uma sugestão errada custa um clique.

Conferindo coordenadas: intervalos, trocas e precisão

Um par de latitude e longitude são só dois números. Estas três verificações dizem se os números fazem sentido.

válido  ⇔  −90 ≤ latitude ≤ 90   e   −180 ≤ longitude ≤ 180

latitude 91.2, longitude 10.5   →  inválido (latitude grande demais)

guardado:  lat = 151.21,  lng = −33.87   →  inválido
trocado:   lat = −33.87,  lng = 151.21   →  válido (Sydney)

1° latitude  ≈ 111 320 m
1° longitude ≈ 111 320 m · cos(latitude)

casas   passo em latitude   passo em longitude em Berlim (52.52°)
1       11.1 km             6.8 km
2       1.1 km              680 m
3       111 m               68 m
4       11.1 m              6.8 m
5       1.1 m               0.68 m
6       0.11 m              0.07 m

Quando este visualizador ajuda

Estas são as situações em que eu recorro a um visualizador de mapa JSON.

1. Conferir a resposta de uma API. Cole a resposta de uma API de clima, transporte ou localizador de lojas e veja na hora se as localizações fazem sentido, antes de escrever qualquer código de mapa.
2. Revisar a exportação de um app ou banco de dados. Apps de entrega, CRMs e plataformas de IoT costumam exportar JSON. Coloque a exportação no mapa para achar registros com coordenadas faltando ou erradas.
3. Converter JSON em GeoJSON ou CSV. Obtenha um arquivo GeoJSON para QGIS ou ArcGIS, ou um CSV para Excel, sem escrever um script.
4. Achar coordenadas trocadas. O aviso e o mapa deixam fácil ver o erro clássico em que latitude e longitude trocam de lugar em algum ponto de um processo.
5. Explorar portais de dados abertos. Muitos portais de dados abertos oferecem JSON ao lado de CSV. O JSON costuma manter detalhes aninhados que o CSV perde, e você pode colocá-lo direto no mapa.
6. Agrupar pontos por um campo. Colora por status, categoria ou tipo para ver padrões, por exemplo quais estações estão fora do ar ou quais lojas abrem aos domingos.
7. Depurar código de mapa. Se o seu próprio mapa mostra pontos no lugar errado, carregue o mesmo JSON aqui. Se aqui os pontos estiverem certos, o erro está no seu código, muitas vezes uma troca entre [lat, lng] e [lng, lat].
8. Ensinar JSON e coordenadas. Os alunos podem colar pequenos exemplos de JSON e ver como o aninhamento, os nomes de campo e a ordem das coordenadas mudam o resultado no mapa.

Perguntas frequentes

Bibliotecas e créditos

A leitura do JSON e a detecção das coordenadas foram escritas para este site. O mapa é feito com software de código aberto.

• Leaflet 1.9 · BSD-2-Clause · Volodymyr Agafonkin and contributors
  Desenha o mapa interativo, a camada de pontos em canvas e as janelas de informação.
• OpenStreetMap, Protomaps (hosted by KONAKTIVE), CARTO, Esri World Imagery · ODbL e termos do provedor · OpenStreetMap contributors, Protomaps, KONAKTIVE, CARTO, Esri
  Blocos e imagens do mapa base.

Ferramentas relacionadas