Imagery SDK Guide

The Urban Sky SDK now includes built-in support for accessing mission imagery through the Data Explorer API.

Quick Start

JavaScript

const { UrbanSkySDK } = require('@urbansky/sdk')

const sdk = await UrbanSkySDK.init({
  apiToken: 'your-api-token',
  baseUrl: 'https://api.ops.urbansky.com',
})

// List missions
const missions = await sdk.listMissions({ page: 1, limit: 50 })

// List images for a mission
const images = await sdk.listImages('mission-id', {
  page: 1,
  limit: 100,
  dateFrom: '2024-06-01T00:00:00Z',
  dateTo: '2024-06-30T23:59:59Z',
  altitudeMin: 15000,
  altitudeMax: 20000,
})

// Get signed URL for original image (valid 15 minutes)
const { url, expiresAt } = await sdk.getImageUrl('mission-id/path/image.jpg', {
  original: 'true',
})

// Get processed image URL
const thumbnail = await sdk.getImageUrl('mission-id/path/image.jpg', {
  w: 400,
  h: 300,
  fit: 'cover',
  format: 'webp',
  quality: 85,
})

// Get image metadata
const metadata = await sdk.getImageMetadata('mission-id/path/image.jpg')

Python

from urbansky_sdk import (
    UrbanSkySDK,
    ImageListOptions,
    ImageProcessingOptions,
    MissionListOptions
)

sdk = await UrbanSkySDK.init({
    'apiToken': 'your-api-token',
    'baseUrl': 'https://api.ops.urbansky.com'
})

# List missions
missions = sdk.list_missions(MissionListOptions(page=1, limit=50))

# List images for a mission
images = sdk.list_images(
    'mission-id',
    ImageListOptions(
        page=1,
        limit=100,
        date_from='2024-06-01T00:00:00Z',
        date_to='2024-06-30T23:59:59Z',
        altitude_min=15000,
        altitude_max=20000
    )
)

# Get signed URL for original image
signed_url = sdk.get_image_url(
    'mission-id/path/image.jpg',
    ImageProcessingOptions(original='true')
)

# Get processed image URL
thumbnail = sdk.get_image_url(
    'mission-id/path/image.jpg',
    ImageProcessingOptions(
        w=400,
        h=300,
        fit='cover',
        format='webp',
        quality=85
    )
)

# Get image metadata
metadata = sdk.get_image_metadata('mission-id/path/image.jpg')

Complete End-to-End Example

This example shows the entire flow from listing missions to downloading an image file. Perfect for testing in the browser console on ops.urbansky.com.

Browser Console (Complete Workflow)

// ============================================
// COMPLETE IMAGE DOWNLOAD WORKFLOW
// ============================================

const API_TOKEN = 'your-32-character-api-token-here'
const BASE_URL = 'https://api.ops.urbansky.com'
const MISSION_ID = 'your-mission-id'

;(async function downloadImageComplete() {
  try {
    console.log('🚀 Starting complete image download flow...\n')

    // STEP 1: List available missions
    console.log('📋 STEP 1: Listing missions...')
    const missionsResponse = await fetch(`${BASE_URL}/v1/images/missions`, {
      headers: {
        'x-api-token': API_TOKEN,
        'Content-Type': 'application/json',
      },
    })

    const missionsData = await missionsResponse.json()
    console.log(`✅ Found ${missionsData.totalCount} missions`)
    console.table(missionsData.missions)

    // STEP 2: List images for specific mission
    console.log(`\n🖼️  STEP 2: Listing images for mission: ${MISSION_ID}`)
    const imagesResponse = await fetch(
      `${BASE_URL}/v1/images/missions/${MISSION_ID}/images?limit=5`,
      {
        headers: {
          'x-api-token': API_TOKEN,
          'Content-Type': 'application/json',
        },
      },
    )

    const imagesData = await imagesResponse.json()
    console.log(
      `✅ Found ${imagesData.totalCount} images (showing first ${imagesData.images.length})`,
    )

    // Show image details
    imagesData.images.forEach((img, i) => {
      console.log(`\n  Image ${i + 1}: ${img.filename}`)
      console.log(`    Location: ${img.latitude}, ${img.longitude}`)
      console.log(`    Altitude: ${img.altitude}m`)
      console.log(`    Size: ${(img.size / 1024 / 1024).toFixed(2)} MB`)
    })

    // STEP 3: Get signed URL for first image
    const firstImage = imagesData.images[0]
    console.log(`\n🔗 STEP 3: Getting signed URL for: ${firstImage.filename}`)

    const signedUrlResponse = await fetch(
      `${BASE_URL}/v1/images?key=${encodeURIComponent(firstImage.key)}&original=true`,
      {
        headers: {
          'x-api-token': API_TOKEN,
          'Content-Type': 'application/json',
        },
      },
    )

    const signedUrlData = await signedUrlResponse.json()
    console.log('✅ Signed URL generated successfully!')
    console.log(`   Expires at: ${signedUrlData.expiresAt}`)

    // STEP 4: Download image from S3
    console.log(`\n💾 STEP 4: Downloading image from S3...`)
    console.log('   Making direct request to S3 (no API token needed!)...')

    const imageResponse = await fetch(signedUrlData.url)
    const blob = await imageResponse.blob()

    console.log(`✅ Image downloaded! Size: ${(blob.size / 1024 / 1024).toFixed(2)} MB`)

    // STEP 5: Save to browser
    console.log(`\n💿 STEP 5: Saving to your computer...`)

    // Create a download link
    const url = URL.createObjectURL(blob)
    const a = document.createElement('a')
    a.href = url
    a.download = firstImage.filename
    document.body.appendChild(a)
    a.click()
    document.body.removeChild(a)
    URL.revokeObjectURL(url)

    console.log(`✅ File saved as: ${firstImage.filename}`)
    console.log('   Check your Downloads folder!')

    // SUMMARY
    console.log('\n' + '='.repeat(50))
    console.log('🎉 COMPLETE! Summary:')
    console.log('='.repeat(50))
    console.log(`✅ API Authentication: Success`)
    console.log(`✅ Missions Found: ${missionsData.totalCount}`)
    console.log(`✅ Images Found: ${imagesData.totalCount}`)
    console.log(`✅ Signed URL Generated: Valid for ~15 minutes`)
    console.log(`✅ File Saved: ${firstImage.filename}`)
    console.log('='.repeat(50))

    return {
      mission: MISSION_ID,
      image: firstImage,
      signedUrl: signedUrlData,
      downloadedSize: blob.size,
    }
  } catch (error) {
    console.error('\n❌ ERROR:', error.message)
    throw error
  }
})()

Expected Output:

🚀 Starting complete image download flow...

📋 STEP 1: Listing missions...
✅ Found 9 missions
┌─────────┬──────────────┬─────────────────┐
│ (index) │      id      │      name       │
├─────────┼──────────────┼─────────────────┤
│    0    │ 'eLHyAqt6fy' │ 'AEROS1'        │
│    1    │ 'raoaiVxYim' │ 'AEROS2'        │
└─────────┴──────────────┴─────────────────┘

🖼️  STEP 2: Listing images for mission: eLHyAqt6fy
✅ Found 234 images (showing first 5)

  Image 1: IMG_0001.jpg
    Location: 39.7392, -104.9903
    Altitude: 15240m
    Size: 5.24 MB

🔗 STEP 3: Getting signed URL for: IMG_0001.jpg
✅ Signed URL generated successfully!
   Expires at: 2024-12-30T18:39:45.000Z

💾 STEP 4: Downloading image from S3...
✅ Image downloaded! Size: 5.24 MB

💿 STEP 5: Saving to your computer...
✅ File saved as: IMG_0001.jpg
   Check your Downloads folder!

==================================================
🎉 COMPLETE! Summary:
==================================================
✅ API Authentication: Success
✅ Missions Found: 9
✅ Images Found: 234
✅ Signed URL Generated: Valid for ~15 minutes
✅ File Saved: IMG_0001.jpg
==================================================

Key Points:

• ✅ Shows every step in the download process
• ✅ No external dependencies (works in browser console)
• ✅ Demonstrates API → Signed URL → S3 download flow
• ✅ Automatically saves file to Downloads folder
• ✅ Great for testing and understanding the complete workflow

Core Methods

listMissions(options?)

List available missions with pagination.

Parameters:

• options.page (number, optional): Page number (default: 1)
• options.limit (number, optional): Items per page, max 100 (default: 50)

Returns: MissionListResponse

• missions: Array of mission objects with id and name
• totalCount: Total number of missions
• pagination: Pagination metadata

listImages(missionId, options?)

List images for a specific mission with filtering and pagination.

Parameters:

• missionId (string, required): Mission identifier
• options.page (number, optional): Page number (default: 1)
• options.limit (number, optional): Items per page, max 1000 (default: 50)
• options.dateFrom (string, optional): Start date filter (ISO 8601)
• options.dateTo (string, optional): End date filter (ISO 8601)
• options.altitudeMin (number, optional): Minimum altitude in meters
• options.altitudeMax (number, optional): Maximum altitude in meters
• options.latitudeMin (number, optional): Minimum latitude (-90 to 90)
• options.latitudeMax (number, optional): Maximum latitude (-90 to 90)
• options.longitudeMin (number, optional): Minimum longitude (-180 to 180)
• options.longitudeMax (number, optional): Maximum longitude (-180 to 180)

Returns: ImageListResponse

• images: Array of image metadata objects
• totalCount: Total number of images matching filters
• pagination: Pagination metadata

getImageUrl(key, options?)

Get a pre-signed S3 URL to download or process an image. URLs are valid for approximately 15 minutes.

Parameters:

• key (string, required): Image key (format: missionId/path/to/image.jpg)
• options.original (string, optional): Set to 'true' for original unprocessed image
• options.w (number, optional): Width in pixels
• options.h (number, optional): Height in pixels
• options.fit (string, optional): Resize mode: 'cover', 'contain', 'inside', 'outside', 'fill'
• options.format (string, optional): Output format: 'jpeg', 'png', 'webp', 'avif', 'tiff', 'gif'
• options.quality (number, optional): Quality 1-100 (higher is better)
• options.colormap (string, optional): Color map for scientific visualization: 'normal', 'thermal', 'viridis', 'plasma', 'inferno'
• options.preserveValues (boolean, optional): Preserve measurement values during processing
• options.displayMode (string, optional): Display mode: 'auto', 'scientific', 'standard'
• options.targetRange (string, optional): Target range for value mapping

Returns: SignedUrlResponse

• url: Pre-signed S3 URL (valid ~15 minutes)
• expiresAt: Expiration timestamp
• metadata: Additional metadata including the original key

getImageMetadata(key)

Get metadata for an image without downloading it.

Parameters:

• key (string, required): Image key (format: missionId/path/to/image.jpg)

Returns: ImageMetadata

• key: Image key
• filename: Original filename
• timestamp: Capture timestamp (ISO 8601)
• latitude: Capture latitude (optional)
• longitude: Capture longitude (optional)
• altitude: Capture altitude in meters (optional)
• size: File size in bytes (optional)

Image Processing Options

Resize and Format Conversion

// Resize to 800x600 WebP with 85% quality
const url = await sdk.getImageUrl('mission-id/image.jpg', {
  w: 800,
  h: 600,
  fit: 'cover',
  format: 'webp',
  quality: 85,
})

// Create thumbnail maintaining aspect ratio
const thumb = await sdk.getImageUrl('mission-id/image.jpg', {
  w: 400,
  format: 'jpeg',
  quality: 80,
})

Fit Modes:

• cover: Crop to fill dimensions
• contain: Fit within dimensions (letterbox)
• inside: Resize to fit inside dimensions
• outside: Resize to fit outside dimensions
• fill: Stretch to fill dimensions

Scientific Visualization

// Apply thermal colormap to temperature data
const thermal = await sdk.getImageUrl('mission-id/thermal-image.tiff', {
  colormap: 'thermal',
  format: 'png',
})

// Preserve exact measurement values
const scientific = await sdk.getImageUrl('mission-id/data-image.tiff', {
  displayMode: 'scientific',
  preserveValues: true,
  format: 'tiff',
})

Available Colormaps:

• normal: Standard RGB rendering
• thermal: Hot-to-cold temperature scale
• viridis: Perceptually uniform, colorblind-friendly
• plasma: Bright colormap for highlighting
• inferno: Dark-to-bright intensity scale

Filtering Examples

Filter by Date Range

const images = await sdk.listImages('mission-id', {
  dateFrom: '2024-06-01T00:00:00Z',
  dateTo: '2024-06-30T23:59:59Z',
})

Filter by Altitude

const images = await sdk.listImages('mission-id', {
  altitudeMin: 15000, // 15km
  altitudeMax: 20000, // 20km
})

Filter by Geographic Bounding Box

const images = await sdk.listImages('mission-id', {
  latitudeMin: 39.0,
  latitudeMax: 40.0,
  longitudeMin: -105.5,
  longitudeMax: -104.5,
})

Combine Multiple Filters

const images = await sdk.listImages('mission-id', {
  dateFrom: '2024-06-15T00:00:00Z',
  altitudeMin: 15000,
  latitudeMin: 39.0,
  latitudeMax: 40.0,
  page: 1,
  limit: 100,
})

Pagination

Results are paginated. Use the pagination metadata to iterate through pages:

let page = 1
let allImages = []

while (true) {
  const response = await sdk.listImages('mission-id', {
    page,
    limit: 100,
  })

  allImages.push(...response.images)

  if (!response.pagination.hasNextPage) {
    break
  }

  page++
}

console.log(`Total images downloaded: ${allImages.length}`)

Error Handling

try {
  const images = await sdk.listImages('mission-id')
} catch (error) {
  if (error.message.includes('401')) {
    console.error('Authentication failed - check API token')
  } else if (error.message.includes('403')) {
    console.error('Access denied - insufficient permissions')
  } else if (error.message.includes('404')) {
    console.error('Mission not found')
  } else if (error.message.includes('429')) {
    console.error('Rate limit exceeded - slow down requests')
  } else {
    console.error('Unexpected error:', error)
  }
}

Complete Download Example

const https = require('https')
const fs = require('fs')

async function downloadAllImages(missionId, outputDir) {
  let page = 1
  let totalDownloaded = 0

  while (true) {
    const response = await sdk.listImages(missionId, { page, limit: 100 })

    for (const image of response.images) {
      const signedUrl = await sdk.getImageUrl(image.key, { original: 'true' })
      const outputPath = `${outputDir}/${image.filename}`

      await downloadFile(signedUrl.url, outputPath)
      totalDownloaded++

      console.log(`Downloaded ${totalDownloaded}/${response.totalCount}: ${image.filename}`)
    }

    if (!response.pagination.hasNextPage) {
      break
    }

    page++
  }

  return totalDownloaded
}

function downloadFile(url, outputPath) {
  return new Promise((resolve, reject) => {
    https
      .get(url, response => {
        const fileStream = fs.createWriteStream(outputPath)
        response.pipe(fileStream)
        fileStream.on('finish', () => {
          fileStream.close()
          resolve()
        })
        fileStream.on('error', reject)
      })
      .on('error', reject)
  })
}

// Usage
await downloadAllImages('mission-id', './downloads')

TypeScript Support

Full TypeScript definitions are included:

import {
  UrbanSkySDK,
  Mission,
  ImageMetadata,
  ImageListOptions,
  ImageProcessingOptions,
  SignedUrlResponse,
} from '@urbansky/sdk'

const sdk = await UrbanSkySDK.init({
  apiToken: process.env.API_TOKEN!,
  baseUrl: 'https://api.ops.urbansky.com',
})

const missions: Mission[] = (await sdk.listMissions()).missions
const images: ImageMetadata[] = (await sdk.listImages(missions[0].id)).images
const signedUrl: SignedUrlResponse = await sdk.getImageUrl(images[0].key)

Best Practices

1. Respect URL Expiration: Signed URLs expire after ~15 minutes. Download immediately or request a new URL.

2. Use Appropriate Limits: Request only what you need. Max limits are 100 for missions, 1000 for images.

3. Add Delays: When downloading many images, add small delays between requests to be respectful:

   await new Promise(resolve => setTimeout(resolve, 500)) // 500ms delay

4. Handle Errors Gracefully: Network issues happen. Implement retry logic with exponential backoff.

5. Use Processing Options: Instead of downloading large originals and processing locally, use the API's built-in processing.

6. Cache Metadata: If you need to reference image metadata multiple times, cache it locally rather than requesting repeatedly.

See Also

• Full API Documentation
• Example Scripts
• Image API README