Prima di iniziare

Questo documento descrive i prerequisiti, le best practice e gli errori comuni quando si lavora con i set di dati.

Prerequisiti

Quando crei un set di dati:

• I nomi visualizzati devono essere univoci all'interno del progetto Google Cloud.
• I nomi visualizzati devono essere inferiori a 64 byte (poiché questi caratteri sono rappresentati in UTF-8, in alcune lingue ogni carattere può essere rappresentato da più byte).
• Le descrizioni devono contenere meno di 1000 byte.

Quando carichi i dati:

• I tipi di file supportati sono CSV, GeoJSON e KML.
• La dimensione massima del file supportata è di 500 MB.
• I nomi delle colonne degli attributi non possono iniziare con la stringa "?_".
• Le geometrie tridimensionali non sono supportate. Sono inclusi il suffisso "Z" nel formato WKT e la coordinata dell'altitudine nel formato GeoJSON.

Nota: a seconda delle dimensioni del file di dati, il caricamento può richiedere minuti o persino ore. Se si verifica un errore durante il caricamento, riceverai un messaggio di errore. Non tentare di eliminare il set di dati finché non ha restituito una risposta dall'operazione di caricamento.

Nota: i riquadri della mappa creati con i dati caricati utilizzando l'API Maps Datasets possono eliminare o semplificare i dati densi o complessi a livelli di zoom bassi. Ad esempio, quando un utente diminuisce lo zoom per visualizzare uno stato o un paese (ad esempio, livello di zoom 5-12), i dati in tile potrebbero avere un aspetto diverso rispetto a quando lo zoom viene aumentato per visualizzare una città o un quartiere (ad esempio, livello di zoom 13-18). Questo avviene per mantenere i riquadri leggeri e performanti utilizzando i riquadri con un renderer di mappe.

Suggerimento: se il file di dati è di grandi dimensioni e contiene molti attributi che non ti servono per lo stile e vuoi ottimizzare le prestazioni di rendering, modifica il file per rimuovere gli attributi non necessari. La riduzione del numero di attributi riduce le dimensioni dei riquadri della mappa, migliorando così le prestazioni di rendering.

Best practice per la preparazione dei dati

Se i dati di origine sono complessi o di grandi dimensioni, ad esempio punti densi, stringhe di linee lunghe o poligoni (spesso i file di origine di dimensioni superiori a 50 MB rientrano in questa categoria), ti consigliamo di semplificarli prima di caricarli per ottenere il miglior rendimento in una mappa visiva.

Di seguito sono riportate alcune best practice per la preparazione dei dati:

1. Riduci a icona le proprietà degli elementi. Conserva solo le proprietà degli elementi necessarie per applicare lo stile alla mappa, ad esempio "id" e "category". Puoi unire proprietà aggiuntive a un elemento in un'applicazione client utilizzando gli stili basati sui dati su una chiave identificatore univoco. Ad esempio, consulta Visualizza i dati in tempo reale con gli stili basati sui dati.
2. Utilizza tipi di dati semplici per gli oggetti proprietà, se possibile, ad esempio numeri interi, per ridurre al minimo le dimensioni dei riquadri e migliorare le prestazioni della mappa.
3. Semplifica le geometrie complesse prima di caricare un file. Puoi farlo in uno strumento geospaziale di tua scelta, ad esempio l'utilità open source Mapshaper.org, o in BigQuery utilizzando ST_Simplify su geometrie poligonali complesse.
4. Raggruppa i punti molto densi prima di caricare un file. Puoi farlo in uno strumento geospaziale di tua scelta, ad esempio le funzioni di clustering turf.js open source, o in BigQuery utilizzando ST_CLUSTERDBSCAN su geometrie di punti densi.

Per ulteriori indicazioni sulle best practice per i set di dati, consulta Visualizza i dati con i set di dati e BigQuery.

Requisiti GeoJSON

L'API Maps Datasets supporta l'attuale specifica GeoJSON. L'API Maps Datasets supporta anche i file GeoJSON che contengono uno dei seguenti tipi di oggetti:

• Oggetti geometrici. Un oggetto geometrico è una forma spaziale, descritta come un'unione di punti, linee e poligoni con fori facoltativi.
• Oggetti Feature. Un oggetto elemento contiene una geometria e coppie nome/valore aggiuntive, il cui significato è specifico dell'applicazione.
• Raccolte di elementi. Una raccolta di caratteristiche è un insieme di oggetti caratteristica.

L'API Maps Datasets non supporta i file GeoJSON con dati in un sistema di riferimento di coordinate (CRS) diverso da WGS84.

Per saperne di più su GeoJSON, consulta Conformità a RFC 7946.

Requisiti KML

L'API Maps Datasets prevede i seguenti requisiti:

• Tutti gli URL devono essere locali (o relativi) al file stesso.
• Sono supportate le geometrie di punti, linee e poligoni.
• Tutti gli attributi dei dati sono considerati stringhe.

Le seguenti funzionalità KML non sono supportate:

• Icone o <styleUrl> definite al di fuori del file.
• Link di rete, ad esempio <NetworkLink>
• Overlay del terreno, come <GroundOverlay>
• Geometrie 3D o tag relativi all'altitudine come <altitudeMode>
• Specifiche della fotocamera, ad esempio <LookAt>
• Stili definiti all'interno del file KML.

Requisiti dei file CSV

Per i file CSV, i nomi delle colonne supportati sono elencati di seguito in ordine di priorità:

• latitude, longitude
• lat, long
• x, y
• wkt (Well-Known Text)
• address, city, state, zip
• address
• Una singola colonna contenente tutte le informazioni sull'indirizzo, ad esempio 1600 Amphitheatre Parkway Mountain View, CA 94043

Ad esempio, il file contiene colonne denominate x, y e wkt. Poiché x e y hanno una priorità più alta, come determinato dall'ordine dei nomi delle colonne supportate nell'elenco precedente, vengono utilizzati i valori nelle colonne x e y e la colonna wkt viene ignorata.

Inoltre:

• Ogni nome di colonna deve appartenere a una singola colonna. In altre parole, non puoi avere una colonna denominata xy che contiene dati relativi alle coordinate x e y. Le coordinate x e y devono trovarsi in colonne separate.
• I nomi delle colonne non fanno distinzione tra maiuscole e minuscole.
• L'ordine dei nomi delle colonne non è importante. Ad esempio, se il file CSV contiene le colonne lat e long, queste possono essere visualizzate in qualsiasi ordine.

Gestisci gli errori di caricamento dei dati

Quando carichi i dati in un set di dati, potresti riscontrare uno degli errori comuni descritti in questa sezione.

Errori GeoJSON

Gli errori GeoJSON più comuni includono:

• Campo type mancante o type non è una stringa. Il file di dati GeoJSON caricato deve contenere un campo stringa denominato type come parte di ogni definizione di oggetto Feature e Geometry.

Errori KML

Gli errori KML più comuni includono:

• Il file di dati non deve contenere nessuna delle funzionalità KML non supportate elencate sopra, altrimenti l'importazione dei dati potrebbe non riuscire.

Errori CSV

Gli errori comuni dei file CSV includono:

• Alcune righe non contengono valori per una colonna di geometria. Tutte le righe di un file CSV devono contenere valori non vuoti per le colonne di geometria. Le colonne di geometria includono:
  • latitude, longitude
  • lat, long
  • x, y
  • wkt
  • address, city, state, zip
  • address
  • Una singola colonna contenente tutte le informazioni sull'indirizzo, ad esempio 1600 Amphitheatre Parkway Mountain View, CA 94043
  Nota: questo errore viene spesso descritto da un messaggio nel formato "Impossibile convertire ' ' in un valore double" o "Impossibile analizzare l'input in un valore geografico". Manca il valore dell'area geografica".
• Se x e y sono le colonne della geometria, assicurati che le unità siano longitudine e latitudine. Alcuni set di dati pubblici utilizzano sistemi di coordinate diversi nelle intestazioni x e y. Se vengono utilizzate unità errate, il set di dati potrebbe essere importato correttamente, ma i dati visualizzati potrebbero mostrare i punti del set di dati in posizioni impreviste.