Collega un tuo servizio di mappe a map.army

map.army viene fornito con un elenco fisso di mappe di sfondo. Se la tua organizzazione gestisce un proprio servizio di mappe — quello di un’agenzia cartografica nazionale, un servizio geospaziale della difesa, o un tile server sulla tua rete — puoi far disegnare quello all’app al suo posto, senza alcuna installazione, semplicemente inserendolo nel link.

Un indirizzo di map.army può portare un parametro mapType che descrive un servizio di mappe. Quando l’app lo trova, quel servizio diventa la mappa di sfondo:

map.army che disegna un servizio WMTS OpenStreetMap personalizzato come mappa di sfondo, caricato da un link mapType

Sostituisce l’elenco integrato invece di aggiungersi ad esso. La riga Tipo di mappa scompare del tutto da Opzioni → Impostazioni mappa, perché con un solo servizio non c’è più alcuna scelta da offrire:

Menu a tendina Tipo di mappa di map.army espanso, con Satellite, Terrain, Hybrid, Roads, Roadmap e OSM

L’effetto dura solo quanto il link. Non viene salvato nulla: apri di nuovo map.army senza il parametro e tornano le mappe abituali. Questo lo rende un buon modo per consegnare a qualcuno una mappa funzionante della tua zona — invii il link e non serve alcuna configurazione da parte loro — ma un modo scadente per cambiare la tua impostazione predefinita, perché ogni visita richiede lo stesso link.

Suggerimento: Non c’è alcun campo nel pannello Opzioni per l’indirizzo di un servizio di mappe. Il link è l’unico modo per farlo nell’app ospitata; se vuoi che i tuoi servizi siano l’elenco, in modo permanente e selezionabili come qualsiasi altra mappa, questo si configura quando viene installata una distribuzione — vedi Gratuito vs Pro.

Apri il link due volte — il primo caricamento non mostra alcuna mappa

map.army alla prima visita di un link mapType: barra degli strumenti funzionante, area mappa completamente vuota

Alla prima visita in un dato browser, un link mapType al momento non mostra alcuna mappa di sfondo — una barra degli strumenti funzionante sopra una tela vuota, esattamente come sopra. Ricarica la pagina e il tuo servizio compare. Tutto il resto del link funziona normalmente.

Misurato il 2026-09-17 sulla build 6.1.1/7489: il primo caricamento ha effettuato zero richieste al servizio di tile; un ricaricamento dello stesso indirizzo ne ha effettuate 19 e ha disegnato la mappa.

Suggerimento: Invia il link con l’indicazione “aprilo, poi ricarica una volta”. Chi apre il tuo link, vede una mappa vuota e chiude la scheda non ha modo di sapere che qualcosa non ha funzionato — non compare alcun messaggio di errore. Finché questo non viene corretto nell’app, il ricaricamento è la soluzione temporanea, ed è utile dirlo esplicitamente a chi riceve il link.

WMTS o WMS — come distinguerli

Sono entrambi modi standard con cui un server pubblica immagini di mappe, e quale dei due hai decide quali proprietà ti servono. La documentazione del tuo fornitore lo indica, ma è di solito l’indirizzo stesso a tradirlo.

  • Un servizio WMTS (Web Map Tile Service) serve tile quadrate pre-tagliate. Il suo indirizzo è un modello con segnaposto per la posizione della tile — {z} per il livello di zoom, {x} e {y} per colonna e riga, come in https://tiles.example.org/{z}/{x}/{y}.png. È il più veloce dei due perché il server ha già fatto il lavoro in anticipo.
  • Un servizio WMS (Web Map Service) disegna un’immagine su richiesta. Il suo indirizzo è un semplice endpoint, e devi anche indicare quali livelli vuoi e in quale formato immagine, perché un endpoint WMS pubblica tipicamente molti livelli.

Se ti viene fornito un URL GetCapabilities, è WMS. Se ti viene fornito un indirizzo con {z}/{x}/{y} al suo interno, è WMTS.

Il JSON

Il valore di mapType è un oggetto JSON. Il più corto utilizzabile per WMTS richiede solo un tipo e un indirizzo:

{"type":"wmts","url":"https://tiles.example.org/{z}/{x}/{y}.png"}

Uno per WMS ne richiede tre, perché un semplice endpoint non basta per disegnare nulla:

{"type":"wms","url":"https://wms.example.org/?","layers":"topo-colour","format":"image/png"}

Tutto il resto è opzionale ed è descritto più sotto. Se sbagli le proprietà richieste, l’app ignora silenziosamente l’intero parametro — vedi Quando il link non funziona.

Codificarlo nell’indirizzo

Il JSON contiene caratteri non sicuri in un URL — virgolette, parentesi graffe, virgole — quindi l’oggetto deve essere codificato in percent-encoding prima di inserirlo nell’indirizzo. Qualsiasi libreria HTTP o linguaggio di scripting lo fa per te. Nella console del browser:

const json = JSON.stringify(mapTypeObject);
const query = new URLSearchParams({ mapType: json }).toString();
const link = `https://www.map.army/?${query}`;

Incollare il JSON grezzo nella barra degli indirizzi a volte sembra funzionare, perché i browser codificano alcuni caratteri al posto tuo — ma non tutti, e quelli che tralasciano falliscono silenziosamente. Codificalo correttamente.

Ogni proprietà in dettaglio

Proprietà comuni a entrambi i tipi di servizio

ProprietàSignificatoObbligatoria
typewmts o wms. Qualsiasi altro valore e il parametro viene ignorato.Sì
urlL’indirizzo del servizio. Per WMTS un modello XYZ contenente {z}, {x} e {y}, più {s} se usi i sottodomini. Per WMS l’endpoint.Sì
extentL’area effettivamente coperta dal servizio, come [xmin, ymin, xmax, ymax] in gradi WGS84 — prima la longitudine. Al di fuori la mappa è vuota. Per impostazione predefinita è il mondo intero.No
epsgIl sistema di coordinate in cui il servizio pubblica, come codice EPSG. Il valore predefinito è 3857. Consulta Quali proiezioni funzionano prima di usare qualsiasi altro codice.No
epsgExtentUn confine espresso nelle unità di epsg anziché in gradi. Questo definisce la griglia di tile, non il ritaglio del livello, ed è significativo solo per WMTS o per un WMS con tiled: true — un WMS non tiled semplice non ha una griglia di tile e lo ignora.No
zoomLevelLo zoom minimo e massimo supportato dal servizio, come [min, max]. Richiedere uno zoom che il server non ha produce tile vuote.No
creditsIl testo di attribuzione. Vedi Attribuzione e crediti — ha effetto solo insieme a creditsUrl.No
creditsUrlIl link dietro quel testo di attribuzione.No

Solo WMTS

ProprietàSignificatoObbligatoria
subdomainsLe lettere su cui far ruotare il segnaposto {s}, scritte come un’unica stringa senza separatori — abc significa a, b e c. I fornitori li offrono così un browser può recuperare tile da più host contemporaneamente. Omettilo se il tuo url non contiene {s}.No
tileSizeIl lato della tile in pixel. Il valore predefinito è 256, usato da quasi tutti i servizi; alcuni più recenti servono 512.No

Solo WMS

ProprietàSignificatoObbligatoria
layersI nomi dei livelli da richiedere, esattamente come il servizio li denomina. Più valori sono separati da virgola.Sì
formatIl tipo di immagine come tipo MIME — image/jpeg per immagini fotografiche, image/png dove serve la trasparenza.Sì
stylesLo stile del livello, vuoto per impostazione predefinita. Nota il plurale: una chiave style viene ignorata, il che è facile non notare perché la richiesta ha comunque successo e usa semplicemente lo stile predefinito del server.No
versionLa versione della specifica WMS. Il valore predefinito è 1.3.0. I server più vecchi potrebbero richiedere 1.1.1, che differisce nell’ordine delle coordinate.No
tiledtrue richiede la mappa come tante piccole tile, false come una singola grande immagine per vista. Tiled è di solito più veloce e più leggero per il server; alcuni servizi supportano solo una delle due modalità.No

Quali proiezioni funzionano

La vista della mappa è sempre in Web Mercator. Il tuo epsg indica all’app in cosa pubblica il servizio, e la mappa riproietta da quel sistema — ma solo per i sistemi di coordinate che conosce.

  • 3857 (Web Mercator) e 4326 (WGS84 lon/lat) funzionano sempre. Sono integrati.
  • Qualsiasi altro codice non è supportato a meno che tu non l’abbia testato. Gli altri codici dipendono dalla registrazione di una definizione di proiezione prima che la mappa venga costruita, e ciò non avviene in modo affidabile. Un servizio svizzero LV95 (2056) potrebbe funzionare; un servizio ETRS89/UTM come 25832 è molto improbabile che funzioni.

Se il tuo servizio pubblica solo in una griglia nazionale, la strada affidabile è chiedere al tuo fornitore se serve anche 3857 o 4326 — la maggior parte lo fa — invece di passare il codice nazionale sperando che funzioni.

Esempi pratici

Un servizio WMTS

Le tile standard di OpenStreetMap, con sottodomini e attribuzione compilati. Questo è il link usato per gli screenshot di questa pagina:

{"type":"wmts","url":"https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png","subdomains":"abc","tileSize":256,"zoomLevel":[0,22],"credits":"OpenStreetMap contributors","creditsUrl":"https://www.openstreetmap.org/copyright"}

Codificato in un link:

https://www.map.army/?mapType=%7B%22type%22%3A%22wmts%22%2C%22url%22%3A%22https%3A%2F%2F%7Bs%7D.tile.openstreetmap.org%2F%7Bz%7D%2F%7Bx%7D%2F%7By%7D.png%22%2C%22subdomains%22%3A%22abc%22%2C%22tileSize%22%3A256%2C%22zoomLevel%22%3A%5B0%2C22%5D%2C%22credits%22%3A%22OpenStreetMap+contributors%22%2C%22creditsUrl%22%3A%22https%3A%2F%2Fwww.openstreetmap.org%2Fcopyright%22%7D

Un servizio WMS

La carta nazionale 1:10 000 di swisstopo, in modalità tiled, limitata all’estensione effettivamente occupata dalla Svizzera così che la mappa non sia vuota altrove:

{"type":"wms","url":"https://wms.geo.admin.ch/?","layers":"ch.swisstopo.landeskarte-farbe-10","format":"image/jpeg","styles":"default","version":"1.3.0","tiled":true,"extent":[5.5,45.8,11,47.8],"zoomLevel":[7,21],"credits":"Federal Office of Topography swisstopo","creditsUrl":"https://www.geo.admin.ch/"}

Codificato in un link:

https://www.map.army/?mapType=%7B%22type%22%3A%22wms%22%2C%22url%22%3A%22https%3A%2F%2Fwms.geo.admin.ch%2F%3F%22%2C%22layers%22%3A%22ch.swisstopo.landeskarte-farbe-10%22%2C%22format%22%3A%22image%2Fjpeg%22%2C%22styles%22%3A%22default%22%2C%22version%22%3A%221.3.0%22%2C%22tiled%22%3Atrue%2C%22extent%22%3A%5B5.5%2C45.8%2C11%2C47.8%5D%2C%22zoomLevel%22%3A%5B7%2C21%5D%2C%22credits%22%3A%22Federal+Office+of+Topography+swisstopo%22%2C%22creditsUrl%22%3A%22https%3A%2F%2Fwww.geo.admin.ch%2F%22%7D

Attribuzione e crediti

credits e creditsUrl sono opzionali per l’app, ma di solito non lo sono per la tua licenza. La maggior parte dei servizi di mappe, inclusi OpenStreetMap e ogni agenzia cartografica nazionale, richiede che la propria attribuzione compaia ovunque le proprie immagini siano mostrate.

Se compilati, compaiono in due punti:

  • Nell’app, come link nel pannello informazioni — il pulsante i nell’angolo in basso a destra — con la dicitura © Map Data: seguita dal tuo testo credits, che rimanda al tuo creditsUrl. Verificato il 2026-09-17: un link che portava l’attribuzione di OpenStreetMap ha prodotto lì © Map Data: OpenStreetMap contributors, esattamente come le mappe integrate producono © Map Data: Google.
  • Nel piè di pagina di ogni esportazione e stampa, che è quello che di solito conta ai fini della licenza.

Nota che il credito nell’app è dietro quel pulsante, non disegnato sulla mappa. Se la tua licenza richiede che l’attribuzione sia visibile senza un clic, il piè di pagina dell’esportazione è dove puoi fare affidamento.

Suggerimento: Entrambe le proprietà sono richieste, altrimenti nessuna delle due viene usata. Fornire credits senza creditsUrl non produce nulla — nessun link nel pannello e un piè di pagina di esportazione vuoto, senza alcun avviso in entrambi i casi. Se l’attribuzione conta per la tua licenza, imposta entrambe e controlla un’esportazione prima di pubblicarla.

La vista 3D

Un servizio mapType funziona nella vista 3D così come nella mappa 2D, anche se la vista 3D lo costruisce con un percorso diverso. Due conseguenze da tenere presenti:

  • Se hai limitato la copertura con extent, la vista 3D aggiunge un tenue sfondo a copertura mondiale sotto il tuo servizio, così che il globo non presenti bordi sfumati al di fuori della tua area. Questo sfondo non è il tuo servizio e non porta alcuna tua attribuzione.
  • L’avvertenza sulle proiezioni indicata sopra vale ancora di più in 3D. Considera 3857 e 4326 come i casi supportati e testa qualsiasi altro codice in entrambe le viste prima di farci affidamento.

Combinare con altri parametri

mapType viene letto indipendentemente dagli altri parametri URL, quindi un unico link può portare il tuo servizio di mappe e precaricare un overlay con layer=. I parametri funzionano in un embed iframe esattamente come in un link normale.

Suggerimento: Un link che porta sia mapType sia una condivisione smette di essere il link che hai inviato. Quando l’app apre una condivisione, riscrive la barra degli indirizzi con l’indirizzo proprio della condivisione e mantiene solo i parametri della condivisione — quindi mapType scompare dall’URL. La mappa continua a funzionare per quella sessione, ma l’indirizzo non è più copiabile, salvabile nei preferiti o ricaricabile come link combinato. Conserva l’originale da qualche parte se ti serve di nuovo, e ricorda che il ricaricamento al primo caricamento descritto sopra richiede proprio quel link.

Condividere una mappa caricata in questo modo

Se apri map.army con un link mapType e poi crei una condivisione, la persona che apre la tua condivisione non riceve il tuo servizio di mappe. Riceve il proprio sfondo predefinito con il tuo overlay sopra di esso.

Questo è il malinteso più probabile su questa pagina, perché nulla sullo schermo lo lascia intuire: la tua condivisione ti appare corretta. La condivisione memorizza quale mappa di base era selezionata ma non la sua definizione, e il tuo servizio non ha mai fatto parte dell’elenco del destinatario, quindi la sua app ricade sul proprio predefinito.

Per dare a qualcuno la tua mappa di sfondo oltre al tuo overlay, inviagli direttamente il link mapType — con il parametro layer= se vuoi che l’overlay lo accompagni — invece di una condivisione.

Ci sono tre errori distinti, e appaiono diversi sullo schermo.

Una mappa vuota al primo caricamento. Previsto, per ora — ricarica la pagina. Vedi Apri il link due volte.

Il tuo servizio viene ignorato e appaiono le mappe normali. Il JSON era leggibile ma non descriveva un servizio utilizzabile — un type diverso da wmts o wms, un url mancante, oppure un WMS senza layers o format. L’app torna al suo elenco integrato. Controlla le proprietà richieste per il tuo tipo di servizio.

Nessuna mappa, nemmeno dopo un ricaricamento. O il JSON non poteva essere letto — una virgola in più, una parentesi graffa spaiata, un carattere non codificato — oppure il servizio non è raggiungibile in un modo che l’app può usare. Per il JSON, incollalo in un qualsiasi validatore prima di codificarlo. Per il servizio, controlla tre cose in quest’ordine:

  1. Accesso cross-origin. map.army disegna ogni tile tramite un canvas, in modo da poter applicare luminosità, tonalità e crominanza e da poter includere la mappa in un’esportazione. Questo significa che il tuo servizio deve inviare un’intestazione Access-Control-Allow-Origin che permetta l’origine dell’app. Un servizio che non lo fa non mostrerà nulla, anche se lo stesso identico URL di tile si apre perfettamente in una scheda del browser. Questa è la causa più comune di un servizio apparentemente corretto che non compare mai, ed è la più difficile da indovinare.
  2. HTTPS. Un browser blocca le immagini in HTTP semplice all’interno di una pagina HTTPS.
  3. Raggiungibilità. Verifica che il servizio risponda dalla macchina che esegue il browser, non solo dall’interno della tua rete.

Se non riesci a far sì che il tuo servizio invii intestazioni cross-origin, la soluzione abituale è mettergli davanti un proxy che possa farlo, sulla tua stessa infrastruttura.

  • Un solo servizio per link. Non c’è modo di passare un elenco, né di aggiungere il tuo accanto alle mappe integrate.
  • Non viene ricordato. Ogni visita richiede di nuovo il link.
  • Non compare nel pannello Opzioni come nuova voce — prende il posto dell’intero elenco, e la riga Tipo di mappa scompare.
  • Non viaggia in una condivisione. Vedi sopra.
  • epsg, epsgExtent e tileSize sono rispettati qui ma non nel file di configurazione proprio di una distribuzione, quindi un link può descrivere un servizio in modo più preciso di quanto possa fare una distribuzione installata.

Per un elenco permanente dei tuoi servizi, selezionabile come qualsiasi altra mappa e condiviso da chiunque usi quella distribuzione, vedi Gratuito vs Pro.

Dove andare adesso