Inizia

Introduzione

L'API Maps Static restituisce un'immagine (GIF, PNG o JPEG) in risposta a una richiesta HTTP tramite un URL. Per ogni richiesta, puoi specificare la posizione della mappa, le dimensioni dell'immagine, il livello di zoom, il tipo di mappa e il posizionamento degli indicatori facoltativi in corrispondenza delle posizioni sulla mappa. Puoi anche etichettare gli indicatori utilizzando caratteri alfanumerici.

Un'immagine dell'API Maps Static è incorporata nell'attributo src del tag <img> o equivalente in altri linguaggi di programmazione.

Questo documento descrive il formato richiesto degli URL dell'API Maps Static e i parametri disponibili. Sono inoltre indicati alcuni suggerimenti utili per specificare gli URL.

Prima di iniziare

Questo documento è destinato agli sviluppatori di siti web e dispositivi mobili che desiderano includere immagini dell'API Maps Static in una pagina web o un'applicazione mobile. Fornisce un'introduzione all'utilizzo dell'API e materiale di riferimento sui parametri disponibili.

Prima di iniziare a sviluppare con l'API Maps Static, rivedi i requisiti di autenticazione (è necessaria una chiave API) e le informazioni su utilizzo e fatturazione dell'API (devi abilitare la fatturazione per il tuo progetto).

Parametri URL

Un URL dell'API Maps Static deve avere il seguente formato:

https://maps.googleapis.com/maps/api/staticmap?parameters

Se il tuo sito web viene visitato tramite HTTPS, devi caricare le immagini dell'API Maps Static anche tramite HTTPS per evitare avvisi di sicurezza del browser. HTTPS è consigliato anche se le richieste includono informazioni utente sensibili, come la sua posizione:

https://maps.googleapis.com/maps/api/staticmap?parameters

Che si tratti di utilizzare HTTP o HTTPS, alcuni parametri URL sono obbligatori, mentre altri sono facoltativi. Come avviene negli URL standard, tutti i parametri sono separati dalla e commerciale (&). L'elenco dei parametri e dei relativi valori sono enumerati in questo documento.

L'API Maps Static definisce le immagini mappa utilizzando i seguenti parametri URL:

Parametri di località

• center (obbligatorio se gli indicatori non sono presenti) definisce il centro della mappa, equidistante da tutti i bordi della mappa. Questo parametro prende una posizione come coppia di {latitudine,longitudine} separate da virgole (ad es. "40.714728,-73.998672") o come indirizzo stringa (ad es. "municipi, new york, ny") che identifica un luogo unico sulla faccia della Terra. Per ulteriori informazioni, consulta la sezione Località.
• zoom (obbligatorio se gli indicatori non sono presenti) definisce il livello di zoom della mappa, che determina il livello di ingrandimento della mappa. Questo parametro assume un valore numerico corrispondente al livello di zoom della regione desiderata. Per ulteriori informazioni, consulta la sezione Livelli di zoom.

Parametri mappa

• size (obbligatorio) definisce le dimensioni rettangolari dell'immagine della mappa. Questo parametro accetta una stringa nel formato {horizontal_value}x{vertical_value}. Ad esempio, 500x400 definisce una mappa di 500 pixel di larghezza per 400 pixel di altezza. Le mappe con larghezza inferiore a 180 pixel mostreranno un logo Google di dimensioni ridotte. Questo parametro è interessato dal parametro scale; la dimensione finale dell'output è il prodotto dei valori dimensione e scala.
• scale (facoltativo) influisce sul numero di pixel che vengono restituiti. scale=2 restituisce un numero di pixel doppio rispetto a scale=1 mantenendo la stessa area di copertura e lo stesso livello di dettaglio (ad esempio, i contenuti della mappa non cambiano). È utile durante lo sviluppo di display ad alta risoluzione. Il valore predefinito è 1. I valori accettati sono 1 e 2. Consulta Valori di scala per ulteriori informazioni.
• format (facoltativo) definisce il formato dell'immagine risultante. Per impostazione predefinita, l'API Maps Static crea immagini PNG. Esistono diversi formati possibili, inclusi GIF, JPEG e PNG. Il formato da utilizzare dipende da come intendi presentare l'immagine. In genere i formati JPEG offrono maggiore compressione, mentre GIF e PNG forniscono maggiori dettagli. Per ulteriori informazioni, consulta la sezione Formati delle immagini.
• maptype (facoltativo) definisce il tipo di mappa da costruire. Esistono diversi valori maptype possibili, tra cui roadmap, satellite, hybrid e terrain. Per ulteriori informazioni, consulta la sezione Maptypes dell'API Maps Static.
• language (facoltativo) definisce la lingua da utilizzare per la visualizzazione delle etichette sui riquadri della mappa. Tieni presente che questo parametro è supportato solo per alcuni riquadri dei paesi; se la lingua specifica richiesta non è supportata per il set di riquadri, verrà utilizzata la lingua predefinita per il set di riquadri in questione.
• region (facoltativo) definisce i confini appropriati da visualizzare in base alle sensibilità geopolitiche. Accetta un codice regione specificato come valore ccTLD ("dominio di primo livello") a due caratteri. Vedi i dettagli della copertura di Google Maps Platform per le regioni supportate.

Parametri della funzionalità

• map_id (facoltativo) specifica l'identificatore di una mappa specifica. L'ID mappa associa una mappa a uno stile o a una funzionalità particolare e deve appartenere allo stesso progetto della chiave API utilizzata per inizializzare la mappa. Per ulteriori informazioni, consulta la sezione Utilizzo degli ID mappa.
• markers (facoltativo) definisce uno o più indicatori da allegare all'immagine nelle posizioni specificate. Questo parametro accetta una singola definizione di indicatori con parametri separati dal carattere barra verticale (|). All'interno dello stesso parametro markers possono essere posizionati più indicatori purché mostrino lo stesso stile. Puoi aggiungere ulteriori indicatori di stili diversi aggiungendo altri parametri markers. Tieni presente che se fornisci indicatori per una mappa, non devi specificare i parametri center e zoom (normalmente obbligatori). Per ulteriori informazioni, consulta la pagina relativa agli indicatori API statici di Google Maps.
• path (facoltativo) definisce un singolo percorso di due o più punti connessi da sovrapporre all'immagine in corrispondenza della posizione specificata. Questo parametro accetta una stringa di definizioni di punti separate dal carattere barra verticale (|) o una polilinea codificata utilizzando il prefisso enc: all'interno della dichiarazione della posizione del percorso. Puoi fornire percorsi aggiuntivi aggiungendo altri parametri path. Tieni presente che se fornisci un percorso per una mappa, non è necessario specificare i parametri center e zoom (normalmente obbligatori). Per ulteriori informazioni, consulta la pagina dedicata ai percorsi dell'API Maps Static.
• visible (facoltativo) specifica una o più località che devono rimanere visibili sulla mappa, sebbene non vengano visualizzati indicatori o altri indicatori. Utilizza questo parametro per assicurarti che determinate funzionalità o posizioni sulla mappa vengano visualizzate nell'API Maps Static.
• style (facoltativo) definisce uno stile personalizzato per modificare la presentazione di un elemento specifico (strade, parchi e altri elementi) della mappa. Questo parametro accetta argomenti feature e element che identificano le caratteristiche per lo stile e un insieme di operazioni di stile da applicare alle caratteristiche selezionate. Puoi fornire più stili aggiungendo altri parametri style. Per ulteriori informazioni, consulta la guida alle mappe con stili applicati.

Parametri chiave e firma

• key (obbligatorio) ti consente di monitorare l'utilizzo dell'API dell'applicazione in Google Cloud Console e garantisce che Google possa contattarti in merito alla tua richiesta, se necessario. Per saperne di più, consulta la sezione Utilizzare le chiavi API con l'API Maps Static.
• signature (consigliato) è una firma digitale utilizzata per verificare che qualsiasi sito che genera richieste utilizzando la tua chiave API sia autorizzato a farlo. Le richieste senza firma digitale potrebbero non riuscire. Per ulteriori informazioni, vedi Utilizzare una firma digitale.

Limitazione delle dimensioni degli URL

La dimensione degli URL dell'API Maps Static è limitata a 16.384 caratteri. In pratica, probabilmente non avrai bisogno di URL più lunghi di questo, a meno che tu non produca mappe complesse con un numero elevato di indicatori e percorsi.

Utilizzo dei parametri

L'API Maps Static è relativamente facile da usare, in quanto è costituita esclusivamente da un URL parametrizzato. Questa sezione spiega come utilizzare questi parametri per creare gli URL.

Specifica delle località

L'API Maps Static deve essere in grado di identificare con precisione le località sulla mappa, sia per focalizzare la mappa nella posizione corretta (utilizzando il parametro center) che/o per posizionare eventuali segnaposto facoltativi (utilizzando il parametro markers) nelle località sulla mappa. L'API Maps Static utilizza numeri (valori di latitudine e longitudine) o stringhe (indirizzi) per specificare queste località. Questi valori identificano una località geocodificata.

Diversi parametri (come i parametri markers e path) occupano più posizioni. In questi casi, le località sono separate dal carattere barra verticale (|).

Latitudini e longitudine

Latitudini e longitudini vengono definite utilizzando numeri all'interno di una stringa di testo separata da virgola con una precisione fino a sei cifre decimali. Ad esempio, "40.714728,-73.998672" è un valore geografico valido. La precisione oltre le sei cifre decimali viene ignorata.

I valori della longitudine si basano sulla loro distanza da Greenwich, in Inghilterra, dove si trova il meridiano fondamentale. Poiché Greenwich si trova a 51,477222 latitudine, possiamo inserire un valore center pari a 51.477222,0 per centrare la mappa su Greenwich:

I valori di latitudine e longitudine devono corrispondere a una posizione valida sulla faccia del pianeta. La latitudine può assumere qualsiasi valore compreso tra -90 e 90, mentre i valori di longitudine possono avere qualsiasi valore compreso tra -180 e 180. Se specifichi un valore non valido per la latitudine o la longitudine, la richiesta verrà rifiutata.

Indirizzi

La maggior parte delle persone non parla in latitudine e longitudine ma indica le località mediante gli indirizzi. Il processo di trasformazione di un indirizzo in un punto geografico è noto come geocodifica e il servizio API Maps Static può eseguire la geocodifica per te se fornisci indirizzi validi.

In qualsiasi parametro per cui puoi fornire latitudine/longitudine, puoi specificare invece una stringa che indica un indirizzo. Google geocodifica l'indirizzo e fornisce al servizio API Maps Static un valore di latitudine/longitudine da utilizzare per posizionare gli indicatori o specificare le località. La stringa deve essere codificata in URL, quindi indirizzi come "Municipio, New York, NY" devono essere convertiti in "Palazzo+della+città,New+York,NY", ad esempio.

Tieni presente che gli indirizzi possono riflettere posizioni precise, ad esempio via, polilinee come percorsi con nome o aree poligonali come città, paesi o parchi nazionali. Per i risultati polilineari e poligonali, il server dell'API Maps Static utilizzerà il punto centrale della linea/area come centro degli indirizzi. Se hai dei dubbi sul modo in cui un indirizzo può essere geocodificato, puoi testarlo utilizzando questa utilità di geocodifica.

L'esempio seguente genera un'immagine mappa statica per Berkeley, CA:

https://maps.googleapis.com/maps/api/staticmap?center=Berkeley,CA&zoom=14&size=400x400&key=YOUR_API_KEY&signature=YOUR_SIGNATURE

Livelli di zoom

Le mappe su Google Maps hanno un "livello di zoom" numero intero che definisce la risoluzione della vista corrente. I livelli di zoom compresi tra 0 (il livello di zoom più basso, dove è visibile tutto il mondo su una mappa) e 21+ (fino a strade ed edifici) sono possibili nella visualizzazione roadmap predefinita. I contorni degli edifici, se disponibili, vengono visualizzati sulla mappa intorno al livello di zoom 17. Questo valore varia da un'area all'altra e può cambiare nel tempo con l'evolversi dei dati.

Google Maps imposta il livello di zoom 0 per includere l'intera Terra. Ogni livello di zoom successivo raddoppia la precisione nelle dimensioni orizzontale e verticale. Ulteriori informazioni su come eseguire questa operazione sono disponibili nella documentazione relativa all'API JavaScript di Google Maps.

Nota: non tutti i livelli di zoom vengono visualizzati in tutte le posizioni della Terra. I livelli di zoom variano a seconda della località, poiché i dati in alcune parti del globo sono più granulari che in altre località.

Se invii una richiesta per un livello di zoom in cui non sono presenti riquadri della mappa, l'API Maps Static restituirà invece un'immagine vuota.

Il seguente elenco mostra il livello approssimativo di dettaglio previsto per ogni livello di zoom:

• 1: Mondo
• 5: massa continentale/continente
• 10: Città
• 15: strade
• 20: edifici

Questo esempio richiede due mappe di Manhattan con lo stesso valore center, ma a livelli di zoom rispettivamente 12 e 14:

https://maps.googleapis.com/maps/api/staticmap?center=40.714728,-73.998672&zoom=12&size=400x400&key=YOUR_API_KEY&signature=YOUR_SIGNATURE
https://maps.googleapis.com/maps/api/staticmap?center=40.714728,-73.998672&zoom=14&size=400x400&key=YOUR_API_KEY&signature=YOUR_SIGNATURE

  

Dimensioni delle immagini

Il parametro size, in combinazione con center, definisce l'area di copertura di una mappa. Definisce inoltre le dimensioni di output della mappa in pixel, quando moltiplicato per il valore scale (che è 1 per impostazione predefinita).

Questa tabella mostra i valori massimi consentiti per il parametro size per ogni valore scale.

scale=1	scale=2
640x640	640x640 (restituisce 1280 x 1280 pixel)

Questo esempio richiede una "sezione" della Terra all'equatore a livello di zoom 1:

https://maps.googleapis.com/maps/api/staticmap?center=0,0&zoom=1&size=400x50&key=YOUR_API_KEY&signature=YOUR_SIGNATURE

Questo esempio richiede una mappa di piccole dimensioni, di 100 x 100 pixel, centrata sulla stessa regione. Nota il logo Google più piccolo:

https://maps.googleapis.com/maps/api/staticmap?center=0,0&zoom=1&size=100x100&key=YOUR_API_KEY&signature=YOUR_SIGNATURE

Valori scala

Il parametro size dell'API Maps Static definisce le dimensioni di una mappa in pixel, pertanto una mappa con size=200x200 viene restituita come 200 pixel per 200 pixel. Sul monitor di un computer LCD, che in genere mostra circa 100 pixel per pollice (ppi), una mappa di 200 x 200 avrà dimensioni di circa 2 pollici per ogni dimensione.

Tuttavia, i dispositivi mobili includono sempre più schermi ad alta risoluzione con densità di pixel superiore a 300 ppi che:

• Ridurre le dimensioni di un'immagine di 200 x 200 pixel a solo 0,7 pollici, il rendering di etichette e icone è troppo piccolo per essere letto; oppure
• Scalare (eseguire lo zoom) dell'immagine per migliorarne la leggibilità, ottenendo un'immagine sfocata o pixelata.

Troppo piccolo	Troppo indistinta

Durante lo sviluppo per i dispositivi mobili, puoi utilizzare il parametro scale dell'API per restituire immagini della mappa con una risoluzione maggiore che risolvono i problemi indicati in precedenza. Il valore scale viene moltiplicato per size per determinare le effettive dimensioni di output dell'immagine in pixel, senza modificare l'area di copertura della mappa. Il valore predefinito di scale è 1; i valori accettati sono 1 e 2.

Ad esempio, un valore di scala pari a 2 restituirà la stessa area di copertura della mappa di una richiesta in cui non è specificata la scala, ma con il doppio dei pixel in ogni dimensione. Sono incluse strade ed etichette, in modo che siano leggibili su schermi ad alta risoluzione e di piccole dimensioni, nonché quando vengono ridimensionati dal browser.

150x150	150x150&scale=2

Un'immagine di questo tipo avrà un buon rendimento anche sui browser desktop, se inserita in un tag img o div con l'altezza e la larghezza impostate tramite CSS. Il browser ridimensionerà l'immagine per riportarla alle dimensioni corrette, senza perdita di qualità.

Questa tabella mostra tre diverse richieste di immagine.

• Il primo è per un'immagine 100 x 100, senza alcun valore di scala specificato. Viene visualizzata correttamente sul computer, ma è troppo piccolo per essere letto su un dispositivo mobile.
• Il secondo consente di raddoppiare le dimensioni della mappa. Sul desktop, il CSS lo inserisce nell'elemento img 100 x 100 specificato, ma nel ridimensionamento dell'immagine, strade ed etichette diventano troppo piccole. Sul dispositivo mobile l'immagine ha le dimensioni corrette, ma anche in questo caso strade ed etichette sono illeggibili.
• La terza richiesta riguarda una mappa 100 x 100 con scale=2. L'immagine viene restituita con 200 px di dettaglio; il desktop la riduce perfettamente, rendendola indistinguibile dalla richiesta originale 100 x 100, mentre il browser mobile beneficia della risoluzione aggiuntiva restituita dall'API.

Richieste di immagini
Dispositivo	100x100	200x200	100x100&scale=2
Computer (con height="100px" e width="100px" nel tag img)
Alta risoluzione (simulata)

Per ulteriori informazioni sullo sviluppo di display per dispositivi mobili e ad alta risoluzione, ti consigliamo di leggere quanto segue:

• Supporto di più schermi nella documentazione per gli sviluppatori Android.
• Suggerimenti di Webkit.org per lo sviluppo di siti web con DPI elevato.
• Supporto degli schermi ad alta risoluzione nella libreria degli sviluppatori iOS.

Formati dell'immagine

Le immagini possono essere restituite in diversi formati comuni di grafica web: GIF, JPEG e PNG. Il parametro format accetta uno dei seguenti valori:

• png8 o png (predefinito) specifica il formato PNG a 8 bit.
• png32 specifica il formato PNG a 32 bit.
• gif specifica il formato GIF.
• jpg specifica il formato di compressione JPEG.
• jpg-baseline specifica un formato di compressione JPEG non progressiva.

Questi esempi richiedono mappe nei formati gif e png:

  https://maps.googleapis.com/maps/api/staticmap?center=40.714728,-73.998672&format=gif&zoom=14&size=400x400&key=YOUR_API_KEY&signature=YOUR_SIGNATURE
  https://maps.googleapis.com/maps/api/staticmap?center=40.714728,-73.998672&format=png&&zoom=14&size=400x400&key=YOUR_API_KEY&signature=YOUR_SIGNATURE

jpg e jpg-baseline in genere forniscono le dimensioni più ridotte delle immagini, anche se lo fanno tramite una compressione "con perdita di dati", che potrebbe deteriorarla. gif, png8 e png32 forniscono compressione senza perdita di dati.

La maggior parte delle immagini JPEG è progressiva, ovvero carica un'immagine più grossolana e perfeziona la risoluzione dell'immagine man mano che arriva una quantità maggiore di dati. Ciò consente di caricare rapidamente le immagini nelle pagine web ed è attualmente l'uso più diffuso di JPEG. Tuttavia, alcuni utilizzi del formato JPEG richiedono immagini non progressive (base di riferimento). In questi casi, puoi utilizzare il formato jpg-baseline, che non è progressivo.

Tipi di mappa

L'API Maps Static crea mappe in diversi formati, elencati di seguito:

• roadmap (predefinita) specifica un'immagine standard della roadmap, come normalmente mostrata sul sito web di Google Maps. Se non viene specificato alcun valore maptype, l'API Maps Static pubblica roadmap riquadri per impostazione predefinita.
• satellite specifica un'immagine satellitare.
• terrain specifica un'immagine in rilievo della mappa che mostra terreno e vegetazione.
• hybrid specifica un ibrido tra l'immagine satellitare e quella della roadmap, che mostra un livello trasparente delle strade principali e dei nomi dei luoghi sull'immagine satellitare.

Puoi vedere la differenza tra i tipi di roadmap e rilievo in questo esempio di codice.

https://maps.googleapis.com/maps/api/staticmap?center=40.714728,-73.998672&zoom=12&size=400x400&maptype=roadmap&key=YOUR_API_KEY&signature=YOUR_SIGNATURE
https://maps.googleapis.com/maps/api/staticmap?center=40.714728,-73.998672&zoom=12&size=400x400&maptype=terrain&key=YOUR_API_KEY&signature=YOUR_SIGNATURE

  

Le mappe ibride utilizzano immagini satellitari e funzionalità in evidenza delle roadmap per creare una mappa combinata. I seguenti esempi mostrano i tipi di mappe satellitari e ibride:

https://maps.googleapis.com/maps/api/staticmap?center=40.714728,-73.998672&zoom=12&size=400x400&maptype=satellite&key=YOUR_API_KEY&signature=YOUR_SIGNATURE
https://maps.googleapis.com/maps/api/staticmap?center=40.714728,-73.998672&zoom=12&size=400x400&maptype=hybrid&key=YOUR_API_KEY&signature=YOUR_SIGNATURE

  

Mappe con stili applicati

Personalizza la presentazione della mappa Google standard applicando i tuoi stili. Consulta la guida alle mappe con stili applicati.

Indicatori

Il parametro markers definisce un insieme di uno o più indicatori (puntini della mappa) in un insieme di posizioni. Ogni indicatore definito in una singola dichiarazione markers deve mostrare lo stesso stile visivo; se vuoi visualizzare indicatori con stili diversi, devi fornire più parametri markers con informazioni di stile separate.

Il parametro markers accetta un insieme di assegnazioni di valori (descrittori dell'indicatore) nel seguente formato:

markers=markerStyles|markerLocation1| markerLocation2|... e così via.

L'insieme di markerStyles è dichiarato all'inizio della dichiarazione markers ed è costituito da zero o più descrittori di stile separati dal carattere barra verticale (|), seguiti da un insieme di una o più località anche separate dal carattere barra verticale (|).

Poiché sia le informazioni sullo stile sia quelle sulla posizione sono delimitate dalla barra verticale, queste devono apparire per prime in qualsiasi descrittore dell'indicatore. Quando il server dell'API Maps Static rileva una posizione nel descrittore dell'indicatore, anche tutti gli altri parametri dell'indicatore vengono considerati posizioni.

Stili indicatore

Il set di descrittori di stile degli indicatori è una serie di assegnazioni di valori separate dal carattere barra verticale (|). Questo descrittore di stile definisce gli attributi visivi da utilizzare per la visualizzazione degli indicatori all'interno del descrittore dell'indicatore. Questi descrittori di stile contengono le seguenti assegnazioni chiave/valore:

• size: (facoltativo) specifica la dimensione dell'indicatore nel set {tiny, mid, small}. Se non viene impostato alcun parametro size, l'indicatore verrà visualizzato con le dimensioni predefinite (normali).

• color: (facoltativo) specifica un colore a 24 bit (esempio: color=0xFFFFCC) o un colore predefinito del set {black, brown, green, purple, yellow, blue, gray, orange, red, white}.

  Tieni presente che le trasparenze (specificate utilizzando valori di colore esadecimali a 32 bit) non sono supportate negli indicatori, sebbene siano supportate per i percorsi.

• (Facoltativo) label: specifica un singolo carattere alfanumerico uppercase nel set {A-Z, 0-9}. Il requisito dell'uso di caratteri maiuscoli è una novità in questa versione dell'API. Tieni presente che gli indicatori di dimensioni predefinite e mid sono gli unici indicatori in grado di visualizzare un parametro alphanumeric-character. Gli indicatori tiny e small non possono mostrare caratteri alfanumerici.

Ridimensionamento indicatore

Il valore scale viene moltiplicato per le dimensioni dell'immagine dell'indicatore per ottenere le dimensioni di output effettive dell'indicatore in pixel. Il valore predefinito della scala è 1; i valori accettati sono 1, 2 e 4.

Il limite di dimensioni in pixel delle immagini viene applicato dopo l'applicazione del ridimensionamento. Ad esempio, se l'indicatore è impostato su scale:2, può essere superiore alla dimensione massima di 4096 pixel, purché venga ridotta a meno di 4096 pixel dopo il ridimensionamento. Utilizza il ridimensionamento degli indicatori insieme al ridimensionamento della mappa per la visualizzazione di mappe con risoluzione più elevata.

Posizioni degli indicatori

Ogni descrittore dell'indicatore deve contenere un insieme di una o più posizioni che definiscano dove posizionare l'indicatore sulla mappa. Queste località possono essere specificate come valori di latitudine/longitudine o come indirizzi. Queste località sono separate da una barra verticale (|).

Nota: se scegli di specificare la posizione degli indicatori utilizzando un metodo che richiede la geocodifica, ad esempio stringhe di indirizzi o polilinee leggibili da persone, la richiesta è limitata a un massimo di 15 indicatori. Questo limite si applica solo alle posizioni degli indicatori che richiedono la geocodifica. Non si applica alle posizioni degli indicatori specificate con le coordinate di latitudine/longitudine.

I parametri di posizione definiscono la posizione dell'indicatore sulla mappa. Se la località non è presente sulla mappa, l'indicatore non verrà visualizzato nell'immagine creata, a condizione che vengano forniti i parametri center e zoom. Tuttavia, se questi parametri non vengono forniti, il server dell'API Maps Static crea automaticamente un'immagine che contiene gli indicatori forniti. Consulta la sezione Posizionamento implicito.

Qui viene mostrata una dichiarazione di esempio di un indicatore. Tieni presente che definiamo un insieme di stili e tre posizioni:

https://maps.googleapis.com/maps/api/staticmap?center=Williamsburg,Brooklyn,NY&zoom=13&size=400x400&
markers=color:blue%7Clabel:S%7C11211%7C11206%7C11222&key=YOUR_API_KEY&signature=YOUR_SIGNATURE

Per definire gli indicatori con stili diversi, dobbiamo fornire più parametri markers. Questo insieme di parametri markers definisce tre indicatori: un indicatore blu con l'etichetta "S" a 62.107733, -145.5419, un piccolo indicatore verde in "Delta Junction, AK" e un indicatore giallo di medie dimensioni con l'etichetta "C" in "Tok, AK". Questi indicatori sono mostrati in questo esempio:

https://maps.googleapis.com/maps/api/staticmap?center=63.259591,-144.667969&zoom=6&size=400x400
&markers=color:blue%7Clabel:S%7C62.107733,-145.541936&markers=size:tiny%7Ccolor:green%7CDelta+Junction,AK
&markers=size:mid%7Ccolor:0xFFFF00%7Clabel:C%7CTok,AK"&key=YOUR_API_KEY&signature=YOUR_SIGNATURE

Icone personalizzate

Anziché utilizzare le icone degli indicatori di Google, puoi usare le tue icone personalizzate. Le icone personalizzate vengono specificate utilizzando il descrittore icon nel parametro markers. Ad esempio:

markers=icon:URLofIcon|markerLocation

Specifica icon utilizzando un URL (che deve essere codificato in URL). Puoi utilizzare gli URL creati da servizi di accorciamento degli URL come https://goo.gl. La maggior parte dei servizi di accorciamento degli URL offre il vantaggio della codifica automatica degli URL.

Puoi specificare un punto di ancoraggio per l'icona personalizzata. Il punto di ancoraggio imposta il modo in cui viene posizionata l'icona rispetto alle posizioni markers specificate. Per impostazione predefinita, il punto di ancoraggio di un'icona personalizzata si trova in basso al centro dell'immagine dell'icona. Puoi specificare un punto di ancoraggio diverso utilizzando il descrittore anchor insieme a icon. Imposta anchor come un punto x,y dell'icona (ad esempio 10,5) o come allineamento predefinito utilizzando uno dei seguenti valori: top, bottom, left, right, center, topleft, topright, bottomleft o bottomright. Ad esempio:

markers=anchor:bottomright|icon:URLofIcon|markerLocation1|markerLocation2

Puoi utilizzare fino a cinque icone personalizzate univoche per richiesta. Questo limite non significa che tu sia limitato a 5 località contrassegnate sulla mappa. Ogni icona univoca può essere utilizzata con più di una posizione markers sulla mappa.

Formato icona:

• Le immagini delle icone possono essere in formato PNG, JPEG o GIF, anche se si consiglia di usare PNG.
• Le icone possono avere una dimensione massima di 4096 pixel (64 x 64 per le immagini quadrate).

Esempi di icone personalizzate

L'Esempio 1 crea icone personalizzate e posiziona le icone utilizzando gli ancoraggi.

https://maps.googleapis.com/maps/api/staticmap?&size=600x400&style=visibility:on
&style=feature:water%7Celement:geometry%7Cvisibility:on
&style=feature:landscape%7Celement:geometry%7Cvisibility:on
&markers=anchor:32,10%7Cicon:https://goo.gl/5y3S82%7CCanberra+ACT
&markers=anchor:topleft%7Cicon:http://tinyurl.com/jrhlvu6%7CMelbourne+VIC
&markers=anchor:topright%7Cicon:https://goo.gl/1oTJ9Y%7CSydney+NSW&key=YOUR_API_KEY
&signature=YOUR_SIGNATURE

L'Esempio 2 crea le stesse icone personalizzate dell'esempio 1, ma non imposta la posizione delle icone utilizzando gli ancoraggi, basandosi sull'ancoraggio predefinito in basso al centro.

https://maps.googleapis.com/maps/api/staticmap?&size=600x400&style=visibility:on
&style=feature:water%7Celement:geometry%7Cvisibility:on
&style=feature:landscape%7Celement:geometry%7Cvisibility:on
&markers=icon:https://goo.gl/5y3S82%7CCanberra+ACT
&markers=icon:http://tinyurl.com/jrhlvu6%7CMelbourne+VIC
&markers=icon:https://goo.gl/1oTJ9Y%7CSydney+NSW&key=YOUR_API_KEY&signature=YOUR_SIGNATURE

Percorsi API Maps Static

Il parametro path definisce un insieme di una o più località collegate da un percorso da sovrapporre all'immagine della mappa. Il parametro path prende un insieme di assegnazioni di valori (descrittori di percorso) nel seguente formato:

path=pathStyles|pathLocation1|pathLocation2|... e così via.

Tieni presente che entrambi i punti del percorso sono separati tra loro tramite il carattere barra verticale (|). Poiché sia le informazioni sullo stile sia quelle sui punti sono delimitate dalla barra verticale, le informazioni di stile devono apparire per prime in ogni descrittore del percorso. Quando il server dell'API Maps Static rileva una posizione nel descrittore del percorso, si presume che anche tutti gli altri parametri del percorso siano posizioni.

Stili percorso

L'insieme di descrittori di stile del percorso è costituito da una serie di assegnazioni di valori separate dal carattere barra verticale (|). Questo descrittore di stile definisce gli attributi visivi da utilizzare per la visualizzazione del percorso. Questi descrittori di stile contengono le seguenti assegnazioni chiave/valore:

• weight: (facoltativo) specifica lo spessore del percorso in pixel. Se non è impostato alcun parametro weight, il percorso verrà visualizzato con lo spessore predefinito (5 pixel).

• color: (facoltativo) specifica un colore come valore esadecimale a 24 bit (esempio: color=0xFFFFCC) o a 32 bit (esempio: color=0xFFFFCCFF) o dal set {black, brown, green, purple, yellow, blue, gray, orange, red, white}.

  Quando viene specificato un valore esadecimale a 32 bit, gli ultimi due caratteri specificano il valore della trasparenza alfa a 8 bit. Questo valore varia tra 00 (completamente trasparente) e FF (completamente opaco). Tieni presente che le trasparenze sono supportate nei percorsi, ma non sono supportate per gli indicatori.

• (Facoltativo) fillcolor: indica che il percorso contrassegna un'area poligonale e specifica il colore di riempimento da utilizzare come overlay all'interno di quell'area. L'insieme di località che segue non deve essere un ciclo "chiuso"; il server dell'API Maps Static unirà automaticamente il primo e l'ultimo punto. Tuttavia, tieni presente che qualsiasi tratto all'esterno dell'area coropletica non verrà chiuso a meno che non specifichi specificamente la stessa posizione di inizio e fine.
• geodesic: (facoltativo) indica che il percorso richiesto deve essere interpretato come una linea geodetica che segue la curvatura della Terra. Se il valore è false, il percorso viene visualizzato come una linea retta nello spazio dello schermo. Il valore predefinito è false.

Alcuni esempi di definizioni di percorsi:

• Linea blu sottile, opacità 50%: path=color:0x0000ff80|weight:1
• Linea rossa continua: path=color:0xff0000ff|weight:5
• Linea bianca spessa continua: path=color:0xffffffff|weight:10

Questi stili di percorso sono facoltativi. Se vuoi utilizzare gli attributi predefiniti, puoi saltare la definizione degli attributi del percorso; in questo caso, sarà composto il primo "argomento" del descrittore del percorso anziché il primo punto dichiarato (posizione).

Punti del percorso

Per disegnare un percorso, il parametro path deve essere passato anche di due o più punti. L'API Maps Static connetterà quindi il percorso lungo questi punti nell'ordine specificato. Ogni pathPoint è indicato nel parametro pathDescriptor separato dal carattere | (barra verticale).

L'esempio seguente definisce un percorso blu con un'opacità predefinita del 50% da Union Square NY a Times Square, NY.

Le specifiche del parametro path sono:

path=color:0x0000ff|weight:5|40.737102,-73.990318|40.749825,-73.987963|40.752946,-73.987384|40.755823,-73.986397

L'esempio seguente definisce lo stesso percorso invece di definire una linea rossa continua con un'opacità del 100%:

Le specifiche di questo parametro path sono:

path=color:0xff0000ff|weight:5|40.737102,-73.990318|40.749825,-73.987963|40.752946,-73.987384|40.755823,-73.986397

L'esempio successivo definisce un'area poligonale all'interno di Manhattan, passata una serie di incroci come località:

Le specifiche di questo parametro path sono:

path=color:0x00000000|weight:5|fillcolor:0xFFFF0033|8th+Avenue+%26+34th+St,New+York,NY|\
8th+Avenue+%26+42nd+St,New+York,NY|Park+Ave+%26+42nd+St,New+York,NY,NY|\
Park+Ave+%26+34th+St,New+York,NY,NY

Tieni presente che abbiamo impostato il percorso stesso in modo che sia invisibile e l'area poligonale con un'opacità del 15%.

Polilinee codificate

Anziché una serie di località, puoi dichiarare un percorso come una polilinea codificata utilizzando il prefisso enc: all'interno della dichiarazione della località dell'path.

L'esempio seguente illustra il percorso dell'Alaska Highway da Dawson Creek, BC a Delta Junction, AK con una polilinea codificata:

https://maps.googleapis.com/maps/api/staticmap
?size=400x400&center=59.900503,-135.478011&zoom=4
&path=weight:3%7Ccolor:orange%7Cenc:_fisIp~u%7CU}%7Ca@pytA_~b@hhCyhS~hResU%7C%7Cx@oig@rwg@amUfbjA}f[roaAynd@%7CvXxiAt{ZwdUfbjAewYrqGchH~vXkqnAria@c_o@inc@k{g@i`]o%7CF}vXaj\h`]ovs@?yi_@rcAgtO%7Cj_AyaJren@nzQrst@zuYh`]v%7CGbldEuzd@%7C%7Cx@spD%7CtrAzwP%7Cd_@yiB~vXmlWhdPez\_{Km_`@~re@ew^rcAeu_@zhyByjPrst@ttGren@aeNhoFemKrvdAuvVidPwbVr~j@or@f_z@ftHr{ZlwBrvdAmtHrmT{rOt{Zz}E%7Cc%7C@o%7CLpn~AgfRpxqBfoVz_iAocAhrVjr@rh~@jzKhjp@``NrfQpcHrb^k%7CDh_z@nwB%7Ckb@a{R%7Cyh@uyZ%7CllByuZpzw@wbd@rh~@%7C%7CFhqs@teTztrAupHhyY}t]huf@e%7CFria@o}GfezAkdW%7C}[ocMt_Neq@ren@e~Ika@pgE%7Ci%7CAfiQ%7C`l@uoJrvdAgq@fppAsjGhg`@%7ChQpg{Ai_V%7C%7Cx@mkHhyYsdP%7CxeA~gF%7C}[mv`@t_NitSfjp@c}Mhg`@sbChyYq}e@rwg@atFff}@ghN~zKybk@fl}A}cPftcAite@tmT__Lha@u~DrfQi}MhkSqyWivIumCria@ciO_tHifm@fl}A{rc@fbjAqvg@rrqAcjCf%7Ci@mqJtb^s%7C@fbjA{wDfs`BmvEfqs@umWt_Nwn^pen@qiBr`xAcvMr{Zidg@dtjDkbM%7Cd_@
&key=YOUR_API_KEY&signature=YOUR_SIGNATURE

Come per i percorsi standard, anche i percorsi delle polilinee codificati possono delimitare le aree poligonali se viene passato un argomento fillcolor al parametro path.

L'esempio seguente delinea un'area poligonale per Brooklyn, NY:

https://maps.googleapis.com/maps/api/staticmap
?size=400x400&center=40.653279,-73.959816&zoom=11
&path=fillcolor:0xAA000033%7Ccolor:0xFFFFFF00%7Cenc:}zswFtikbMjJzZ%7CRdPfZ}DxWvBjWpF~IvJnEvBrMvIvUpGtQpFhOQdKpz@bIx{A%7CPfYlvApz@bl@tcAdTpGpVwQtX}i@%7CGen@lCeAda@bjA%60q@v}@rfAbjA%7CEwBpbAd_@he@hDbu@uIzWcWtZoTdImTdIwu@tDaOXw_@fc@st@~VgQ%7C[uPzNtA%60LlEvHiYyLs^nPhCpG}SzCNwHpz@cEvXg@bWdG%60]lL~MdTmEnCwJ[iJhOae@nCm[%60Aq]qE_pAaNiyBuDurAuB }}Ay%60@%7CEKv_@?%7C[qGji@lAhYyH%60@Xiw@tBerAs@q]jHohAYkSmW?aNoaAbR}LnPqNtMtIbRyRuDef@eT_z@mW_Nm%7CB~j@zC~hAyUyJ_U{Z??cPvg@}s@sHsc@_z@cj@kp@YePoNyYyb@_iAyb@gBw^bOokArcA}GwJuzBre@i\tf@sZnd@oElb@hStW{]vv@??kz@~vAcj@zKa%60Atf@uQj_Aee@pU_UrcA
&key=YOUR_API_KEY&signature=YOUR_SIGNATURE

Aree visibili

Le immagini possono specificare un viewport specificando le località visibili tramite il parametro visible. Il parametro visible indica al servizio API Maps Static di creare una mappa in modo che le località esistenti rimangano visibili. Questo parametro può essere combinato con indicatori o percorsi esistenti per definire anche una regione visibile. La definizione di un'area visibile in questo modo elimina la necessità di specificare un livello di zoom esatto.

L'esempio seguente richiede una mappa centrata su Boston, Massachusetts, contenente sia il MIT che Harvard Square a Cambridge, MA:

https://maps.googleapis.com/maps/api/staticmap?center=Boston,MA
&visible=77+Massachusetts+Ave,Cambridge,MA%7CHarvard+Square,Cambridge,MA&size=512x512&key=YOUR_API_KEY&signature=YOUR_SIGNATURE

Posizionamento implicito della mappa

In genere, devi specificare i parametri URL center e zoom per definire la posizione e il livello di zoom della mappa generata. Tuttavia, se fornisci i parametri markers, path o visible, puoi consentire all'API Maps Static di determinare in modo implicito il livello corretto di centro e zoom, in base alla valutazione della posizione di questi elementi.

Se fornisci due o più elementi, l'API Maps Static determinerà un centro e un livello di zoom corretti, fornendo margini generosi per gli elementi contenuti. Questo esempio mostra una mappa contenente San Francisco, Oakland e San Jose, CA:

https://maps.googleapis.com/maps/api/staticmap?size=512x512&maptype=roadmap\
&markers=size:mid%7Ccolor:red%7CSan+Francisco,CA%7COakland,CA%7CSan+Jose,CA&key=YOUR_API_KEY&signature=YOUR_SIGNATURE

Immagini di dimensioni maggiori

Se hai bisogno di immagini di dimensioni superiori a 640 x 640 pixel (o 1280 x 1280 pixel con un valore di scala pari a 2), contatta il team di assistenza e fornisci le seguenti informazioni:

1. Il tuo caso d'uso e perché hai bisogno di immagini di grandi dimensioni.
2. Se hai preso in considerazione l'utilizzo di altre API Google Maps Platform (API Maps JavaScript, API Maps Embed, Maps SDK for Android o Maps SDK for iOS) e perché non soddisfano le tue esigenze.
3. Screenshot, simulazioni o esempi di come utilizzerai immagini di grandi dimensioni.
4. Utilizzo mensile stimato per immagini di grandi dimensioni.

Esamineremo la tua richiesta in base alle informazioni da te fornite e stabiliremo se il tuo caso d'uso è conforme ai Termini di servizio di Google Maps Platform.

La dimensione massima che possiamo fornire è 2048 x 2048 pixel.

Risoluzione dei problemi e assistenza

Per saperne di più sull'utilizzo dell'API Maps Static, consulta la pagina di assistenza.

L'API Maps Static può generare un errore o un avviso in caso di problemi. Controlla soprattutto gli avvisi se noti che manca qualcosa nella mappa. È buona norma verificare la presenza di avvisi prima di avviare una nuova applicazione. Tieni presente che gli avvisi potrebbero non essere immediatamente evidenti perché vengono visualizzati nell'intestazione HTTP. Per maggiori informazioni, consulta la guida agli errori e avvisi.