How custom services work in BlenderGIS

Basemap sources live in a file called servicesDefs.py inside the BlenderGIS add-on folder, and the add-on’s official wiki documents adding your own service there in a JSON-like syntax. Each service definition has the same shape:

• A name and description — what shows up in the basemap source list.
• A service type — WMS, WMTS, or TMS (slippy-map XYZ tiles).
• A grid — the tile grid the service uses, typically WM for Web Mercator (EPSG:3857), which is what almost every public tile service speaks.
• Layers — the layers you want available, each with its format (png or jpeg), style, and zoom range.
• A URL template — for WMS, the GetMap request parameters with placeholders BlenderGIS fills in per tile ({CRS}, {LAY}, {BBOX}, {WIDTH}, {HEIGHT}); for TMS, the classic {z}/{x}/{y} tile URL pattern.
• A referer — some tile servers check the HTTP referer and return blank tiles without the right one.

A minimal TMS/XYZ definition looks like this (edit names and URLs to match your service, then reinstall or re-enable the add-on so it reloads the file):

"MY_TILES" : {
    "name" : 'My Tile Service',
    "description" : 'Organization name',
    "service": 'TMS',
    "grid": 'WM',
    "layers" : {
        "TOPO" : {"urlKey" : 'topo', "name" : 'Topo', "description" : '', "format" : 'png', "style" : '', "zmin" : 0, "zmax" : 18}
    },
    "urlTemplate": {
        "BASE_URL" : 'https://tiles.example.org/topo/{z}/{x}/{y}.png'
    },
    "referer": "https://tiles.example.org/"
}

For a WMS service the URL template instead builds the full GetMap request: base URL plus SERVICE=WMS, VERSION, REQUEST=GetMap, and the {CRS} / {LAY} / {FORMAT} / {STYLE} / {BBOX} / {WIDTH} / {HEIGHT} placeholders. Copy the structure of a working WMS definition from the file and change the values — do not invent the key names.

Troubleshooting the common failures

Gray or blank tiles. This is the most common symptom and it almost always means the server refused the request rather than the geometry being wrong. Check the referer first (some servers require it), then open Blender’s system console and look for the “Invalid tile data” debug line — it prints the exact URL BlenderGIS requested. Paste that URL into a browser: if the browser shows the tile, the server accepted the request and the problem is on the BlenderGIS side (timeout, cache); if the browser also fails, fix the URL parameters.

URL returns an error in the browser. Walk the GetMap parameters one by one: layer name spelled exactly as the server’s GetCapabilities advertises, supported CRS (EPSG:3857 works for nearly everything public; some national geoportals only serve their local projection), and an image format the server actually offers. Get the layer’s GetCapabilities XML and read what it supports — guessing parameter values is how afternoons disappear.

Projection mismatch. BlenderGIS works in Web Mercator for the map view and reprojects on export. If your service only serves a local projection (common with government WMS endpoints), tiles may not align or may fail entirely. Prefer services that offer EPSG:3857, or accept that the source will need pre-tiling into Web Mercator outside Blender.

Authentication required. Some WMS services accept an API token baked into the URL (a query parameter), and those can work as custom definitions — just put the token in the base URL. Services needing headers, cookies, or interactive login are generally not workable through the add-on’s tile fetcher.

Tiles show but resolution is poor. You are likely capped by the layer’s zmax or by the zoom you exported at. Raise zmax to what the service actually serves (check its docs), and use the basemap’s lock-extent trick (L key) to force higher-zoom tiles for your chosen area. If the built-in sources are failing for you instead, our satellite maps not showing guide covers those fixes.

Finally: attribute your sources. Public tile services are free to use but almost all require or appreciate credit — put the provider’s name in your renders, videos, and project credits.

Where is the servicesDefs.py file?

Inside the BlenderGIS add-on folder in your Blender add-ons directory (for example, under Blender’s scripts/addons/blendergis). Back it up before editing, add your service definition in the same JSON-like syntax as the existing entries, then reinstall or re-enable the add-on so it reloads the file.

Which service types can I add?

WMS, WMTS, and TMS (slippy-map XYZ tiles), per the add-on’s official basemap documentation. Plain XYZ tile URLs are the easiest to get working; WMS needs the GetMap parameter template done exactly right.

Can I add a WMS that needs a login or API key?

If the key can be embedded as a URL query parameter, yes — put it in the base URL of your definition. Services that require HTTP headers, cookies, or interactive login are generally not supported by the add-on’s tile fetcher.

Why do I get gray tiles from a URL that works in my browser?

The server is likely rejecting the request for a non-URL reason: a missing or wrong HTTP referer is the classic cause. Check the system console for the exact requested URL, verify the referer field in your definition, and confirm the server does not block non-browser clients.

What projection should the service support?

EPSG:3857 (Web Mercator) is the safest — it is what nearly all public tile services offer and what the add-on’s map view expects. Services limited to a local projection may not align or may fail entirely.

How do I get higher-resolution tiles from my custom source?

Set the layer’s zmax to the highest zoom the service genuinely serves, then in the basemap view lock the extent (L key) and zoom in — the add-on downloads tiles from the higher zoom level for the same area.