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:

• Node.js Official Download - Choose the LTS version
• Node.js Installation Guide - Step-by-step instructions
• Windows users: Consider using Node Version Manager for Windows
• Mac/Linux users: Consider using Node Version Manager (nvm)

Package Availability

Currently, the SDK is distributed via our CDN loader system. In the future, we may offer npm packages for JavaScript and pip packages for Python for easier installation.

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. Load the SDK

Select the SDK loader for your preferred language:

JavaScript/Node.js

// Dynamic loading for Node.js
const response = await fetch('https://sdk.atmosys.com/runtime/js/current/loader.js')
eval(await response.text())

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

# UrbanSkySDK is available after loading the script
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}")

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:

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.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.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?

• 📖 Check our Examples for common use cases
• 💬 Contact support through your Urban Sky dashboard
• 📧 Email us at support@atmosys.com

---

Ready for more? Explore our examples →