Urban Sky SDK

Appearance

Getting Started ​

Welcome to the Urban Sky SDK! This guide will help you get up and running with real-time balloon telemetry data in just a few minutes.

Need Help Getting Started?

New to coding? Check out our AI Assistant Guide for detailed prompts that can generate complete SDK implementations for your preferred language.

Overview ​

The Urban Sky SDK provides real-time access to balloon telemetry data including:

  • Location tracking with GPS coordinates and altitude
  • Real-time updates via WebSocket connections
  • Multi-language support with JavaScript and Python SDKs

Prerequisites ​

Before you begin, you'll need:

  • An Urban Sky account with API access
  • Node.js 18+ (for JavaScript) or Python 3.8+ (for Python)
  • An API token from your Urban Sky dashboard

Install Node.js (for JavaScript users) ​

If you don't have Node.js installed, download it from the official website:

Package Availability

The SDKs install via the CDN loader, which fetches the latest runtime at load time. The Python SDK requires centrifuge-python, which must be available in your environment (pip install centrifuge-python). The Python loader snippet also needs requests (pip install requests).

Quick Start ​

1. Get Your API Token ​

To get an API token:

  1. Contact Urban Sky support
  2. Provide your organization details
  3. Receive your API token via secure email

TIP

API tokens are scoped to your organization and provide access to your balloon data. Keep them secure and never commit them to version control. Use them only on server-side applications, not in client-side code.

2. Install the SDK ​

Install the SDK for your preferred language:

javascript
// Dynamic loading for Node.js - always fetches the latest SDK
const response = await fetch('https://sdk.atmosys.com/runtime/js/current/loader.js')
eval(await response.text())
python
# Dynamic loading for Python - always fetches the latest SDK
# Requires: pip install requests centrifuge-python
import requests

exec(requests.get('https://sdk.atmosys.com/runtime/py/current/loader.py').text)

3. Initialize the SDK ​

javascript
// UrbanSkySDK is available globally after loading
const sdk = await UrbanSkySDK.init({
  apiToken: 'your-api-token-here',
  // baseUrl: 'custom-api-url' // Optional: only needed for custom deployments
})
python
from urbansky_sdk import UrbanSkySDK

sdk = await UrbanSkySDK.init({
    'apiToken': 'your-api-token-here'
    # 'baseUrl': 'custom-api-url'  # Optional: only needed for custom deployments
})

4. Connect and Listen for Updates ​

javascript
// Listen for balloon updates
sdk.on('balloon:update', update => {
  console.log('Received balloon update:', {
    balloonId: update.balloonId,
    missionId: update.missionId,
    deviceCount: update.devices.length,
  })

  // Process each device in the balloon
  update.devices.forEach(device => {
    console.log(`Device ${device.deviceId} (${device.deviceType}):`)
    console.log(`  Location: ${device.lat}, ${device.lng}`)
    console.log(`  Timestamp: ${device.timestamp}`)
  })
})

// Handle connection events
sdk.on('connected', () => {
  console.log('Connected to Urban Sky telemetry feed')
})

sdk.on('disconnected', () => {
  console.log('Disconnected from telemetry feed')
})

sdk.on('error', error => {
  console.error('SDK Error:', error)
})

// SDK is already connected via init()
console.log('SDK connected successfully!')
python
# Define event handlers
def on_balloon_update(update):
    print(f"Received balloon update: {update.balloon_id}")
    print(f"Mission: {update.mission_id}")
    print(f"Devices: {len(update.devices)}")

    # Process each device in the balloon
    for device in update.devices:
        print(f"Device {device.device_id} ({device.device_type}):")
        print(f"  Location: {device.lat}, {device.lng}")
        print(f"  Timestamp: {device.timestamp}")

# Handlers always receive one payload argument, even for connection events
def on_connected(_):
    print("Connected to Urban Sky telemetry feed")

def on_disconnected(_):
    print("Disconnected from telemetry feed")

def on_error(error):
    print(f"SDK Error: {error}")

# Register event handlers
sdk.on('balloon:update', on_balloon_update)
sdk.on('connected', on_connected)
sdk.on('disconnected', on_disconnected)
sdk.on('error', on_error)

# SDK is already connected via .init() - no need to call connect again
print("SDK connected successfully!")

Understanding Balloon Updates ​

Each balloon update contains the following fields. The names below are the JavaScript/wire form (camelCase); the Python SDK converts these to snake_case dataclass attributes before your handler sees them, so balloonId in JavaScript is update.balloon_id in Python.

typescript
interface BalloonUpdate {
  balloonId: string // Unique balloon identifier
  missionId: string // Associated mission ID
  devices: Device[] // Array of device telemetry
}

interface Device {
  deviceId: string // Unique device identifier
  deviceType: string // Device type (PLD, APX, BLS, etc.)
  lat: number // Latitude (decimal degrees)
  lng: number // Longitude (decimal degrees)
  altitude?: number // Altitude in meters
  timestamp: string // ISO 8601 timestamp
}

Testing Your Implementation ​

You can test your SDK integration using our test endpoint:

javascript
// Send a test balloon update to verify your implementation
const testResponse = await fetch('https://api.ops.atmosys.com/sdk/test/balloon', {
  method: 'POST',
  headers: {
    'x-api-token': 'your-api-token',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})

if (testResponse.ok) {
  console.log('Test message sent - you should receive it via your SDK listener')
}
python
import requests

# Send a test balloon update to verify your implementation
response = requests.post(
    'https://api.ops.atmosys.com/sdk/test/balloon',
    headers={
        "x-api-token": "your-api-token",
        "Content-Type": "application/json"
    },
    json={}
)

if response.ok:
    print("Test message sent - you should receive it via your SDK listener")

Error Handling ​

Always implement proper error handling for production applications:

javascript
sdk.on('error', error => {
  console.error('SDK Error:', error.message)

  // Handle different error types
  if (error.code === 'AUTHENTICATION_FAILED') {
    console.error('Invalid API token')
  } else if (error.code === 'CONNECTION_LOST') {
    console.log('Connection lost, attempting to reconnect...')
    // SDK will automatically attempt to reconnect
  }
})

// SDK is already connected via init()
// Error handling is done in the init() call above
python
def on_error(error):
    print(f"SDK Error: {error.message}")

    # Handle different error types
    if error.code == 'AUTHENTICATION_FAILED':
        print("Invalid API token")
    elif error.code == 'CONNECTION_LOST':
        print("Connection lost, attempting to reconnect...")
        # SDK will automatically attempt to reconnect

sdk.on('error', on_error)

# SDK is already connected via .init()
# Error handling is done in the init() call above

Configuration Options ​

The SDK accepts minimal configuration - most options have sensible defaults:

javascript
const sdk = await UrbanSkySDK.init({
  apiToken: 'your-token', // Required: Your API token
  baseUrl: 'custom-api-url', // Optional: Only needed for custom deployments
})
python
sdk = await UrbanSkySDK.init({
    'apiToken': 'your-token',       # Required: Your API token
    'baseUrl': 'custom-api-url'     # Optional: Only needed for custom deployments
})

Next Steps ​

Now that you have the SDK connected and receiving balloon updates, you can:

  1. Explore Examples - See more detailed usage examples
  2. Read API Reference - Dive deep into the SDK API
  3. Handle Errors - Implement robust error handling

Need Help? ​

Ready for more? Explore our examples →

Copyright © 2024 Urban Sky