Antes de começar

Este documento descreve os pré-requisitos, as práticas recomendadas e os erros comuns ao trabalhar com conjuntos de dados.

Pré-requisitos

Ao criar um conjunto de dados:

• Os nomes de exibição precisam ser exclusivos no projeto do Google Cloud.
• Esses nomes devem ter menos de 64 bytes. Como os caracteres são representados em UTF-8, em alguns idiomas, um caractere pode ser representado por vários bytes.
• As descrições precisam ter menos de 1.000 bytes.

Ao fazer o upload de dados:

• Os tipos de arquivos compatíveis são CSV, GeoJSON e KML.
• O tamanho máximo de arquivo permitido é 500 MB.
• Os nomes das colunas de atributos não podem começar com a string "?_".
• Geometrias tridimensionais não são aceitas. Isso inclui o sufixo "Z" no formato WKT e a coordenada de altitude no formato GeoJSON.

Observação : dependendo do tamanho do arquivo de dados, o upload pode levar desde alguns minutos até algumas horas. Se houver um erro, você vai receber um alerta. Não tente excluir o conjunto de dados até que ele tenha retornado uma resposta da operação de upload.

Observação : os blocos de mapa criados com dados enviados usando a API Datasets do Maps podem descartar ou simplificar dados densos ou complexos em níveis de zoom baixos. Por exemplo, quando um usuário diminui o zoom para um estado ou país (por exemplo, nível de zoom de 5 a 12), os dados em blocos podem parecer diferentes do que quando o zoom é aumentado para uma cidade ou bairro (por exemplo, nível de zoom de 13 a 18). Isso acontece para manter os blocos leves e eficientes usando os blocos com um renderizador de mapa.

Dica : se o arquivo de dados for grande, tiver muitos atributos não necessários para definir o estilo e você quiser otimizar a renderização, edite o arquivo para remover os atributos desnecessários. Isso reduz o tamanho dos blocos do mapa, melhorando a performance.

Práticas recomendadas para a preparação de dados

Se os dados de origem forem complexos ou grandes, como pontos densos, polilinhas longas ou polígonos (geralmente, arquivos de origem maiores que 50 MB se enquadram nessa categoria), simplifique os dados antes de fazer o upload para ter o melhor desempenho em um mapa visual.

Confira algumas práticas recomendadas para preparar seus dados:

1. Minimizar propriedades de recursos. Mantenha apenas as propriedades de recursos necessárias para estilizar seu mapa, por exemplo, "id" e "category". É possível unir outras propriedades a um recurso em um aplicativo cliente usando estilos orientados a dados em uma chave de identificador exclusivo. Por exemplo, consulte Ver seus dados em tempo real com o estilo baseado em dados.
2. Use tipos de dados simples para objetos de propriedade sempre que possível, como números inteiros, para minimizar o tamanho do bloco e melhorar o desempenho do mapa.
3. Simplifique geometrias complexas antes de fazer upload de um arquivo. É possível fazer isso em uma ferramenta geoespacial da sua escolha, como o utilitário de código aberto Mapshaper.org, ou no BigQuery usando ST_Simplify em geometrias de polígonos complexos.
4. Agrupe pontos muito densos antes de fazer upload de um arquivo. Você pode fazer isso em uma ferramenta geoespacial de sua escolha, como as funções de cluster turf.js de código aberto, ou no BigQuery usando ST_CLUSTERDBSCAN em geometrias de pontos densos.

Consulte outras orientações sobre práticas recomendadas de conjuntos de dados em Visualizar seus dados com conjuntos de dados e o BigQuery.

Requisitos de GeoJSON

A API Datasets do Google Maps é compatível com a especificação atual do GeoJSON. A API Maps Datasets também aceita arquivos GeoJSON que contêm qualquer um destes tipos de objetos:

• Objetos de geometria. Esse tipo de objeto é uma forma espacial, descrita como uma união de pontos, linhas e polígonos com furos opcionais.
• Objetos de elementos. Esse tipo de objeto contém uma geometria e outros pares de nome/valor, com um significado específico do aplicativo.
• Coleções de elementos. Uma coleção de recursos é um conjunto de objetos de recursos.

A API Maps Datasets não é compatível com arquivos GeoJSON que têm dados em um sistema de referência de coordenadas (CRS, na sigla em inglês) diferente de WGS84.

Para mais informações sobre o GeoJSON, consulte Compliance com RFC 7946 (ambos os links em inglês).

Requisitos de KML

A API Maps Datasets tem os seguintes requisitos:

• Todos os URLs precisam ser locais (ou relativos) ao próprio arquivo.
• Compatível com geometrias de ponto, linha e polígono.
• Todos os atributos de dados são considerados strings.

Os seguintes elementos KML não são compatíveis:

• Ícones ou <styleUrl> definidos fora do arquivo
• Links de rede, como <NetworkLink>
• Sobreposições de solo, por exemplo, <GroundOverlay>
• Geometrias 3D ou qualquer tag relacionada à altitude, como <altitudeMode>
• Especificações da câmera, por exemplo, <LookAt>
• Estilos definidos dentro do arquivo KML

Requisitos de CSV

Para arquivos CSV, os nomes das colunas compatíveis são listados abaixo em ordem de prioridade:

• latitude, longitude
• lat, long
• x, y
• wkt (texto conhecido)
• address, city, state, zip
• address
• Uma única coluna contendo todas as informações de endereço, como 1600 Amphitheatre Parkway Mountain View, CA 94043

Por exemplo, seu arquivo inclui colunas chamadas x, y e wkt. Como x e y têm uma prioridade mais alta, segundo a ordem dos nomes de colunas compatíveis na lista acima, os valores nas colunas x e y são usados, e a coluna wkt é ignorada.

Além disso:

• Cada nome de coluna tem que pertencer a uma única coluna, ou seja, não é possível ter uma coluna chamada xy que inclua dados das coordenadas x e y. Essas coordenadas precisam estar em colunas diferentes.
• Os nomes das colunas não diferenciam maiúsculas de minúsculas.
• A ordem dos nomes não importa. Por exemplo, se o arquivo CSV tiver colunas lat e long, elas poderão estar em qualquer ordem.

Resolver erros de upload de dados

Ao fazer o upload de dados para um conjunto, você pode encontrar um dos erros comuns descritos nesta seção.

Erros de GeoJSON

Exemplo de erro comum de GeoJSON:

• Campo type faltando, ou type não é uma string. O arquivo de dados GeoJSON enviado precisa ter um campo de string chamado type em cada definição de objeto de elemento e de geometria.

Erros de KML

Exemplo de erro comum de KML:

• O arquivo de dados não pode conter nenhum dos elementos KML incompatíveis listados acima. Caso contrário, a importação pode falhar.

Erros de CSV

Exemplos de erros comuns de CSV:

• Algumas linhas não contêm valores para uma coluna de geometria. Em um arquivo CSV, todas as linhas em colunas desse tipo precisam ter valores não vazios. Confira algumas colunas de geometria:
  • latitude, longitude
  • lat, long
  • x, y
  • wkt
  • address, city, state, zip
  • address
  • Uma única coluna contendo todas as informações de endereço, como 1600 Amphitheatre Parkway Mountain View, CA 94043
  Observação: esse erro geralmente é descrito por uma mensagem no formato "Não foi possível converter ' ' em aspas duplas" ou "Não foi possível analisar a entrada na região geográfica: está faltando o valor da geografia".
• Se x e y forem suas colunas de geometria, verifique se as unidades são longitude e latitude. Alguns conjuntos de dados públicos usam sistemas de coordenadas diferentes nos cabeçalhos x e y. Se as unidades incorretas forem usadas, o conjunto poderá ser importado, mas os dados renderizados talvez mostrem os pontos em locais inesperados.