On this page

Use lightweight paginated catalog calls to find the right survey, then fetch the heavier geometry or coverage only when needed.

## Key Concepts

- `GET /tile/v2/surveys` returns ids, page info, capture windows, and links.
- Follow up with `/tile/v2/{survey_id}/footprint` for GeoJSON geometry.
- Optionally call `/tile/v2/{survey_id}/coverage` to retrieve tile metadata for a zoom + AOI.

**note**

Legacy `/tile/surveys` routes emit deprecation warnings—stick with the v2 paths.

## Essential Endpoints

### Surveys (paginated)

```text
GET /tile/v2/surveys?page=<n>
```

Returns survey metadata (id, acquisition window, cloud cover, paging controls). Ideal for building catalog browsers. Most recent surveys are at the top of the list.

**tip**

Page size is 25 by default.

### Survey Footprint

```text
GET /tile/v2/{survey_id}/footprint
```

Fetch the GeoJSON footprint + properties for a specific survey when you need geometry or capture timestamps.

**tip**

Cache footprints—geometry rarely changes once published.

### Coverage by AOI

```text
GET /tile/v2/surveys/coverage?wkt=<polygon>&zoom=<z>
```

Find surveys that intersect your WKT polygon. Responses include survey ids and metadata you can pipe into downstream queries.

**tip**

Send WKT in EPSG:4326; we return ISO‑8601 timestamps.

### Tile Metadata

```text
GET /tile/v2/{survey_id}/coverage?zoom=<z>&wkt=<polygon>
```

Returns tile footprints + static URLs for a single survey at a given zoom. Perfect for bulk downloads.

**tip**

Each metadata item already contains the full static tile URL.

## Code Examples

- Python
- JavaScript
- Bash

```python
import requests

def get_surveys_page(auth_token, page=1):
    url = "https://api.nearspacelabs.net/tile/v2/surveys"
    headers = {'Authorization': f'Bearer {auth_token}'}
    params = {'page': page}
    with requests.get(url, headers=headers, params=params) as req:
        req.raise_for_status()
        return req.json()

def get_survey_footprint(survey_id, auth_token):
    url = f"https://api.nearspacelabs.net/tile/v2/{survey_id}/footprint"
    headers = {'Authorization': f'Bearer {auth_token}'}
    with requests.get(url, headers=headers) as req:
        req.raise_for_status()
        return req.json().get('footprint')

# Usage
auth_token = get_auth_token()
page = get_surveys_page(auth_token, page=1)

if not page['results']:
    raise RuntimeError("No surveys returned")

survey_id = page['results'][0]['id']
footprint = get_survey_footprint(survey_id, auth_token)

print(f"First survey: {survey_id}")
print(f"Has next page: {page['has_next']}")
print(f"Footprint included: {bool(footprint)}")
```

```javascript
async function getSurveysPage(token, page = 1) {
  const response = await fetch(
    `https://api.nearspacelabs.net/tile/v2/surveys?page=${page}`,
    {
      headers: {
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json'
      }
    }
  );

if (!response.ok) {
    throw new Error(`HTTP error! Status: ${response.status}`);
  }

return response.json();
}

async function getSurveyFootprint(token, surveyId) {
  const response = await fetch(
    `https://api.nearspacelabs.net/tile/v2/${surveyId}/footprint`,
    {
      headers: { 'Authorization': `Bearer ${token}` }
    }
  );

if (!response.ok) {
    throw new Error(`HTTP error! Status: ${response.status}`);
  }

const data = await response.json();
  return data.footprint;
}

// Usage
const token = await getAuthToken();
const page = await getSurveysPage(token, 1);

if (!page.results.length) {
  throw new Error('No surveys were returned');
}

const surveyId = page.results[0].id;
const footprint = await getSurveyFootprint(token, surveyId);

console.log(`First survey: ${surveyId}`);
console.log(`Has next page: ${page.has_next}`);
console.log(`Footprint returned: ${Boolean(footprint)}`);
```

```bash
TOKEN="<your OAuth token>"

# Page through surveys
curl -s -H "Authorization: Bearer $TOKEN" \
  "https://api.nearspacelabs.net/tile/v2/surveys?page=1"

# Fetch a footprint once you pick a survey
curl -s -H "Authorization: Bearer $TOKEN" \
  "https://api.nearspacelabs.net/tile/v2/<survey_id>/footprint"

# Optional: tile metadata for a zoom level / AOI
curl -s -H "Authorization: Bearer $TOKEN" \
  "https://api.nearspacelabs.net/tile/v2/<survey_id>/coverage?zoom=14&wkt=<polygon_wkt>"
```