Mapbox

Add 1224Tools Bathymetry to a Mapbox GL JS map as a transparent raster overlay while keeping your existing Mapbox basemap and map configuration.

Overview

1224Tools Bathymetry uses standard XYZ raster tiles and can be added to Mapbox GL JS as a raster source and raster layer.

The bathymetry tiles have transparent backgrounds and are intended to be displayed as an overlay above an existing basemap.

Tile URL

https://tiles.1224tools.com/v1/{z}/{x}/{y}.png?key=YOUR_API_KEY

Replace YOUR_API_KEY with the API key provided for your 1224Tools Bathymetry account.

Basic Integration

The following example assumes that you already have a Mapbox GL JS map instance named map.

const BATHYMETRY_API_KEY = 'YOUR_API_KEY';

map.on('load', () => {
  map.addSource('1224tools-bathymetry', {
    type: 'raster',
    tiles: [
      `https://tiles.1224tools.com/v1/{z}/{x}/{y}.png?key=${BATHYMETRY_API_KEY}`
    ],
    tileSize: 256,
    scheme: 'xyz',
    minzoom: 7,
    maxzoom: 13
  });

  map.addLayer({
    id: '1224tools-bathymetry',
    type: 'raster',
    source: '1224tools-bathymetry',
    minzoom: 7,
    paint: {
      'raster-opacity': 1
    }
  });
});

Mapbox Access Token

Your Mapbox access token and your 1224Tools Bathymetry API key are separate credentials. Continue using your existing Mapbox access token for Mapbox, and use your Bathymetry API key only in the bathymetry tile URL.

Zoom Levels

Native bathymetric contour tiles are available from Z7 through Z13.

The raster source is configured with maxzoom: 13. At higher map zoom levels, Mapbox can continue displaying the Z13 source tiles by overzooming them.

Overzooming does not introduce additional bathymetric detail beyond the native Z13 tiles.

Adjusting Opacity

Change the raster opacity when you want the basemap to remain more visible beneath the bathymetry contours.

map.setPaintProperty(
  '1224tools-bathymetry',
  'raster-opacity',
  0.6
);

Show or Hide the Layer

// Hide
map.setLayoutProperty(
  '1224tools-bathymetry',
  'visibility',
  'none'
);

// Show
map.setLayoutProperty(
  '1224tools-bathymetry',
  'visibility',
  'visible'
);

Layer Order

Bathymetry should normally be placed above the basemap so that contour lines and depth labels remain visible.

If your Mapbox style contains additional overlays, labels or interactive layers, adjust the bathymetry layer position to match the visual hierarchy of your application.

Coastline Alignment

During testing with Mapbox basemaps, visible coastline offsets have been observed in some locations, particularly around small islands and complex shorelines.

These offsets can result from differences between the bathymetry source data and the coastline geometry used by the basemap. Developers should review alignment in the geographic areas that are important to their application.

Important Notes

• Native tile zoom levels are Z7 through Z13.
• Tiles use the XYZ scheme and Web Mercator projection.
• Tile images are transparent 256 × 256 PNG files.
• Contour depth labels are included in the tile images.
• Overzooming above Z13 does not add additional bathymetric detail.