Google Maps

Add 1224Tools Bathymetry to Google Maps as a transparent XYZ tile overlay
while keeping your existing Google Maps basemap and application structure.

Overview

1224Tools Bathymetry uses standard XYZ raster tiles. In the Google Maps
JavaScript API, the tiles can be displayed above the existing basemap by
adding a custom image map type to overlayMapTypes.

The bathymetry tiles have transparent backgrounds, so the Google Maps
basemap remains visible beneath the contour lines and depth labels.

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.

Google Maps API Key

Your Google Maps Platform API key and your 1224Tools Bathymetry API key
are separate credentials. Continue using your Google Maps API key to load
Google Maps, and use your Bathymetry API key only for bathymetry tile
requests.

Basic Integration

The following example adds the native Z7–Z13 bathymetry tiles as an
ImageMapType.

const BATHYMETRY_API_KEY = 'YOUR_API_KEY';

function getNormalizedCoord(coord, zoom) {
  const tileRange = 2 ** zoom;

  // Tiles do not repeat vertically.
  if (coord.y < 0 || coord.y >= tileRange) {
    return null;
  }

  // Repeat horizontally when the map wraps around the world.
  const x = ((coord.x % tileRange) + tileRange) % tileRange;

  return {
    x,
    y: coord.y
  };
}

const bathymetryMapType = new google.maps.ImageMapType({
  getTileUrl: (coord, zoom) => {
    if (zoom < 7 || zoom > 13) {
      return '';
    }

    const normalizedCoord = getNormalizedCoord(coord, zoom);

    if (!normalizedCoord) {
      return '';
    }

    return (
      `https://tiles.1224tools.com/v1/${zoom}/` +
      `${normalizedCoord.x}/${normalizedCoord.y}.png` +
      `?key=${BATHYMETRY_API_KEY}`
    );
  },

  tileSize: new google.maps.Size(256, 256),
  opacity: 1,
  name: '1224Tools Bathymetry'
});

map.overlayMapTypes.insertAt(0, bathymetryMapType);

Zoom Levels

Native bathymetric contour tiles are available from Z7 through Z13.

The basic example above displays only native bathymetry tiles. Applications
that need to display the bathymetry layer above Z13 can overzoom the Z13
tiles as described below.

Overzooming Above Z13

Google Maps overlay map types do not automatically use the Z13 source tile
as a correctly cropped parent tile at higher zoom levels. To preserve
geographic alignment, an application can crop the appropriate portion of
the Z13 parent tile and scale it to the requested map tile.

The following example implements client-side overzooming while continuing
to request only native tiles from Z7 through Z13.

const BATHYMETRY_API_KEY = 'YOUR_API_KEY';
const TILE_SIZE = 256;
const MIN_NATIVE_ZOOM = 7;
const MAX_NATIVE_ZOOM = 13;

const bathymetryOverlay = {
  tileSize: new google.maps.Size(TILE_SIZE, TILE_SIZE),

  getTile(coord, zoom, ownerDocument) {
    const canvas = ownerDocument.createElement('canvas');
    canvas.width = TILE_SIZE;
    canvas.height = TILE_SIZE;

    if (zoom < MIN_NATIVE_ZOOM) {
      return canvas;
    }

    const worldTileCount = 2 ** zoom;

    if (coord.y < 0 || coord.y >= worldTileCount) {
      return canvas;
    }

    // Normalize X so the overlay works when the map wraps around the world.
    const normalizedX =
      ((coord.x % worldTileCount) + worldTileCount) % worldTileCount;

    const sourceZoom = Math.min(zoom, MAX_NATIVE_ZOOM);
    const overzoomFactor = 2 ** (zoom - sourceZoom);

    const sourceX = Math.floor(normalizedX / overzoomFactor);
    const sourceY = Math.floor(coord.y / overzoomFactor);

    const childX = normalizedX % overzoomFactor;
    const childY = coord.y % overzoomFactor;

    const sourceSize = TILE_SIZE / overzoomFactor;

    const image = ownerDocument.createElement('img');

    image.src =
      `https://tiles.1224tools.com/v1/${sourceZoom}/${sourceX}/${sourceY}.png` +
      `?key=${BATHYMETRY_API_KEY}`;

    image.onload = () => {
      const context = canvas.getContext('2d');

      if (!context) {
        return;
      }

      context.imageSmoothingEnabled = true;
      context.imageSmoothingQuality = 'high';

      context.drawImage(
        image,
        childX * sourceSize,
        childY * sourceSize,
        sourceSize,
        sourceSize,
        0,
        0,
        TILE_SIZE,
        TILE_SIZE
      );
    };

    return canvas;
  },

  releaseTile(tile) {
    // No additional cleanup is required for this implementation.
  }
};

map.overlayMapTypes.insertAt(0, bathymetryOverlay);

Overzooming above Z13 enlarges existing Z13 content and does not introduce
additional bathymetric detail.

Adjusting Opacity

When using ImageMapType, opacity can be set directly on the
overlay.

bathymetryMapType.setOpacity(0.6);

Show or Hide the Layer

Overlay map types are stored in the map’s overlayMapTypes
collection. You can remove and insert the bathymetry overlay when users
enable or disable the layer.

// Hide the overlay at index 0
map.overlayMapTypes.removeAt(0);

// Show it again
map.overlayMapTypes.insertAt(0, bathymetryMapType);

Overlay Order

Google Maps renders overlay map types above the basemap. When multiple
overlay map types are present, overlays with higher indexes are displayed
in front of overlays with lower indexes.

Troubleshooting

Platform-specific rendering behavior may differ between the Google Maps
JavaScript API, native mobile SDKs and Flutter integrations.

If depth labels appear unusually small on iOS, or if bathymetry disappears
at certain zoom transitions in a Flutter integration, see the
Troubleshooting guide.

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.
• Tile X coordinates should be normalized when the map wraps horizontally.
• Platform-specific mobile rendering issues are documented separately in
  the Troubleshooting guide.