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 parametroscale
; 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 ascale=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 sono1
e2
. 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 cuiroadmap
,satellite
,hybrid
eterrain
. 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 parametromarkers
possono essere posizionati più indicatori purché mostrino lo stesso stile. Puoi aggiungere ulteriori indicatori di stili diversi aggiungendo altri parametrimarkers
. Tieni presente che se fornisci indicatori per una mappa, non devi specificare i parametricenter
ezoom
(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 prefissoenc:
all'interno della dichiarazione della posizione del percorso. Puoi fornire percorsi aggiuntivi aggiungendo altri parametripath
. Tieni presente che se fornisci un percorso per una mappa, non è necessario specificare i parametricenter
ezoom
(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 argomentifeature
eelement
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 parametristyle
. 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" ewidth="100px" neltag 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
opng
(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 valoremaptype
, l'API Maps Static pubblicaroadmap
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 parametrosize
, 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 emid
sono gli unici indicatori in grado di visualizzare un parametroalphanumeric-character
. Gli indicatoritiny
esmall
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 parametroweight
, 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) eFF
(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¢er=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¢er=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:
- Il tuo caso d'uso e perché hai bisogno di immagini di grandi dimensioni.
- 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.
- Screenshot, simulazioni o esempi di come utilizzerai immagini di grandi dimensioni.
- 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.