GRASS logo

NAME

i.basemap - Import basemaps from various web map services

KEYWORDS

raster, import, web, basemap

SYNOPSIS

i.basemap
i.basemap --help
i.basemap [-lcrob] output=name [server=string] [url=string] [maxcols=integer] [maxrows=integer] [srs=string] [format=string] [composite_levels=integer] [zoom=string] [api_key=string] [cache=name] [--overwrite] [--help] [--verbose] [--quiet] [--ui]

Flags:

-l
List available web map servers
-c
Use current computational region
-r
Reproject to current location's projection
-o
Overwrite existing maps
-b
Keep separate red/green/blue band maps instead of a single composite
--overwrite
Allow output files to overwrite existing files
--help
Print usage summary
--verbose
Verbose module output
--quiet
Quiet module output
--ui
Force launching GUI dialog

Parameters:

output=name [required]
Name for output raster map(s)
server=string
Web map server to use
Options: Google_Satellite, OpenStreetMap, Bing_Aerial, ESRI_WorldImagery, USGS_Topo, Google_Terrain, Google_Hybrid, Bing_Roads, Stamen_Terrain, Stamen_Toner, Stamen_Watercolor, OpenTopoMap, OSM_Humanitarian, Natural_Earth, USGS_NAIP, USGS_3DEP, USGS_Hydro, Copernicus_Sentinel, Landsat, MODIS
Default: OpenStreetMap
url=string
Custom URL template for XYZ tiles (use {x}, {y}, {z} or {quadkey})
maxcols=integer
Maximum width of output map in pixels
Default: 1024
maxrows=integer
Maximum height of output map in pixels
Default: 1024
srs=string
Spatial reference system for the output
Default: EPSG:3857
format=string
Output format for downloaded tiles
Options: png, jpeg
Default: png
composite_levels=integer
Number of color levels per RGB channel used by r.composite (256 = lossless for 8-bit imagery)
Options: 1-256
Default: 256
zoom=string
Tile zoom level (0-20), or auto to match the region resolution
Default: auto
api_key=string
API key for servers that require one (e.g. Stamen styles hosted by Stadia Maps)
cache=name
Directory where downloaded tiles are kept and reused by later runs

Table of contents

DESCRIPTION

i.basemap downloads base map tiles from public web map servers for the current computational region and imports them as raster maps. The tiles are mosaicked, reprojected from Web Mercator to the project's coordinate reference system and resampled to the computational region.

The server option selects one of 20 predefined servers (list them with -l); url gives a custom XYZ or quadkey template instead.

Servers

Server Max zoom Content
Google_Satellite 20 Google satellite and aerial imagery
Google_Hybrid 20 Google imagery with labels and roads
Google_Terrain 15 Google terrain map
ESRI_WorldImagery 19 ESRI World Imagery
Bing_Aerial 19 Microsoft Bing aerial imagery (quadkey)
Bing_Roads 19 Microsoft Bing road map (quadkey)
OpenStreetMap 19 OpenStreetMap standard style
OSM_Humanitarian 20 OpenStreetMap humanitarian style
OpenTopoMap 17 Topographic map from OpenStreetMap and SRTM
Natural_Earth 16 ESRI National Geographic world map
Stamen_Terrain 18 Stamen terrain, hosted by Stadia Maps (api_key required)
Stamen_Toner 20 Stamen toner, hosted by Stadia Maps (api_key required)
Stamen_Watercolor 16 Stamen watercolor, hosted by Stadia Maps (api_key required)
USGS_Topo 16 USGS topographic map (United States)
USGS_NAIP 16 USGS Imagery Only basemap, NAIP orthoimagery (United States)
USGS_3DEP 13 USGS 3DEP shaded relief, a rendering, not elevation values
USGS_Hydro 16 USGS hydrography (United States)
Copernicus_Sentinel 15 Sentinel-2 cloudless 2023 mosaic by EOX (CC BY-NC-SA 4.0)
Landsat 12 Landsat WELD annual true colour, NASA GIBS
MODIS 8 Blue Marble Next Generation, MODIS composite, NASA GIBS

Each server has its own terms of use and attribution requirements; the user is responsible for respecting them.

Zoom level

With zoom=auto (the default), the zoom level is the coarsest one whose tile pixel is no larger than the region resolution (with a 5 % tolerance, so that a 2 m region at mid latitudes uses zoom 16, whose pixels are about 2.0 m). It is capped at the server's highest level, with a warning when the region is finer than the server can deliver. A number from 0 to 20 forces the zoom level; a level above the server's highest one is an error.

A Web Mercator tile pixel at zoom z and latitude φ covers 40,075,017 · cos φ / (256 · 2^z) m: about 2.0 m at zoom 16 and 0.5 m at zoom 18 at 32° N.

Output

By default the red, green and blue bands are combined by r.composite. With -b the bands are kept as separate maps. Areas without tiles are NULL; black pixels are kept.

NOTES

The region extent is converted to WGS 84 with g.region -b, so any projected or geographic coordinate reference system selects the right tiles. Tiles are downloaded with curl in random order, with a descriptive User-Agent and up to three attempts per tile; HTTP errors are treated as failed tiles. Each tile is georeferenced by a world file whose origin is the centre of its upper-left pixel, mosaicked into a virtual raster with an alpha band, and imported with r.import.

More than 2,500 tiles trigger a warning: tile servers limit bulk downloads. A smaller region or a lower zoom level reduces the number of tiles by four per level.

With cache, tiles are kept in that directory, in one sub-folder per tile source and zoom level, and a later run reuses every valid tile already there instead of downloading it again. This resumes an interrupted download of a large region. Without cache, tiles are downloaded to a temporary directory that is removed at the end.

Template fields for url: {x}, {y}, {z}, {quadkey}, {s} (a subdomain, a, b or c) and {api_key}.

EXAMPLES

List the servers:

i.basemap -l

Aerial imagery at 0.5 m (zoom 18) for the current region:

g.region n=3558300 s=3557300 w=515000 e=516000 res=0.5
i.basemap server=Google_Satellite output=aerial

A fixed zoom level and separate bands:

i.basemap server=ESRI_WorldImagery output=esri zoom=17 -b

A server requiring an API key:

i.basemap server=Stamen_Terrain output=terrain api_key=MY_STADIA_KEY

Download into a cache directory, so that an interrupted run resumes where it stopped:

i.basemap server=Google_Satellite output=aerial cache=$HOME/tiles

A custom XYZ template:

i.basemap url="https://tile.example.org/{z}/{x}/{y}.png" output=custom

SEE ALSO

r.composite, r.import, r.in.wms

AUTHORS

Yann Chemin

SOURCE CODE

Available at: i.basemap source code (history)

Accessed: Sunday Nov 15 10:56:31 2026


Main index | Imagery index | Topics index | Keywords index | Graphical index | Full index

© 2003-2026 GRASS Development Team, GRASS 8.5.1dev Reference Manual