Inizia

Sviluppatori dello Spazio economico europeo (SEE)

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 determinate posizioni 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 nel suo 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 è rivolto 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. Fornisce un'introduzione all'utilizzo dell'API e materiale di riferimento sui parametri disponibili.

Prima di iniziare lo sviluppo con l'API Maps Static, esamina i requisiti di autenticazione (devi avere una chiave API) e le informazioni sull' utilizzo e sulla fatturazione dell'API (devi abilitare la fatturazione nel tuo progetto).

Parametri URL

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

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

Se l'accesso al tuo sito web avviene 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 tue richieste includono informazioni sensibili sugli utenti, ad esempio la loro posizione:

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

Che tu utilizzi HTTP o HTTPS, alcuni parametri URL sono obbligatori, mentre altri sono facoltativi. Come di consueto negli URL, tutti i parametri sono separati utilizzando il carattere e commerciale (&). L'elenco dei parametri e dei relativi valori possibili è riportato in questo documento.

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

Parametri di località

  • center (obbligatorio se non sono presenti indicatori) definisce il centro della mappa, equidistante da tutti i bordi della mappa. Questo parametro accetta una località come coppia {latitudine,longitudine} separata da virgole (ad es. "40.714728,-73.998672") o un indirizzo stringa (ad es. "city hall, new york, ny") che identifica una località univoca sulla superficie terrestre. Per maggiori informazioni, consulta 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 saperne di più, consulta 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 larga 500 pixel e alta 400 pixel. Le mappe con una larghezza inferiore a 180 pixel mostreranno un logo Google di dimensioni ridotte. Questo parametro è influenzato dal parametro scale; le dimensioni finali dell'output sono 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). Questo è utile quando sviluppi per display ad alta risoluzione. Il valore predefinito è 1. I valori accettati sono 1 e 2. Per saperne di più, consulta Valori di scalabilità.
  • format (facoltativo) definisce il formato dell'immagine risultante. Per impostazione predefinita, l'API Maps Static crea immagini PNG. Esistono diversi formati possibili, tra cui GIF, JPEG e PNG. Il formato da utilizzare dipende da come intendi presentare l'immagine. In genere, il formato JPEG offre una compressione maggiore, mentre i formati GIF e PNG offrono maggiori dettagli. Per saperne di più, consulta Formati delle immagini.
  • maptype (facoltativo) definisce il tipo di mappa da creare. Esistono diversi valori possibili per maptype, tra cui roadmap, satellite, hybrid e terrain. Per saperne di più, consulta Tipi di mappe dell'API Maps Static.
  • colorscheme (facoltativo) definisce la combinazione di colori per la mappa. I valori accettati sono light (predefinito) e dark. La combinazione di colori scuri si applica ai tipi di mappa roadmap e terrain. Per saperne di più, consulta Scopri di più su modalità e tipi di mappe.
  • 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 quel set di riquadri.
  • 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") di due caratteri. Per le regioni supportate, consulta i dettagli sulla copertura di Google Maps Platform.

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 saperne di più, consulta 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 indicatore con parametri separati dal carattere pipe (|). È possibile inserire più indicatori nello stesso parametro markers, purché abbiano lo stesso stile. Puoi aggiungere altri indicatori con stili diversi aggiungendo altri parametri markers. Tieni presente che se fornisci indicatori per una mappa, non è necessario specificare i parametri center e zoom (normalmente obbligatori). Per saperne di più, consulta Indicatori dell'API Maps Static.
  • path (facoltativo) definisce un singolo percorso di due o più punti collegati da sovrapporre all'immagine in 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: all'interno della dichiarazione della località del percorso. Puoi fornire percorsi aggiuntivi aggiungendo altri parametri path. Tieni presente che se fornisci un percorso per una mappa, non è necessario specificare i parametri center e zoom (normalmente obbligatori). Per saperne di più, consulta Percorsi dell'API Maps Static.
  • visible (facoltativo) specifica una o più località che devono rimanere visibili sulla mappa, anche se non verranno visualizzati indicatori o altri indicatori. Utilizza questo parametro per assicurarti che determinate caratteristiche o località della 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 a cui applicare lo stile e un insieme di operazioni di stile da applicare alle caratteristiche selezionate. Puoi fornire più stili aggiungendo altri parametri style. Per saperne di più, consulta la guida alle mappe con stili.

Parametri di chiave e firma

  • key (obbligatorio) ti consente di monitorare l'utilizzo delle API della tua applicazione nella 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 (consigliata) è una firma digitale utilizzata per verificare che qualsiasi sito che genera richieste di generazione utilizzando la tua chiave API sia autorizzato a farlo. Le richieste senza firma digitale potrebbero non riuscire. Per saperne di più, consulta Utilizza una firma digitale.

Limitazione delle dimensioni dell'URL

Gli URL dell'API Maps Static sono limitati a 16.384 caratteri. In pratica, probabilmente non avrai bisogno di URL più lunghi di questo, 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, 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 posizioni sulla mappa, sia per centrare la mappa sulla posizione corretta (utilizzando il parametro center) sia per posizionare eventuali segnaposto facoltativi (utilizzando il parametro markers) in 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) accettano più località. In questi casi, le località sono separate dal carattere pipe (|).

Latitudini e longitudini

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

I valori di longitudine si basano sulla distanza da Greenwich, in Inghilterra, dove si trova il meridiano di Greenwich. Poiché Greenwich si trova alla latitudine 51.477222, 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 località valida sulla superficie terrestre. Le latitudini possono assumere qualsiasi valore compreso tra -90 e 90, mentre i valori di longitudine possono assumere qualsiasi valore compreso tra -180 e 180. Se specifichi un valore di latitudine o longitudine non valido, la richiesta verrà rifiutata come richiesta non valida.

Indirizzi

La maggior parte delle persone non parla di latitudine e longitudine, ma indica le località utilizzando gli indirizzi. Il processo di conversione 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 in cui puoi fornire una latitudine/longitudine, puoi invece specificare una stringa che indica un indirizzo. Google geocodificherà l'indirizzo e fornirà 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 "City Hall, New York, NY" devono essere convertiti, ad esempio, in "City+Hall,New+York,NY".

Tieni presente che gli indirizzi possono riflettere posizioni esatte, come indirizzi stradali, 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 dell'indirizzo. Se hai dubbi su come un indirizzo potrebbe essere geocodificato, puoi testarlo utilizzando questa utilità di geocodifica.

L'esempio seguente genera un'immagine di mappa statica per Berkeley, in 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 visualizzazione corrente. Nella visualizzazione roadmap predefinita sono possibili livelli di zoom compresi tra 0 (il livello di zoom più basso, in cui l'intero mondo può essere visualizzato su una mappa) e 21+ (fino a strade e singoli edifici). 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 man mano che i dati si evolvono.

Google Maps imposta il livello di zoom 0 per includere l'intera Terra. Ogni livello di zoom successivo raddoppia la precisione sia nella dimensione orizzontale che in quella verticale. Per saperne di più su come eseguire questa operazione, consulta la documentazione dell'API Google Maps JavaScript.

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

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

Il seguente elenco mostra il livello di dettaglio approssimativo che puoi aspettarti di vedere a ogni livello di zoom:

  • 1: Dal 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 Faraway  Manhattan Up Close

Dimensioni delle immagini

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

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 con 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 di piccole dimensioni, 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

Mappa dell'equatore piccola

Valori di scala

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

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 soli 0,7 pollici, rendendo le etichette e le icone troppo piccole per essere lette; oppure
  • Ridimensiona (zoom) l'immagine per migliorare la leggibilità, ottenendo un'immagine sfocata o pixelata.
Troppo piccolo Troppo sfocata

Quando sviluppi per dispositivi mobili, puoi utilizzare il parametro scale dell'API per restituire immagini della mappa ad alta risoluzione che risolvono i problemi sopra indicati. Il valore scale viene moltiplicato per 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 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é quando vengono ridimensionate dal browser.

150x150 150x150&scale=2

Un'immagine di questo tipo funzionerà bene anche sui browser desktop, se inserita in un tag img o div con altezza e larghezza impostate utilizzando CSS. Il browser ridurrà l'immagine alle dimensioni corrette, senza perdita di qualità.

Questa tabella mostra tre diverse richieste di immagini.

  • Il primo è per un'immagine 100 x 100, senza alcun valore di scala specificato. Viene visualizzato correttamente sul computer, ma è troppo piccolo per essere letto su un dispositivo mobile.
  • La seconda raddoppia le dimensioni della mappa. Sul computer, il CSS la adatta all'elemento img 100 x 100 specificato, ma riducendo l'immagine, le strade e le etichette diventano troppo piccole. Sul dispositivo mobile, l'immagine ha le dimensioni corrette, ma anche in questo caso le strade e le 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 computer la ridimensiona perfettamente, in modo che sia indistinguibile dalla richiesta originale di 100 x 100, mentre il browser mobile beneficia della 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)

Per saperne di più sullo sviluppo per dispositivi mobili e display ad alta risoluzione, ti consigliamo di leggere i seguenti articoli:

Formati dell'immagine

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

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

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 dell'immagine più piccole, anche se lo fanno tramite una compressione "con perdita di dati" che potrebbe peggiorare l'immagine. gif, png8 e png32 forniscono una compressione senza perdita di dati.

La maggior parte delle immagini JPEG è progressiva, il che significa che caricano prima un'immagine più grossolana e perfezionano 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 di JPEG attualmente. Tuttavia, alcuni utilizzi di 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 della mappa stradale standard, come viene normalmente mostrata sul sito web di Google Maps. Se non viene specificato alcun valore maptype, l'API Maps Static fornisce i riquadri roadmap per impostazione predefinita.
  • satellite specifica un'immagine satellitare.
  • terrain specifica un'immagine della mappa in rilievo fisica, che mostra il terreno e la vegetazione.
  • hybrid specifica un'immagine ibrida tra l'immagine satellitare e quella della mappa stradale, che mostra un livello trasparente di strade principali e nomi di luoghi sull'immagine satellitare.

Puoi vedere la differenza tra i tipi di mappa stradale e di terreno 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 del rilievo di Manhattan

Le mappe ibride utilizzano immagini satellitari e caratteristiche principali della mappa stradale per creare una mappa combinata. I seguenti esempi mostrano i tipi di mappa satellitare e ibrida:

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 del rilievo di Manhattan

Mappe con stili

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

Indicatori

Il parametro markers definisce un insieme di uno o più indicatori (segnaposto sulla mappa) in un insieme di località. Ogni indicatore definito all'interno di una singola dichiarazione markers deve presentare 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 di indicatori) nel seguente formato:

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

L'insieme di markerStyles 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 dal carattere barra verticale (|).

Poiché sia le informazioni sullo stile che i dati sulla posizione sono delimitati dal carattere pipe, le informazioni sullo stile devono apparire per prime in qualsiasi descrittore di indicatore. Una volta che il server dell'API Maps Static rileva una località nel descrittore dell'indicatore, si presume che anche tutti gli altri parametri dell'indicatore siano località.

Stili marcatore

L'insieme 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 di questo descrittore di indicatori. Questi descrittori di stile contengono le seguenti assegnazioni di coppie chiave/valore:

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

  • color: (facoltativo) specifica un colore a 24 bit (ad esempio: color=0xFFFFCC) o un colore predefinito dell'insieme {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 nei segnaposto, anche se sono supportate per i percorsi.

  • label: (facoltativo) specifica un singolo carattere alfanumerico maiuscolo del set {A-Z, 0-9}. (Il requisito dei caratteri maiuscoli è una novità di questa versione dell'API). Tieni presente che i marker predefiniti e di dimensioni mid sono gli unici in grado di visualizzare un parametro alphanumeric-character. I marker tiny e small non sono in grado di visualizzare un carattere alfanumerico.

Scalabilità degli indicatori

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

Il limite di dimensioni in pixel delle immagini si applica 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 la scalabilità. Utilizza la scalabilità degli indicatori insieme alla scalabilità della mappa quando visualizzi mappe ad alta risoluzione.

Posizioni degli indicatori

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

Nota: se scegli di specificare le posizioni dei marker utilizzando un metodo che richiede la geocodifica, ad esempio stringhe di indirizzi o polilinee leggibili, la richiesta è limitata a un massimo di 15 marker. Questo limite si applica solo alle posizioni dei segnaposto 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 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 creerà automaticamente un'immagine contenente gli indicatori forniti. (Vedi Posizionamento implicito.)

Di seguito è riportato un esempio di dichiarazione di un indicatore. Tieni presente che 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 con l'etichetta "S" in corrispondenza di 62.107733, -145.5419, un indicatore verde piccolo in corrispondenza di "Delta Junction, AK" e un indicatore giallo di medie dimensioni con l'etichetta "C" in corrispondenza di "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'Alaska, indicatori diversi

Icone personalizzate

Anziché utilizzare le icone dei segnaposto di Google, puoi utilizzare 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 abbreviazione URL come https://goo.gl. La maggior parte dei servizi di abbreviazione URL offre il vantaggio di codificare automaticamente gli URL.

Puoi specificare un punto di ancoraggio per l'icona personalizzata. Il punto di ancoraggio imposta il modo in cui l'icona viene posizionata in relazione alle località 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 insieme a icon. Imposta anchor come 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 uniche per richiesta. Questa limitazione non significa che puoi contrassegnare solo 5 località sulla mappa. Ogni icona univoca può essere utilizzata con più di una località markers sulla mappa.

Formato icona:

  • Le immagini delle icone possono essere in formato PNG, JPEG o GIF, anche se è consigliato il formato 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 le ancore.

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 le ancora, basandosi sull'ancora predefinita 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, icone personalizzate diverse 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 accetta un insieme di assegnazioni di valori (descrittori di percorso) nel seguente formato:

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

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

Stili percorso

L'insieme di descrittori di stile del percorso è 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 viene impostato alcun parametro weight, il percorso verrà visualizzato con lo spessore predefinito (5 pixel).

  • color: (facoltativo) specifica un colore come valore esadecimale a 24 bit (ad esempio: color=0xFFFFCC) o a 32 bit (ad esempio: color=0xFFFFCCFF) oppure 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 tra 00 (completamente trasparente) e FF (completamente opaco). Tieni presente che le trasparenze sono supportate nei percorsi, ma non negli indicatori.

  • fillcolor: (facoltativo) indica che il percorso delimita 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 unirà automaticamente il primo e l'ultimo punto. Tuttavia, tieni presente che qualsiasi tratto all'esterno dell'area riempita non verrà chiuso, a meno che non specifichi la stessa posizione di inizio e di fine.
  • geodesic: (facoltativo) indica che il percorso richiesto deve essere interpretato come una linea geodetica che segue la curvatura della Terra. Se è false, il percorso viene visualizzato come una linea retta nello spazio dello schermo. Il valore predefinito è false.

Alcuni esempi di definizioni di percorsi:

  • Sottile linea blu, opacità 50%: path=color:0x0000ff80|weight:1
  • Linea rossa continua: path=color:0xff0000ff|weight:5
  • Linea bianca continua spessa: 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, il primo "argomento" del descrittore del percorso sarà costituito dal primo punto dichiarato (località).

Punti del percorso

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

L'esempio seguente definisce un percorso blu con 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, ma definisce 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, passando 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 abbiamo impostato il percorso in modo che sia invisibile e l'area poligonale in modo che abbia un'opacità del 15%.

Polilinee codificate

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

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

https://maps.googleapis.com/maps/api/staticmap
?size=400x400&center=59.900503,-135.478011&zoom=4
&path=weight:3%7Ccolor:orange%7Cenc:_fisIp~u%7CU%7D%7Ca@pytA_~b@hhCyhS~hResU%7C%7Cx@oig@rwg@amUfbjA%7Df%5BroaAynd@%7CvXxiAt%7BZwdUfbjAewYrqGchH~vXkqnAria@c_o@inc@k%7Bg@i%60%5Do%7CF%7DvXaj%5Ch%60%5Dovs@?yi_@rcAgtO%7Cj_AyaJren@nzQrst@zuYh%60%5Dv%7CGbldEuzd@%7C%7Cx@spD%7CtrAzwP%7Cd_@yiB~vXmlWhdPez%5C_%7BKm_%60@~re@ew%5ErcAeu_@zhyByjPrst@ttGren@aeNhoFemKrvdAuvVidPwbVr~j@or@f_z@ftHr%7BZlwBrvdAmtHrmT%7BrOt%7BZz%7DE%7Cc%7C@o%7CLpn~AgfRpxqBfoVz_iAocAhrVjr@rh~@jzKhjp@%60%60NrfQpcHrb%5Ek%7CDh_z@nwB%7Ckb@a%7BR%7Cyh@uyZ%7CllByuZpzw@wbd@rh~@%7C%7CFhqs@teTztrAupHhyY%7Dt%5Dhuf@e%7CFria@o%7DGfezAkdW%7C%7D%5BocMt_Neq@ren@e~Ika@pgE%7Ci%7CAfiQ%7C%60l@uoJrvdAgq@fppAsjGhg%60@%7ChQpg%7BAi_V%7C%7Cx@mkHhyYsdP%7CxeA~gF%7C%7D%5Bmv%60@t_NitSfjp@c%7DMhg%60@sbChyYq%7De@rwg@atFff%7D@ghN~zKybk@fl%7DA%7DcPftcAite@tmT__Lha@u~DrfQi%7DMhkSqyWivIumCria@ciO_tHifm@fl%7DA%7Brc@fbjAqvg@rrqAcjCf%7Ci@mqJtb%5Es%7C@fbjA%7BwDfs%60BmvEfqs@umWt_Nwn%5Epen@qiBr%60xAcvMr%7BZidg@dtjDkbM%7Cd_@
&key=YOUR_API_KEY&signature=YOUR_SIGNATURE

Alaska Highway

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

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

https://maps.googleapis.com/maps/api/staticmap
?size=400x400&center=40.653279,-73.959816&zoom=11
&path=fillcolor:0xAA000033%7Ccolor:0xFFFFFF00%7Cenc:%7DzswFtikbMjJzZ%7CRdPfZ%7DDxWvBjWpF~IvJnEvBrMvIvUpGtQpFhOQdKpz%40bIx%7BA%7CPfYlvApz%40bl%40tcAdTpGpVwQtX%7Di%40%7CGen%40lCeAda%40bjA%60q%40v%7D%40rfAbjA%7CEwBpbAd_%40he%40hDbu%40uIzWcWtZoTdImTdIwu%40tDaOXw_%40fc%40st%40~VgQ%7C%5BuPzNtA%60LlEvHiYyLs%5EnPhCpG%7DSzCNwHpz%40cEvXg%40bWdG%60%5DlL~MdTmEnCwJ%5BiJhOae%40nCm%5B%60Aq%5DqE_pAaNiyBuDurAuB%7D%7DAy%60%40%7CEKv_%40%3F%7C%5BqGji%40lAhYyH%60%40Xiw%40tBerAs%40q%5DjHohAYkSmW%3FaNoaAbR%7DLnPqNtMtIbRyRuDef%40eT_z%40mW_Nm%7CB~j%40zC~hAyUyJ_U%7BZ%3F%3FcPvg%40%7Ds%40sHsc%40_z%40cj%40kp%40YePoNyYyb%40_iAyb%40gBw%5EbOokArcA%7DGwJuzBre%40i%5Ctf%40sZnd%40oElb%40hStW%7B%5Dvv%40%3F%3Fkz%40~vAcj%40zKa%60Atf%40uQj_Aee%40pU_UrcA
&key=YOUR_API_KEY&signature=YOUR_SIGNATURE

Polilinea codificata di Brooklyn con firma

Viewport

Le immagini possono specificare un'area visibile 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 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 successivo 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

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 lasciare che l'API Maps Static determini implicitamente 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 ampi margini 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

Carta 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 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 di 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, modelli o esempi di come utilizzerai le immagini di grandi dimensioni.
  4. Il tuo utilizzo mensile stimato per le immagini di grandi dimensioni.

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

Le dimensioni massime che possiamo fornire sono 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 potrebbe generare un errore o un avviso quando si verifica un problema. In particolare, dovresti controllare se sono presenti avvisi se noti che manca qualcosa nella mappa. È inoltre consigliabile verificare la presenza di avvisi prima di lanciare una nuova applicazione. Tieni presente che gli avvisi potrebbero non essere immediatamente visibili perché vengono visualizzati nell'intestazione HTTP. Per saperne di più, consulta la guida agli errori e agli avvisi.