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 di indicatori facoltativi in punti sulla mappa. Puoi anche etichettare gli indicatori utilizzando caratteri alfanumerici.

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

Questo documento descrive il formato richiesto degli URL dell'API Maps Static e i parametri disponibili. Inoltre, fornisce 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 Maps Static in una pagina web o in un'applicazione mobile. Offre un'introduzione all'utilizzo dell'API e materiale di riferimento sui parametri disponibili.

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

Parametri URL

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

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

Se si accede al tuo sito web 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, ad esempio 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 nello standard per gli URL, tutti i parametri vengono separati utilizzando la e commerciale (&). L'elenco dei parametri e i relativi valori possibili sono enumerati in questo documento.

L'API Maps Static definisce le immagini delle mappe 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} separata da virgole (ad es. "40.714728,-73.998672") o come indirizzo stringa (ad es. "municipio, new york, ny") che identifica una posizione unica 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 è 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 un numero di pixel doppio rispetto a scale=1 mantenendo la stessa area di copertura e livello di dettaglio (ovvero, i contenuti della mappa non cambiano). Questa funzionalità è utile durante lo sviluppo di display ad alta risoluzione. Il valore predefinito è 1. I valori accettati sono 1 e 2. Per ulteriori informazioni, consulta Valori della scala.
  • format (facoltativo) definisce il formato dell'immagine risultante. Per impostazione predefinita, l'API Maps Static crea immagini PNG. Esistono diversi formati possibili, inclusi i tipi GIF, JPEG e PNG. Il formato da utilizzare dipende da come intendi presentare l'immagine. In genere i formati JPEG consentono una compressione maggiore, mentre i formati 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 di maptype possibili, tra cui roadmap, satellite, hybrid e terrain. Per ulteriori informazioni, consulta la sezione Maptype 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 del paese; se la lingua richiesta specifica non è supportata per il set di riquadri, verrà utilizzata la lingua predefinita per quel set di riquadri.
  • region (facoltativo) definisce i confini appropriati da visualizzare, in base alle sensibilità geo-politiche. Accetta un codice regione specificato come valore ccTLD a due caratteri ("dominio di primo livello"). Vedi i dettagli della copertura di Google Maps Platform per le regioni supportate.

Parametri funzionalità

  • map_id (facoltativo) specifica l'identificatore di una mappa specifica. L'ID mappa associa una mappa a un particolare stile o elemento 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 prevede una singola definizione di indicatore con parametri separati dal carattere barra verticale (|). È possibile posizionare più indicatori all'interno dello stesso parametro markers purché abbiano 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 ai indicatori API Static di Maps.
  • path (facoltativo) definisce un percorso singolo di due o più punti connessi da sovrapporre all'immagine nelle posizioni specificate. Questo parametro accetta una stringa di definizioni di punti separate dal carattere barra verticale (|) o una polilinea codificata che utilizza il prefisso enc: nella dichiarazione della posizione del percorso. Puoi fornire percorsi aggiuntivi aggiungendo altri parametri path. Tieni presente che se fornisci un percorso per una mappa, non devi specificare i parametri center e zoom (normalmente obbligatori). Per saperne di più, consulta la pagina 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 da applicare allo stile e un insieme di operazioni di stile da applicare alle caratteristiche selezionate. Puoi fornire più stili aggiungendo ulteriori 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 della tua applicazione in Google Cloud Console e garantisce che Google possa contattarti in merito alla tua applicazione, se necessario. Per saperne di più, consulta Utilizzare le chiavi API con l'API Maps Static.
  • signature (consigliato) è una firma digitale utilizzata per verificare che qualsiasi sito che genera richieste mediante la chiave API sia autorizzato a farlo. Le richieste senza firma digitale potrebbero non riuscire. Per ulteriori informazioni, consulta l'articolo Utilizzare una firma digitale.

Limitazione dimensioni URL

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

Utilizzo dei parametri

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

Specificare le località

L'API Maps Static deve essere in grado di identificare con precisione le posizioni 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) in corrispondenza delle posizioni 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 da una barra verticale (|).

Latitudine e longitudine

Latitudine e longitudine 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 i 6 decimali viene ignorata.

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

Greenwich, Inghilterra

I valori di latitudine e longitudine devono corrispondere a una posizione valida sulla faccia della Terra. La latitudine può avere qualsiasi valore compreso tra -90 e 90, mentre per la longitudine può essere qualsiasi valore compreso tra -180 e 180. Se specifichi un valore di latitudine o longitudine non valido, la richiesta verrà respinta.

Indirizzi

La maggior parte delle persone non parla in latitudine e longitudine; indicano le località utilizzando 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 tutti i parametri 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 formato URL, quindi indirizzi come "Municipio, New York, NY" devono essere convertiti, ad esempio, in "Museo+Città,New+York,NY".

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

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

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" numero intero che definisce la risoluzione della visualizzazione corrente. I livelli di zoom compresi tra 0 (il livello di zoom più basso, dove è possibile vedere tutto il mondo su una mappa) e 21+ (fino a strade e singoli 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 coprire l'intera Terra. Ogni livello di zoom successivo raddoppia la precisione sia in orizzontale che in 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 posizione, poiché i dati in alcune parti del globo sono più granulari che in altre.

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 12 e 14, rispettivamente:

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, insieme a center, definisce l'area di copertura di una mappa. Definisce inoltre le dimensioni di output della mappa in pixel, moltiplicate per il valore scale (che è 1 per impostazione predefinita).

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

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

Questo esempio richiede una "sezione" 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 mappa piccola, di 100 x 100 pixel, centrata sulla stessa area. 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 dell&#39;equatore piccolo

Valori scala

Il parametro size dell'API 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. Sul monitor di un computer LCD, che di solito mostra circa 100 pixel per pollice (ppi), una mappa di 200 x 200 misura circa 2 pollici per ogni dimensione.

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

  • Ridurre le dimensioni di un'immagine di 200 x 200 pixel a solo 0,7 pollici, visualizzare le etichette e le icone troppo piccole per essere lette; oppure
  • Ridimensiona (esegui lo zoom) l'immagine per migliorarne la leggibilità, ottenendo così 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 mappa a risoluzione più elevata che risolvono i problemi indicati in precedenza. Il valore scale viene moltiplicato per size per determinare le dimensioni effettive 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 senza scala specificata, 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é su schermi di dimensioni ridotte dal browser.

150x150 150x150&scala=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 ridimensiona l'immagine 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 piccola per essere letta su un dispositivo mobile.
  • Il secondo raddoppia le dimensioni della mappa. Sul desktop, il CSS lo inserisce nell'elemento img 100 x 100 specificato, ma quando ridimensiona l'immagine, strade ed etichette diventano troppo piccole. Sul dispositivo mobile, l'immagine ha le dimensioni corrette, ma anche 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 per dispositivi mobili e display ad alta risoluzione, consigliamo di leggere quanto segue:

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 (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

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

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

Tipi di mappe

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

  • roadmap (predefinito) specifica un'immagine standard della roadmap, come mostrato di solito 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 fisica in rilievo, che mostra il terreno e la 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

Mappa normale di Manhattan  Mappa dei rilievi di Manhattan

Le mappe ibride utilizzano immagini satellitari e funzionalità ben visibili della 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

Mappa satellitare di Manhattan  Mappa dei rilievi di Manhattan

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 (segnaposto sulla mappa) in un insieme di posizioni. Ogni indicatore definito all'interno di 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 utilizza un insieme di assegnazioni di valori (descrittori di indicatori) con il seguente formato:

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

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

Poiché sia le informazioni sullo stile che le informazioni sulla posizione sono delimitate da una barra verticale, le informazioni sullo stile devono apparire prima in ogni descrittore dell'indicatore. Quando il server API Maps Static rileva una posizione nel descrittore dell'indicatore, anche tutti gli altri parametri dell'indicatore vengono considerati posizioni.

Stili indicatore

L'insieme di descrittori di stile degli indicatori è una serie di assegnazioni di valori separate da una barra verticale (|). Questo descrittore di stile descrive gli attributi visivi da utilizzare quando vengono visualizzati gli indicatori all'interno del descrittore dell'indicatore. Questi descrittori di stile contengono le seguenti assegnazioni di chiave/valore:

  • size: (facoltativo) specifica le dimensioni dell'indicatore dal set {tiny, mid, small}. Se non è impostato alcun parametro size, l'indicatore verrà visualizzato nelle sue 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, ma sono supportate per i percorsi.

  • label: (facoltativo) specifica un singolo carattere alfanumerico maiuscole nel set {A-Z, 0-9}. Il requisito di caratteri in maiuscolo è una novità per questa versione dell'API. Tieni presente che gli indicatori con 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 produrre le dimensioni effettive di output dell'indicatore in pixel. Il valore predefinito di scala è 1; i valori accettati sono 1, 2 e 4.

Il limite per le dimensioni in pixel delle immagini viene applicato dopo l'applicazione del ridimensionamento. Ad esempio, se l'indicatore è impostato su scale:2, l'indicatore può essere più grande della dimensione massima di 4096 pixel, purché si riduca a meno di 4096 pixel dopo il ridimensionamento. Usa la scalabilità degli indicatori insieme alla scalabilità della mappa quando visualizzi 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à vengono separate dal carattere barra verticale (|).

Nota: se scegli di specificare le posizioni degli indicatori utilizzando un metodo che richiede la geocodifica, ad esempio stringhe di indirizzi o polilinee leggibili, 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. (vedi Posizionamento implicito).

Qui viene mostrata una dichiarazione di esempio dell'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

Tre codici postali di Brooklyn

Per definire gli indicatori con stili diversi, dobbiamo fornire più parametri markers. Questo insieme di parametri markers definisce tre indicatori: un indicatore blu con etichetta "S" a 62.107733, -145.5419, un piccolo indicatore verde a "Delta Junction, AK" e un indicatore giallo di medie dimensioni con 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

Tre città dell&#39;Alaska, indicatori diversi

Icone personalizzate

Invece di 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 come 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 è la parte inferiore centrale 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 puoi scegliere solo 5 località contrassegnate sulla tua mappa. Ogni icona univoca può essere utilizzata con più una posizione markers sulla mappa.

Formato icona:

  • Le immagini delle icone possono essere in formato PNG, JPEG o GIF, ma si consiglia di utilizzare 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 i 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

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

L'esempio 2 crea le stesse icone personalizzate dell'esempio 1, ma non imposta le posizioni delle icone utilizzando 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

Tre città australiane, diverse icone personalizzate con posizionamento predefinito.

Percorsi dell'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 l'uno dall'altro tramite il carattere barra verticale (|). Poiché le informazioni sullo stile e sui punti sono delimitate dalla barra verticale, le informazioni di stile devono apparire per prime in ogni descrittore del percorso. Quando il server API Maps Static rileva una posizione nel descrittore del percorso, vengono considerati anche tutti gli altri parametri del percorso.

Stili percorso

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

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

  • color: (facoltativo) specifica un colore come valore esadecimale a 24 bit (esempio: color=0xFFFFCC) o esadecimale a 32 bit (esempio: color=0xFFFFCCFF) o del 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.

  • fillcolor: (facoltativo) 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 loop "chiuso"; il server dell'API Maps Static unisce 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.

Ecco 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 preferisci utilizzare gli attributi predefiniti, puoi saltare la definizione degli attributi del percorso. In questo caso, sarà costituito 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 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.

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, invece definisce una linea rossa continua con un'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 seguente definisce un'area poligonale all'interno di Manhattan, attraversata da una serie di incroci come località:

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

Tieni presente che impostiamo 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: nella dichiarazione della località dell'path.

L'esempio seguente illustra il percorso dell'Alaska Highway da Dawson Creek, BC a Delta Junction, Alaska 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 dell&#39;Alaska

Come per i percorsi standard, anche i percorsi delle polilinee codificati possono delimitare 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

Polilinea codificata da Brooklyn con firma

Aree visibili

Le immagini possono specificare un viewport specificando le posizioni visibili utilizzando il parametro visible. Il parametro visible indica al servizio API Maps Static di creare una mappa in modo che le località esistenti restino 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 evita di dover specificare un livello di zoom esatto.

Il prossimo esempio richiede una mappa centrata su Boston, MA contenente sia il MIT sia 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

Normalmente, 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 lasciare che l'API Maps Static determini in modo implicito il centro e il livello di zoom corretti, 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 appropriati, 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

Cartina stradale

Dimensioni delle immagini più grandi

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 il motivo per cui 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. 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 è 2048 x 2048 pixel.

Risoluzione dei problemi e assistenza

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

L'API Maps Static potrebbe generare un errore o un avviso in caso di problemi. Se noti che manca qualcosa nella mappa, devi verificare la presenza di avvisi. Ti consigliamo inoltre di 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 ulteriori informazioni, consulta la guida a errori e avvisi.