Retrieving Tiles

Tiles are standard XYZ resources. Use the survey id plus z/x/y coordinates, then stream the PNG/JPEG response to disk, cloud storage, or a CDN cache.

Tile URL Template

https://api.nearspacelabs.net/tile/v2/{surveyid}/{z}/{x}/{y}

Browsing with the Basemap Keyword

Don't have a specific survey in mind? Use the keyword basemap in place of the survey id to browse the latest imagery across all available surveys. The tile server returns the most recent tile it has for each z/x/y, so you can pan and zoom a continuous map without choosing a survey first.

https://api.nearspacelabs.net/tile/v2/basemap/{z}/{x}/{y}

For example, https://api.nearspacelabs.net/tile/v2/basemap/18/71276/110648 returns the latest tile at that location. The same zoom levels, formats, and authentication apply — send your Bearer token or ?api_key= just as you would for a survey-specific tile.

tip

basemap pairs well with a static API key: a single tile URL with ?api_key= that needs no survey lookup and no token refresh — ideal for drop-in web maps.

Specifications

Spec	Value
Min zoom	14
Max zoom	21
Formats	PNG, JPEG
Tile size	256 × 256 px

Out-of-Bounds Tiles

If you request a tile at coordinates where no imagery exists, the API returns 404 Not Found. Handle this gracefully — render a transparent placeholder, skip the tile, or fall back to a basemap.

tip

Use the /tile/v2/{survey_id}/coverage endpoint first to enumerate valid tile coordinates for an AOI and avoid unnecessary 404s.

Download Examples

Python

import requests

NSL_ID = "YOUR NSL ID"
NSL_SECRET = "YOUR NSL SECRET"
TILE_SERVER_URL = "https://api.nearspacelabs.net/tile/v2/2024Q4-FL-PTCH/{z}/{x}/{y}"

# Request a token and add it to the Authorization header
my_token = get_auth_token()
headers = {'Authorization': f'Bearer {my_token}'}

X = 71276
Y = 110648
Z = 18

with requests.get(
    TILE_SERVER_URL.format(z=Z, x=X, y=Y),
    headers=headers,
    stream=True
) as req:
    req.raise_for_status()
    local_file = f'{Z}_{X}_{Y}.png'
    with open(local_file, 'wb') as f:
        for chunk in req.iter_content(chunk_size=8192):
            f.write(chunk)

JavaScript

const fetch = require('node-fetch');
const fs = require('fs');

async function downloadTile() {
  const token = await getAuthToken();
  const headers = { 'Authorization': `Bearer ${token}` };

  const X = 71276;
  const Y = 110648;
  const Z = 18;

  const TILE_SERVER_URL =
    `https://api.nearspacelabs.net/tile/v2/2024Q4-FL-PTCH/${Z}/${X}/${Y}`;

  const response = await fetch(TILE_SERVER_URL, { headers });
  if (!response.ok) {
    throw new Error(`HTTP error! Status: ${response.status}`);
  }

  const localFile = `${Z}_${X}_${Y}.png`;
  const buffer = await response.buffer();
  fs.writeFileSync(localFile, buffer);
  console.log(`Tile downloaded to ${localFile}`);
}

downloadTile().catch(console.error);