Surveys & Coverage

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)

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

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

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

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

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>"