On this page

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

```text
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.

```text
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](https://docs.nearspacelabs.com/authentication#static-api-keys-long-lived): 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
- JavaScript

```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);
```

- [Tile URL Template](https://docs.nearspacelabs.com/retrieving-tiles/#tile-url-template)
- [Browsing with the Basemap Keyword](https://docs.nearspacelabs.com/retrieving-tiles/#browsing-with-the-basemap-keyword)
- [Specifications](https://docs.nearspacelabs.com/retrieving-tiles/#specifications)
- [Out-of-Bounds Tiles](https://docs.nearspacelabs.com/retrieving-tiles/#out-of-bounds-tiles)
- [Download Examples](https://docs.nearspacelabs.com/retrieving-tiles/#download-examples)