Questa pagina è stata tradotta dall'API Cloud Translation.

Per iniziare

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 sulle posizioni sulla mappa. Puoi anche etichettare gli indicatori con caratteri alfanumerici.

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

Questo documento descrive il formato richiesto degli URL API di Maps Static e i parametri disponibili. Indica anche alcuni suggerimenti utili per specificare gli URL.

Prima di iniziare

Questo documento è destinato agli sviluppatori di siti web e dispositivi mobili che vogliono includere immagini dell'API Static di Maps in una pagina web o in un'applicazione mobile. Viene fornita un'introduzione all'utilizzo dell'API e del materiale di riferimento per i parametri disponibili.

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

Parametri URL

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

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

Se al tuo sito web si accede tramite HTTPS, devi caricare le immagini dell'API Maps Static anche su HTTPS per evitare avvisi di sicurezza del browser. HTTPS è consigliato anche se le richieste includono informazioni sensibili dell'utente, ad esempio la posizione di un utente:

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

Alcuni URL sono obbligatori, ad esempio HTTP o HTTPS, mentre alcuni sono facoltativi. Come avviene negli URL, tutti i parametri sono separati utilizzando la e commerciale (&). L'elenco dei parametri e i relativi valori possibili sono elencati in questo documento.

Importante: la discussione dei parametri URL utilizza esempi che per chiarezza sono forniti nel loro formato pre-escape. Prima di inviare qualsiasi richiesta all'API, i suoi parametri devono essere correttamente codificati tramite URL. Ad esempio, molti parametri utilizzano una barra verticale (|) come separatore, che deve essere codificato come %7C nell'URL finale, come nell'esempio rapido nella parte superiore di questo documento. Per saperne di più, consulta la pagina Creare un URL valido.

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

Parametri per località

center (obbligatorio se gli indicatori non sono presenti) definiscono il centro della mappa, equidistante da tutti i bordi della mappa. Questo parametro accetta una posizione come coppia { latitudine,longitudine} separata da virgola (ad esempio "40.714728,-73.998672") o da un indirizzo stringa (ad es. "municipio, new york, ny") che identifica una posizione univoca sulla faccia della terra. Per scoprire di più, 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 accetta 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 mappa. Questo parametro assume una stringa nel formato {horizontal_value}x{vertical_value}. Ad esempio, 500x400 definisce una mappa larga 500 pixel e alta 400 pixel. Nelle mappe di larghezza inferiore a 180 pixel verrà visualizzato un logo Google di dimensioni ridotte. Questo parametro è influenzato dal parametro scale; la dimensione finale dell'output è il prodotto dei valori di dimensione e scala.
scale (facoltativo) influisce sul numero di pixel restituiti. scale=2 restituisce il doppio dei pixel rispetto a scale=1 mantenendo la stessa area di copertura e lo stesso livello di dettaglio (ovvero i contenuti della mappa non cambiano). Ciò è utile per lo sviluppo di display ad alta risoluzione. Il valore predefinito è 1. I valori accettati sono 1 e 2. Per ulteriori informazioni, consulta Scalabilità dei valori.
format (facoltativo) definisce il formato dell'immagine risultante. Per impostazione predefinita, l'API Maps Static crea immagini PNG. Sono disponibili diversi formati, tra cui i tipi GIF, JPEG e PNG. Il formato da utilizzare dipende dal modo in cui intendi presentare l'immagine. JPEG generalmente consente una maggiore compressione, mentre GIF e PNG forniscono maggiori dettagli. Per maggiori informazioni, consulta la pagina Formati di immagini.
maptype (facoltativo) definisce il tipo di mappa da creare. Esistono diversi possibili valori di tipi di mappa, tra cui roadmap, satellite, hybrid e terrain. Per ulteriori informazioni, consulta la sezione Maptypes dell'API Static Maps.
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 del paese; se la lingua specifica richiesta non è supportata per il riquadro, verrà utilizzata la lingua predefinita per quel riquadro.
region (facoltativo) definisce i bordi appropriati da visualizzare, in base alla sensibilità geopolitica. Accetta un codice di area geografica specificato come valore ccTLD ("dominio di primo livello") a due caratteri. Consulta i dettagli di copertura di Google Maps Platform per le regioni supportate.

Parametri delle funzionalità

map_id (facoltativo) specifica l'identificatore di una mappa specifica. L'ID mappa associa una mappa a uno stile o a una funzionalità specifici 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 in posizioni specificate. Questo parametro accetta una definizione di un singolo indicatore con parametri separati dalla barra verticale (|). È possibile inserire più indicatori all'interno dello stesso parametro markers, purché mostrino lo stesso stile. Puoi aggiungere ulteriori indicatori di stili diversi aggiungendo ulteriori parametri markers. Tieni presente che se fornisci indicatori per una mappa, non è necessario specificare i parametri center e zoom (normalmente obbligatori). Per ulteriori informazioni, consulta la pagina Indicatori API statici di Maps.
path (facoltativo) definisce un singolo percorso di due o più punti di contatto che si sovrappongono all'immagine in posizioni specificate. Questo parametro accetta una stringa di definizioni di punti separate dal carattere della barra verticale (|) o da una polilinea codificata utilizzando il prefisso enc: all'interno della dichiarazione relativa alla posizione del percorso. Puoi fornire percorsi aggiuntivi aggiungendo ulteriori 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 Percorsi API Maps Static.
visible (facoltativo) specifica una o più località che devono rimanere visibili sulla mappa, anche se non vengono 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 gli argomenti feature e element che identificano le caratteristiche nello stile e un insieme di operazioni di stile da applicare alle funzionalità selezionate. Puoi fornire più stili aggiungendo ulteriori parametri style. Per ulteriori informazioni, consulta la guida alle mappe con stile.

Parametri chiave e firma

key (obbligatorio) ti consente di monitorare l'utilizzo dell'API nella tua console Google Cloud e garantisce che Google possa contattarti in merito alla tua applicazione, se necessario. Per saperne di più, consulta Utilizza le chiavi API con l'API Maps Static.
signature (consigliato) è una firma digitale utilizzata per verificare che qualsiasi sito che genera richieste utilizzando la 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

Gli URL dell'API Static di Maps non possono superare 8192 caratteri. In pratica, probabilmente non avrai bisogno di URL più lunghi di questo, a meno che non generi mappe complicate 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 con parametri. 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 posizioni sulla mappa, sia per rendere la mappa la posizione corretta (utilizzando il parametro center), sia per posizionare eventuali segnaposto facoltativi (utilizzando il parametro markers) nelle posizioni sulla mappa. L'API Maps Static utilizza numeri (valori di latitudine e longitudine) o stringhe (indirizzi) per specificare tali località. Questi valori identificano una località con geocodifica.

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

Latitudini e longitudini

Le latitudini e le longitudini sono definite mediante numeri all'interno di una stringa di testo separata da virgole con una precisione di sei cifre decimali. Ad esempio, "40.714728,-73.998672" è un valore geografico valido. La precisione oltre le sei cifre decimali viene ignorata.

I valori di longitudine si basano sulla distanza da Greenwich, in Inghilterra, che ospita il primo meridiano. Poiché Greenwich si trova a 51,477222 di latitudine, possiamo inserire un valore center di 51.477222,0 per centrare la mappa su Greenwich:

Greenwich, Inghilterra

I valori di latitudine e longitudine devono corrispondere a una posizione valida sulla superficie del pianeta. Le latitudini possono contenere qualsiasi valore compreso tra -90 e 90, mentre i valori della longitudine possono assumere qualsiasi valore compreso tra -180 e 180. Se specifichi un valore di longitudine o latitudine non valido, la richiesta verrà rifiutata come non valida.

Indirizzi

La maggior parte delle persone non parla in latitudine e longitudine; indicano le località usando 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 al posto tuo se fornisci indirizzi validi.

In qualsiasi parametro in cui potresti specificare una latitudine/longitudine, puoi invece specificare una stringa che indica un indirizzo. Google geocodifica l'indirizzo e fornisce al servizio API statico di Maps un valore di latitudine/longitudine da utilizzare per posizionare gli indicatori o specificare le località. La stringa deve essere con codifica URL, quindi ad esempio "City Hall, New York, NY" devono essere convertiti in "City+Hall,New+York,NY".

Tieni presente che gli indirizzi possono indicare località precise, ad esempio indirizzi, polilinee come percorsi con nome oppure aree poligonali come città, paesi o parchi nazionali. Per i risultati polilineari e poligonali, il server API Maps Static utilizza il punto centrale della linea/area come centro indirizzi. Se hai dubbi sul modo in cui un indirizzo potrebbe geocodificare, puoi testare l'indirizzo utilizzando questa utilità di codifica.

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

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

Berkeley, CA

Livelli di zoom

Le mappe su Google Maps hanno un "livello di zoom" intero che definisce la risoluzione della vista corrente. I livelli di zoom tra 0 (il livello di zoom più basso, in cui il mondo intero può essere visto su una mappa) e 21+ (fino alle strade e singoli edifici) sono possibili nella visualizzazione predefinita di roadmap. I contorni di un edificio, dove disponibili, vengono visualizzati sulla mappa intorno al livello di zoom 17. Questo valore varia da un'area all'altra e può cambiare nel tempo man mano che i dati si evolvono.

Google Maps imposta il livello di zoom 0 per includere l'intero pianeta. Ogni livello di zoom riuscito raddoppia la precisione in entrambe le 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 del pianeta. I livelli di zoom variano a seconda della località, poiché i dati di alcune parti del globo sono più granulari che in altre.

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

L'elenco seguente 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 con 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

Manhattan lontano Manhattan da vicino

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, se moltiplicate 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 1280x1280 pixel)

Questo esempio richiede una "fetta" della terra all'equatore al 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

Equatore

Questo esempio richiede una piccola mappa, di dimensioni 100 x 100 pixel, centrata sulla stessa area geografica. 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

Mappa equatore piccola

Valori in scala

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

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

Riduci le dimensioni di un'immagine di 200 x 200 pixel a soli 0,7 pollici, poiché le etichette e le icone di rendering sono troppo piccole per essere lette; oppure
Scala (zoom) l'immagine per migliorarne la leggibilità, ottenendo un'immagine sfocata o pixelata.

Troppo piccolo	Troppo confusa

Durante lo sviluppo di dispositivi mobili, puoi utilizzare il parametro scale dell'API per restituire immagini mappa ad alta risoluzione che risolvono i problemi sopra indicati. Il valore scale viene moltiplicato con size per determinare le dimensioni effettive dell'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 scalabilità pari a 2 restituirà la stessa area di copertura della mappa di una richiesta per cui non è stata specificata alcuna scala, ma con il doppio dei pixel in ogni dimensione. Sono incluse strade ed etichette, in modo che siano leggibili sugli schermi ad alta risoluzione e di piccole dimensioni, nonché quando vengono ridimensionate dal browser.

150x150	150x150&scale=2

Questa immagine avrà un buon rendimento anche sui browser per desktop, quando verrà inserita in un tag img o div con altezza e larghezza impostate utilizzando CSS. Il browser ridurrà le dimensioni corrette dell'immagine senza alcuna perdita di qualità.

Questa tabella mostra tre diverse richieste di immagini.

Il primo è per un'immagine di 100 x 100, senza alcun valore di scala specificato. Il file viene visualizzato correttamente sul desktop, ma è troppo piccolo per essere letto su un dispositivo mobile.
Il secondo raddoppia le dimensioni della mappa. Sul desktop, il CSS si adatta all'elemento img 100x100 specificato, ma le dimensioni dell'immagine, delle strade e delle etichette diventano troppo ridotte. Sul dispositivo mobile, l'immagine è della dimensione giusta, ma ancora una volta strade ed etichette sono illeggibili.
La terza richiesta riguarda una mappa 100x100 con scale=2. L'immagine viene restituita con 200 px di dettagli; il desktop esegue lo scale down perfettamente, in modo che sia indistinguibile dalla richiesta 100x100 originale, mentre il browser mobile trae vantaggio dalla risoluzione aggiuntiva restituita dall'API.

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

Suggerimento: le piattaforme per dispositivi mobili, come Android e iOS, consentono alle app di supportare schermi ad alta risoluzione specificando immagini separate per ogni risoluzione. Il parametro scala consente di richiedere facilmente un'immagine mappa per una schermata a risoluzione standard e la mappa corrispondente per una schermata ad alta risoluzione, semplicemente impostando rispettivamente scale=1 e scale=2.

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

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

Formati dell'immagine

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

png8 o png (impostazione predefinita) 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 progressivo.

Questi esempi richiedono le 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

In genere jpg e jpg-baseline forniscono le dimensioni più piccole per le immagini, ma lo fanno mediante una compressione "perdita" che può peggiorare l'immagine. gif, png8 e png32 offrono una compressione senza perdita di dati.

La maggior parte delle immagini JPEG è progressiva, ovvero carica un'immagine più vecchia e perfeziona la risoluzione dell'immagine man mano che aumentano i dati. Questo consente di caricare rapidamente le immagini nelle pagine web e al momento è l'uso più diffuso di JPEG. Tuttavia, alcuni utilizzi dei file JPEG richiedono immagini non progressive (base di riferimento). In questi casi, puoi utilizzare il formato jpg-baseline, che non è di tipo progressivo.

Tipi di mappe

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

roadmap (impostazione predefinita) specifica un'immagine standard per la roadmap, come di consueto, sul sito web di Google Maps. Se non viene specificato un valore maptype, l'API Maps Static gestisce roadmap riquadri per impostazione predefinita.
satellite specifica un'immagine satellitare.
terrain specifica un'immagine fisica della mappa in rilievo, che mostra il rilievo e la vegetazione.
hybrid specifica un ibrido dell'immagine del satellite e della roadmap, che mostra un livello trasparente di strade principali e nomi di luoghi sull'immagine satellitare.

In questo esempio di codice puoi vedere la differenza tra la roadmap e i tipi di rilievo.

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

Mappa normale di Manhattan Mappa dei rilievi di Manhattan

Le mappe ibride utilizzano immagini satellitari e funzionalità di roadmap importanti per creare una mappa combinata. Gli esempi riportati di seguito 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

Mappa satellitare di Manhattan Mappa dei rilievi di Manhattan

Mappe con stile

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

Indicatori

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

Il parametro markers prende l'insieme di assegnazioni di valori (descrittori dell'indicatore) del seguente formato:

markers=markerStyles|markerLocation1| markerLocation2|... ecc.

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

Poiché sia le informazioni sullo stile che le informazioni sulla posizione sono delimitate tramite il carattere della barra verticale, le informazioni sullo stile devono apparire per prime in qualsiasi descrittore dell'indicatore. Quando il server API Maps Static rileva una località nel descrittore dell'indicatore, si presume che anche tutti gli altri parametri dell'indicatore siano località.

Stili degli indicatori

L'insieme dei descrittori dello stile dell'indicatore è una serie di assegnazioni di valori separate dal carattere barra verticale (|). Questo descrittore dello stile definisce gli attributi visivi da utilizzare quando vengono visualizzati gli indicatori in questo descrittore. Questi descrittori dello stile contengono le seguenti assegnazioni di coppie chiave-valore:

size: (facoltativo) specifica la dimensione dell'indicatore dal set {tiny, mid, small}. Se non è impostato alcun parametro size, l'indicatore viene visualizzato con le dimensioni predefinite (normali).
color: (facoltativo) specifica un colore a 24 bit (esempio: color=0xFFFFCC) o un colore predefinito dal set {black, brown, green, purple, yellow, blue, gray, orange, red, white}.
Tieni presente che le lucidi (specificate utilizzando valori esadecimali a 32 bit) non sono supportate negli indicatori, anche se sono supportate per i percorsi.
label: (facoltativo) specifica un singolo carattere alfanumerico maiuscolo dal set {A-Z, 0-9}. (il requisito per i caratteri maiuscoli è una nuova versione di questa API). Tieni presente che gli indicatori predefiniti e di dimensioni mid sono gli unici indicatori in grado di visualizzare un parametro alphanumeric-character. Gli indicatori tiny e small non sono in grado di visualizzare un carattere alfanumerico.

Ridimensionamento indicatore

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

Il limite per le dimensioni dei pixel sulle immagini viene applicato dopo l'applicazione della scalabilità. Ad esempio, se l'indicatore è impostato su scale:2, può essere più grande della dimensione massima di 4096 pixel, purché si riduca a meno di 4096 pixel dopo l'applicazione della scala. Utilizza il ridimensionamento dell'indicatore in combinazione con il ridimensionamento della mappa quando vengono mostrate mappe a risoluzione più elevata.

Posizione 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 longitudine/longitudine o come indirizzi. Queste località sono separate utilizzando il carattere della barra verticale (|).

Nota: se scegli di specificare le posizioni degli indicatori utilizzando un metodo che richiede la geocodifica, come stringhe di indirizzi o polilinee leggibili dalla persona, 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 coordinate di latitudine/longitudine.

I parametri di posizione definiscono la posizione dell'indicatore sulla mappa. Se la posizione è fuori dalla mappa, quell'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 API Maps Static crea automaticamente un'immagine contenente gli indicatori forniti. (consulta la sezione Posizionamento implicito.)

Di seguito è riportato un esempio di dichiarazione dell'indicatore. Definiamo un insieme di stili e tre località:

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

Tre codici postali di Brooklyn

Per definire indicatori con stili diversi, dobbiamo fornire più parametri markers. Questo insieme di parametri markers definisce tre indicatori: un indicatore blu denominato "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 nell'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

Tre città dell'Alaska, diversi indicatori

Icone personalizzate

Invece di utilizzare le icone di Google, puoi decidere di usare icone personalizzate. Le icone personalizzate vengono specificate utilizzando il descrittore icon nel parametro markers. Ad esempio:

markers=icon:URLofIcon|markerLocation

Specifica la icon utilizzando un URL (che deve essere codificato in URL). Puoi utilizzare gli URL creati da servizi di abbreviazione degli URL come https://goo.gl. La maggior parte dei servizi di abbreviazione 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 come viene posizionata l'icona in relazione alle posizioni markers specificate. Per impostazione predefinita, il punto di ancoraggio di un'icona personalizzata è il centro inferiore dell'immagine dell'icona. Puoi specificare un punto di ancoraggio diverso utilizzando il descrittore anchor in combinazione con icon. Imposta anchor come punto x, y dell'icona (ad es. 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. Ciò non significa che sulla mappa sia limitato solo a cinque località contrassegnate. 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, sebbene sia consigliato l'utilizzo di 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 le posiziona utilizzando gli ancoraggi.

http://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

Tre città australiane, diverse icone personalizzate posizionate con ancoraggi.

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

http://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 di overlay sull'immagine mappa. Il parametro path prende l'insieme di assegnazioni di valori (descrittori del percorso) del seguente formato:

path=pathStyles|pathLocation1|pathLocation2|... ecc.

Tieni presente che entrambi i punti del percorso sono separati l'uno dall'altro utilizzando il carattere della barra verticale (|). Poiché sia le informazioni sullo stile che le informazioni sui punti sono delimitate tramite il carattere della barra verticale, le informazioni di stile devono apparire per prime in qualsiasi descrittore del percorso. Quando il server API Maps Static rileva una località nel descrittore del percorso, si presume che anche tutti gli altri parametri del percorso siano località.

Stili percorso

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

weight: (facoltativo) specifica lo spessore del percorso in pixel. Se non è impostato alcun parametro weight, il percorso verrà visualizzato nello spessore predefinito (5 pixel).
color: (facoltativo) specifica un colore come valore a 24 bit (esempio: color=0xFFFFCC) o esadecimale 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 di trasparenza alfa a 8 bit. Questo valore varia da 00 (totalmente trasparente) a FF (completamente opaco). Tieni presente che le lucidi sono supportate nei percorsi, ma non sono supportati per gli indicatori.
(Facoltativo) fillcolor: indica che il percorso contrassegna un'area poligonale e specifica il colore di riempimento da usare come overlay all'interno dell'area. L'insieme di località che seguono non deve essere un loop "chiuso". Il server API di Maps Static si unirà automaticamente al primo e all'ultimo punto. Tuttavia, tieni presente che qualsiasi tratto all'esterno dell'area colorata non verrà chiuso, a meno che non specifichi specificatamente la stessa posizione di partenza e di arrivo.
geodesic: (facoltativo) indica che il percorso richiesto deve essere interpretato come una linea geodetica che segue la curvatura della terra. Se il valore è falso, il percorso viene visualizzato come una linea retta nello spazio sullo schermo. Il valore predefinito è false.

Ecco alcuni esempi di definizioni di percorso:

Linea blu sottile, opacità del 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 attributi predefiniti, puoi saltare la definizione degli attributi del percorso; in questo caso, il primo "argomento" del descrittore di percorso sarà composto anziché dal primo punto dichiarato (località).

Punti del percorso

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

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

Percorso da Union Sq a Times Sq

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 anziché definire una linea rossa continua con opacità del 100%:

Percorso da Union Sq a Times Sq

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, ha superato una serie di incroci come luoghi:

Percorso da Union Sq a Times Sq

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

Tenete presente che il percorso stesso è invisibile e l'area poligonale ha un'opacità del 15%.

Polilinee codificate

Invece di una serie di località, puoi dichiarare un percorso come polilinea codificata utilizzando il prefisso enc: nella dichiarazione relativa alla posizione di path.

L'esempio seguente delinea il percorso dell'Alaska 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

Autostrada Alaska

Come con i percorsi standard, anche i percorsi polilineati codificati possono demarcare le aree poligonali se un argomento fillcolor viene passato 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

Brooklyn Encoded Polyline con firma

Area visibile

Le immagini possono specificare un'area visibile specificando le località visibili utilizzando 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 impedisce di specificare un livello esatto di zoom.

L'esempio successivo richiede una mappa centrata su Boston, MA contenente sia 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

Mappa di Cambridge

Posizionamento implicito della mappa

Solitamente, devi specificare i parametri URL center e zoom per definire la posizione e il livello di zoom della mappa generata. Tuttavia, se fornisci parametri markers, path o visible, puoi lasciare che l'API Maps Static determini correttamente il livello centrale e di zoom, in base alla valutazione della posizione di questi elementi.

Se fornisci due o più elementi, l'API Maps Static determinerà un centro e uno zoom adeguati, 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

Mappa stradale

Dimensioni delle immagini più grandi

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

Il tuo caso d'uso e perché ti servono immagini di grandi dimensioni.
Se hai considerato di utilizzare altre API di Google Maps Platform (API Maps JavaScript, API Maps Embed, SDK Maps per Android o SDK Maps per iOS) e perché non soddisfano le tue esigenze.
Screenshot, simulazioni o esempi di come utilizzerai immagini di grandi dimensioni.
Il tuo utilizzo mensile stimato per le 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 è 2048x2048 pixel.

Risoluzione dei problemi e assistenza

Per ulteriori informazioni sull'utilizzo dell'API Maps Static, consultate la pagina dell'assistenza.

Quando si verifica un problema, l'API Maps Static potrebbe restituire un errore o un avviso. Dovresti verificare gli avvisi in particolare se noti che manca qualcosa sulla mappa. Inoltre, è una buona idea verificare la presenza di avvisi prima di avviare una nuova applicazione. Tieni presente che gli avvisi potrebbero non essere immediatamente evidenti perché compaiono nell'intestazione HTTP. Per saperne di più, consulta la guida agli errori e avvisi.