Connect Your Own Map Service to map.army

map.army ships with a fixed list of background maps. If your organisation runs its own map service — a national survey agency’s, a defence geospatial service, or a tile server on your own network — you can have the app draw that instead, without any installation, by putting it in the link.

What a `mapType` link does

A map.army address can carry a mapType parameter describing one map service. When the app finds it, that service becomes the background map:

map.army drawing a custom OpenStreetMap WMTS service as its background map, loaded from a mapType link

It replaces the built-in list rather than joining it. The Map Type row disappears from Options → Map Settings altogether, because with a single service there is no longer a choice to offer:

map.army's Map Type dropdown expanded, listing Satellite, Terrain, Hybrid, Roads, Roadmap and OSM

The effect lasts only as long as the link. Nothing is saved: open map.army again without the parameter and the usual maps are back. That makes it a good way to hand somebody a working map of your own area — send the link and they need no setup — and a poor way to change your own default, because every visit needs the same link.

Hint: There is no field in the Options panel for a map-service address. The link is the only way to do this in the hosted app; if you want your services to be the list, permanently and selectable like any other map, that is configured when a deployment is installed — see Free vs Pro.

Open the link twice — the first load shows no map

map.army on a first visit to a mapType link, showing a working toolbar over a completely empty white map area

On the first visit in a given browser, a mapType link currently shows no background map at all — a working toolbar over an empty canvas, exactly as above. Reload the page and your service appears. Everything else about the link works normally.

Measured on 2026-09-17 against build 6.1.1/7489: first load made zero requests to the tile service; a reload of the identical address made 19 and drew the map.

Hint: Send the link with “open it, then reload once”. A recipient who opens your link, sees a blank map and closes the tab has no way of knowing anything was wrong — there is no error message. Until this is fixed in the app, the reload is the workaround, and it is worth saying out loud to whoever you send the link to.

WMTS or WMS — telling them apart

Both are standard ways for a server to publish map imagery, and which one you have decides which properties you need. Your provider’s documentation will say, but the address itself is usually the giveaway.

A WMTS service (Web Map Tile Service) serves pre-cut square tiles. Its address is a template with placeholders for the tile’s position — {z} for the zoom level, {x} and {y} for the column and row, as in https://tiles.example.org/{z}/{x}/{y}.png. It is the faster of the two because the server has done the work in advance.
A WMS service (Web Map Service) draws an image to order. Its address is a plain endpoint, and you also have to say which layers you want and in what image format, because one WMS endpoint typically publishes many.

If you are given a GetCapabilities URL, that is WMS. If you are given an address with {z}/{x}/{y} in it, that is WMTS.

Building the link

The JSON

The value of mapType is a JSON object. The shortest usable WMTS one needs just a type and an address:

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

A WMS one needs three things, because a bare endpoint is not enough to draw anything:

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

Everything else is optional and described below. Get the required properties wrong and the app quietly ignores the whole parameter — see When the link does not work.

Encoding it into the address

JSON contains characters that are not safe in a URL — quotes, braces, commas — so the object has to be percent-encoded before it goes in the address. Any HTTP library or scripting language will do this for you. In a browser console:

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

Pasting raw JSON into the address bar sometimes appears to work, because browsers encode some characters on your behalf — but not all of them, and the ones it misses fail silently. Encode it properly.

Every property in detail

Properties both service types take

Property	Meaning	Required
`type`	`wmts` or `wms`. Anything else and the parameter is ignored.	Yes
`url`	The service address. For WMTS an XYZ template containing `{z}`, `{x}` and `{y}`, plus `{s}` if you use subdomains. For WMS the endpoint.	Yes
`extent`	The area the service actually covers, as `[xmin, ymin, xmax, ymax]` in WGS84 degrees — longitude first. It clips the layer, so outside it the map is blank. Defaults to the whole world.	No
`epsg`	The coordinate system the service publishes in, as an EPSG code. Defaults to `3857`. See Which projections work before using anything else.	No
`epsgExtent`	A boundary in the units of `epsg` rather than degrees. This one defines the tile grid, not the layer clip, and is only meaningful for WMTS or for WMS with `tiled: true` — a plain untiled WMS has no tile grid and ignores it.	No
`zoomLevel`	The lowest and highest zoom the service supports, as `[min, max]`. Asking for a zoom the server does not have produces empty tiles.	No
`credits`	The attribution text. See Attribution and credits — it only takes effect together with `creditsUrl`.	No
`creditsUrl`	The link behind that attribution text.	No

WMTS only

Property	Meaning	Required
`subdomains`	The letters to rotate through the `{s}` placeholder, written as one string with no separators — `abc` means `a`, `b` and `c`. Providers offer these so a browser can fetch tiles from several hostnames at once. Omit it if your `url` has no `{s}`.	No
`tileSize`	The tile edge in pixels. Defaults to `256`, which is what almost every service uses; some newer ones serve `512`.	No

WMS only

Property	Meaning	Required
`layers`	The layer names to request, exactly as the service names them. Several are comma-separated.	Yes
`format`	The image type as a MIME type — `image/jpeg` for photographic imagery, `image/png` where you need transparency.	Yes
`styles`	The layer style, empty by default. Note the plural: a `style` key is ignored, which is easy to miss because the request still succeeds and simply uses the server’s default.	No
`version`	The WMS specification version. Defaults to `1.3.0`. Older servers may need `1.1.1`, which differs in how it orders coordinates.	No
`tiled`	`true` asks for the map as many small tiles, `false` as one large image per view. Tiled is usually faster and easier on the server; a few services only support one or the other.	No

Which projections work

The map view itself is always Web Mercator. Your epsg tells the app what the service publishes in, and the map reprojects from it — but only for coordinate systems it knows.

3857 (Web Mercator) and 4326 (WGS84 lon/lat) always work. They are built in.
Anything else is unsupported unless you have tested it. Other codes depend on a projection definition being registered before the map is built, and that does not reliably happen. A Swiss LV95 service (2056) may work; an ETRS89/UTM service such as 25832 is very unlikely to.

If your service publishes only in a national grid, the dependable route is to ask your provider whether it also serves 3857 or 4326 — most do — rather than passing the national code and hoping.

Worked examples

A WMTS service

OpenStreetMap’s standard tiles, with subdomains and attribution filled in. This is the link used for the screenshots on this page:

{"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"}

Encoded into a 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

A WMS service

swisstopo’s 1:10 000 national map, tiled, restricted to the extent Switzerland actually occupies so the map is not blank elsewhere:

{"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/"}

Encoded into a 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

Attribution and credits

credits and creditsUrl are optional to the app and usually not optional to your licence. Most map services, including OpenStreetMap and every national survey agency, require their attribution to appear wherever their imagery is shown.

Filled in, they appear in two places:

In the app, as a link in the information panel — the i button in the bottom-right corner — reading © Map Data: followed by your credits text, pointing at your creditsUrl. Verified 2026-09-17: a link carrying OpenStreetMap’s attribution produced © Map Data: OpenStreetMap contributors there, exactly as the built-in maps produce © Map Data: Google.
In the footer of every export and print, which is the one that usually matters for a licence.

Note that the in-app credit is behind that button, not drawn on the map. If your licence requires attribution to be visible without a click, the export footer is where you can rely on it.

Hint: Both properties are required, or neither is used. Supplying credits without creditsUrl emits nothing at all — no link in the panel and an empty export footer, with no warning either way. If attribution matters for your licence, set both and check an export before you publish one.

The 3D view

A mapType service works in the 3D view as well as the 2D map, though the 3D view builds it by a different route. Two consequences worth knowing:

If you restricted coverage with extent, the 3D view adds a faint world-wide backdrop underneath your service so the globe does not have smeared edges outside your area. That backdrop is not your service and carries no attribution of yours.
The projection caution above applies more strongly in 3D. Treat 3857 and 4326 as the supported cases and test anything else in both views before relying on it.

Combining with other parameters

mapType is read independently of the other URL parameters, so one link can carry your map service and pre-load an overlay with layer=. The parameters work in an iframe embed exactly as they do in a normal link.

Hint: A link that carries both mapType and a share stops being the link you sent. When the app opens a share, it rewrites the address bar to the share’s own address and keeps only the share’s parameters — so mapType vanishes from the URL. The map still works for that session, but the address is no longer copyable, bookmarkable or reloadable as the combined link. Keep the original somewhere if you need it again, and remember the first-load reload above needs it.

If you open map.army with a mapType link and then create a share, the person opening your share does not get your map service. They get their own default background with your overlay on top of it.

This is the most likely misunderstanding on this page, because nothing on your screen hints at it: your share looks right to you. The share stores which base map was selected but not its definition, and your service was never part of the recipient’s list, so their app falls back to its own default.

To give somebody your background map as well as your overlay, send them the mapType link itself — with the layer= parameter if you want the overlay to come with it — rather than a share.

When the link does not work

There are three distinct failures, and they look different on screen.

A blank map on the first load. Expected, for now — reload the page. See Open the link twice.

Your service is ignored and the normal maps appear. The JSON was readable but did not describe a usable service — a type that is not wmts or wms, a missing url, or a WMS without layers or format. The app falls back to its built-in list. Check the required properties for your service type.

No maps at all, after a reload too. Either the JSON could not be read — a stray comma, an unmatched brace, an unencoded character — or the service is not reachable in a way the app can use. For the JSON, paste it into any validator before encoding it. For the service, check three things in this order:

Cross-origin access. map.army draws every tile through a canvas, so that brightness, hue and chroma can be applied and so the map can go into an export. That means your service must send an Access-Control-Allow-Origin header permitting the app’s origin. A service that does not will show nothing at all, even though the very same tile URL opens perfectly in a browser tab. This is the most common cause of a correct-looking service that never appears, and the hardest to guess.
HTTPS. A browser blocks plain-HTTP imagery inside an HTTPS page.
Reachability. Confirm the service answers from the machine running the browser, not only from inside your network.

If your service cannot be made to send cross-origin headers, the usual answer is to put a proxy that can in front of it, on your own infrastructure.

What a link cannot do

Only one service per link. There is no way to pass a list, and no way to add yours alongside the built-in maps.
It is not remembered. Each visit needs the link again.
It does not appear in the Options panel as a new entry — it takes the place of the whole list, and the Map Type row disappears.
It does not travel in a share. See above.
epsg, epsgExtent and tileSize are honoured here but not in a deployment’s own configuration file, so a link can describe a service more precisely than an installed deployment can.

For a permanent list of your own services, selectable like any other map and shared by everybody using that deployment, see Free vs Pro.

Where to go next

Base maps — the built-in list, and what each map may be used for.
Load a MilX Layer via URL Parameter — every other parameter a link can carry.
Import Overlays — image overlays and vector layers, for putting your own material on top of a base map instead of replacing it.