# Verizon ThingSpace API Sample App Guide (v1) ## Overview The Verizon ThingSpace API Sample App is a open-source Python web application that demonstrates how to integrate with Verizon's ThingSpace IoT platform. This sample app provides developers with a practical example of authenticating with the ThingSpace API, managing device activations, retrieving service plans, and accessing device information. Feel free to modify and extend this open-source application to suit your needs. **Target Audience:** Developers building IoT applications that need to integrate with Verizon's ThingSpace platform for device management and connectivity services. ### Key Use Cases - **IoT Device Onboarding:** Streamline the process of activating new devices on the Verizon network - **Service Plan Management:** Query and manage connectivity service plans for your IoT devices - **Device Monitoring:** Retrieve real-time device information and status updates - **API Integration Testing:** Test ThingSpace API endpoints before implementing in production applications ## Quick Start ### Prerequisites Before running the sample app, ensure you have: - Python 3.8 or higher installed - Verizon ThingSpace API credentials (API key and secret) - A Verizon ThingSpace developer account - Git for cloning the repository ### Get Running in 3 Steps 1. **Try the Live Demo:** Visit the [sandbox environment](https://verizon-sample-python-app.netlify.app/) to explore the app's functionality immediately 2. **Clone and Setup:** Follow the installation steps below to run locally 3. **Configure API Keys:** Add your ThingSpace credentials to start making real API calls ## Links <CardGroup cols={2}> <Card title="View on GitHub" icon="Github" link="https://github.com/verizonlabs/thingspace-sample-app"> Access the complete source code, contribute to the project, or report issues. </Card> <Card title="🚀 Try Live Demo" link="https://verizon-sample-python-app.netlify.app/"> Explore the sample app in action with our hosted sandbox environment. Test all features without local setup. </Card> </CardGroup> ## Features ### Authentication Management - **Session Token Retrieval:** Secure authentication flow with ThingSpace API - **Access Token Handling:** Automatic token refresh and management - **Credential Validation:** Built-in validation for API keys and secrets ### Device Operations - **Device Activation:** Activate IoT devices on the Verizon network - **Device Information Retrieval:** Access detailed device status, connectivity info, and metadata - **Bulk Device Management:** Handle multiple devices efficiently ### Service Plan Management - **Plan Listing:** Retrieve available service plans for your account - **Plan Details:** Access pricing, data limits, and feature information - **Account Integration:** Seamlessly integrate with your ThingSpace account ### User Interface - **Intuitive Web Interface:** Clean, responsive design for easy navigation - **Real-time Updates:** Live status updates for API operations - **Error Handling:** Clear error messages and troubleshooting guidance ## Setup & Installation ### 1. Clone the Repository ```bash git clone https://github.com/verizonlabs/thingspace-sample-app.git cd verizon-sample-app ``` ### 2. Install Dependencies ```bash # Create virtual environment (recommended) python -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate # Install required packages pip install -r requirements.txt ``` ### 3. Configure Environment Variables Create a `.env` file in the project root: ```env VERIZON_API_KEY=your_api_key_here VERIZON_API_SECRET=your_api_secret_here VERIZON_BASE_URL=https://thingspace.verizon.com DEBUG=False ``` ### 4. Run the Application ```bash # Start the development server python app.py # Access the app at http://localhost:5000 ``` ## Usage ### Getting Started with the Sample App 1. **Launch the Application:** Start the local server or use the sandbox environment 2. **Authenticate:** Enter your ThingSpace API credentials to obtain session and access tokens 3. **Explore Features:** Navigate through the different sections to test API functionality ### Example Workflows #### Activating a New Device 1. Navigate to the "Device Activation" section 2. Enter device details (IMEI, ICCID, etc.) 3. Select appropriate service plan 4. Click "Activate Device" to process the request 5. Monitor activation status in real-time #### Retrieving Service Plans 1. Access the "Service Plans" section 2. Click "Load Plans" to fetch available options 3. Review plan details including data limits and pricing 4. Use plan IDs for device activation or management #### Checking Device Information 1. Go to "Device Information" section 2. Enter device identifier (IMEI or device ID) 3. View comprehensive device details including: - Connection status - Data usage - Location information - Service plan details ## Customization ### Extending the Sample App **Add New API Endpoints:** The modular structure allows easy integration of additional ThingSpace API endpoints: ```python # Example: Add location tracking endpoint @app.route('/device/location') def get_device_location(): # Implement location tracking logic pass ``` **Custom UI Components:** Modify the templates to match your application's branding and user experience requirements. **Database Integration:** Add persistent storage for device information, usage history, or user preferences. ### Configuration Options - **API Timeout Settings:** Adjust request timeout values in `config.py` - **Logging Levels:** Customize logging verbosity for development or production - **UI Themes:** Modify CSS files to implement custom styling ## Troubleshooting ### Common Issues **Authentication Errors** - **Problem:** "Invalid API credentials" or "Authentication failed" - **Solution:** Verify your API key and secret are correct and have proper permissions - **Check:** Ensure your ThingSpace account has API access enabled **Connection Timeouts** - **Problem:** API requests timing out or failing - **Solution:** Check your internet connection and ThingSpace service status - **Workaround:** Increase timeout values in the configuration **Device Activation Failures** - **Problem:** Device activation returns error codes - **Solution:** Verify device IMEI/ICCID format and ensure device is compatible with selected service plan - **Debug:** Check device eligibility in ThingSpace console **Missing Dependencies** - **Problem:** ImportError or ModuleNotFoundError - **Solution:** Run `pip install -r requirements.txt` to install all dependencies - **Environment:** Ensure you're using the correct Python version (3.8+) ### Debugging Tips - Enable debug mode by setting `DEBUG=True` in your environment variables - Check application logs for detailed error information - Use the sandbox environment to test API calls without affecting production data - Verify API rate limits aren't being exceeded ## Support ### Contributing We welcome contributions to improve the sample app: 1. Fork the repository 2. Create a feature branch 3. Make your changes 4. Submit a pull request with detailed description ### Reporting Issues If you encounter bugs or have feature requests, please open an issue on the [GitHub Issues page](https://github.com/verizonlabs/thingspace-sample-app/issues) ### Version Information - **Current Version:** v1.2.0 - **Python SDK Version:** verizon-sdk v2.1.0 - **Last Updated:** March 2024 - **Compatibility:** Python 3.8+, ThingSpace API v2.0 ## Additional Resources - [Verizon ThingSpace Platform Overview](https://thingspace.verizon.com/platform) - [Python SDK Documentation](https://github.com/verizon/verizon-python-sdk) - [IoT Device Integration Best Practices](https://thingspace.verizon.com/resources/best-practices) - [API Rate Limits and Usage Guidelines](https://thingspace.verizon.com/developer/rate-limits)