The client code is fairly slick in that it takes care of version negotiation (inheriting functionalities from AbstractOpenWebService), and even a few server specific wrinkles for you.

This page contains examples how how to connect and use the GeoTools WebMapTileServer class. WebMapTileServer acts as a proxy for a remote “Web Map Tile Server” and can be used to examine and retrieve published information in the forms of descriptive Java beans, and raw images.

  • To begin communicating with a server, pass in a URL pointing to a WMTS Capabilities document.

    Constructing a WebMapTileServer object:

    URL url = null;
    try {
      url = new URL("https://gibs.earthdata.nasa.gov/wmts/epsg4326/best/wmts.cgi?VERSION=1.0.0&Request=GetCapabilities&Service=WMTS");
    } catch (MalformedURLException e) {
      // will not happen
    WebMapTileServer wmts = null;
    try {
      wmts = new WebMapTileServer(url);
    } catch (IOException e) {
      // There was an error communicating with the server
      // For example, the server is down
    } catch (ServiceException e) {
      // The server returned a ServiceException (unusual in this case)
    } catch (SAXException e) {
      // Unable to parse the response from the server
      // For example, the capabilities it returned was not valid

    Assuming nothing went wrong, we now have a WebMapTileServer object wmts that contains the Capabilities document of returned from the server. It can also provide further communication with the server.


WMTSCapabilities is used to describe the abilities and published information available via a Web Map Tile Service.

You can retrieve a WMTSCapabilities directly from your WebMapTileService:

WMTSCapabilities capabilities = wmts.getCapabilities();

From the capabilities you can retrieve info about the Service, the available Requests, the available Layers and the configured MatrixSets.


Service contains metadata information about the server:

WMTSCapabilities capabilities = wmts.getCapabilities();

String serverName = capabilities.getService().getName();
String serverTitle = capabilities.getService().getTitle();
System.out.println("Capabilities retrieved from server: " + serverName + " (" + serverTitle + ")");


The WMTS Operations describe the requests entry points:

URL requestUrl = wmts.getCapabilities().getRequest().getGetTile().getGet();


The Layer section contains detailed information about the layers on the server:

WMTSCapabilities capabilities = wmts.getCapabilities();

// gets all the layers in a list, in the order they appear in
// the capabilities document
List<WMTSLayer> layers = capabilities.getLayerList();

Every layer has a list of related Formats:

String layerName = ...

// Get formats for a given layer
List<String> formats = wmts.getCapabilities().getLayer(layerName).getFormats()


For each layer you can get its available styles:

for (WMTSLayer layer : wmts.getCapabilities().getLayerList()) {
   System.out.println("Layer: " + layer.getName());
   System.out.println("       " + layer.getTitle());

   for (StyleImpl style : layer.getStyles()) {
      // Print style info
      System.out.println("  Name:  " + style.getName());
      System.out.println("  Title: " + style.getTitle());


Each Layer is available in one or more MatrixSet. Here’s an example on how to loop in the matrices of the published layers:

for (WMTSLayer layer : wmts.getCapabilities().getLayerList()) {
   for (String tileMatrixId : layer.getTileMatrixLinks().keySet()) {
      List<TileMatrixLimits> limits = layer.getTileMatrixLinks().get(tileMatrixId).getLimits();
      TileMatrixSet matrixSet = wmts.getCapabilities().getMatrixSet(tileMatrixId);

      List<TileMatrix> matrices = matrixSet.getMatrices();

      for (TileMatrix matrix : matrices) {
         System.out.println("LAYER " + layer.getName()
                  + ", matrixSet id : " + tileMatrixId
                  + ", matrix " + matrix.getIdentifier()
                  + ", matrixGrid" + matrix.getMatrixWidth() + "x" + matrix.getMatrixHeight()
                  + ", tileSize" + matrix.getTileWidth() + "x" + matrix.getTileHeight());


Making a GetTile request is more interesting than looking at WMSCapabilities.

  1. We need to ask the client to create us a GetTileRequest object:

    GetTileRequest req = wmts.createGetTileRequest();
  2. Using data from the capabilities document (or our own personal choices) we can configure the request object:

    // set any other required dimensions, as advertised by the layer - only time is supported at the moment
    // if time is need but is not provided, the default value will be used
    // set bbox - coords and CRS
    // set the pixel size of the image to be created
  1. Now we can issue our request and grab the Tiles:

    Set<Tile> responses = wmts.issueRequest(req);

    We are getting a Set of Tiles, which are all the Tiles needed to fill the bounding box we requested.

  2. In order to get the tile images, we’ll have to use the info in the Tiles:

    for(Tile tile: responses) {
       BufferedImage image = ImageIO.read(tile.getInputStream());
       ... use the image (you may want to render it onto a Graphics2D) ...