Skip to main content

​
Overview

Enhance your Stardeck applications by integrating external APIs for weather data, maps, email notifications, SMS, and other services. This guide covers setting up API accounts, configuring credentials in Stardeck, and using the AI agent to build integrations.
This guide uses a weather API as the main example, but the same principles apply to any external API integration.

​
Prerequisites

Before you begin, ensure you have:
  • An active Stardeck project
  • Familiarity with environment variables in Stardeck
  • An account with the API service you want to use
Here are some commonly integrated APIs:
  • Payment Gateways: Stripe, Omise, PayPal - See detailed payment integration guide
  • Weather: OpenWeatherMap, WeatherAPI, Tomorrow.io
  • Maps & Location: Google Maps, Mapbox, OpenStreetMap
  • Email: SendGrid, Mailgun, Resend
  • SMS: Twilio, MessageBird, Vonage
  • AI/ML: OpenAI, Anthropic, Google Gemini
  • Social Media: Twitter API, Instagram API, LinkedIn API
For payment gateway integrations (Stripe, Omise), check out our comprehensive Payment Gateway Integration Guide which covers credit card processing, webhooks, and Thai QR payments.

​
Setting Up OpenWeatherMap (Example)

We’ll use OpenWeatherMap as an example for this guide.

​
Creating an Account

  1. Go to openweathermap.org and click Sign In or Sign Up
  2. Complete the registration process
  3. Verify your email address
  4. You’ll be automatically enrolled in the Free tier
The free tier includes 1,000 API calls per day, which is perfect for development and small applications.

​
Getting Your API Key

  1. After signing in, go to your account page by clicking your username
  2. Navigate to the API keys tab
  3. You’ll see a default API key already created, or you can create a new one
  4. Copy your API key (starts with a long alphanumeric string)
API keys may take a few minutes to activate after account creation. If you get authentication errors, wait 10-15 minutes and try again.

​
Understanding API Limits

  • Free tier: 1,000 calls/day, 60 calls/minute
  • Data: Current weather, 5-day forecast, weather maps
  • Updates: Weather data updates every 10 minutes

​
Setting Up Other Common APIs

​
Google Maps API

  1. Go to Google Cloud Console
  2. Create a new project or select existing
  3. Enable Maps JavaScript API and Geocoding API
  4. Go to Credentials and create an API key
  5. Restrict the key by HTTP referrer (for security)

​
SendGrid (Email)

  1. Sign up at sendgrid.com
  2. Verify your sender email address
  3. Go to Settings > API Keys
  4. Create an API key with appropriate permissions
  5. Copy the key (shown only once)

​
Twilio (SMS)

  1. Sign up at twilio.com
  2. Get your free trial phone number
  3. Find your Account SID and Auth Token in the dashboard
  4. Copy both credentials

​
Configuring Environment Variables in Stardeck

Add your API credentials to your Stardeck project as environment variables.

​
Adding API Keys

  1. Open your project in the Stardeck dashboard
  2. Click the Settings button (gear icon)
  3. Navigate to the Environment Variables tab

​
OpenWeatherMap Configuration

​
API Key (Non-Secret)

  • Key: WEATHER_API_KEY
  • Value: Your OpenWeatherMap API key
  • Secret Variable: Off (unchecked)
  • Deployment Targets: Select Sandbox for testing
For public APIs like weather services, API keys can be non-secret if rate-limited per key. For production, consider marking as secret.

​
Google Maps Configuration

  • Key: GOOGLE_MAPS_API_KEY
  • Value: Your Google Maps API key
  • Secret Variable: Off (for client-side use) or On (for server-side)
  • Deployment Targets: Select Sandbox

​
SendGrid Configuration

  • Key: SENDGRID_API_KEY
  • Value: Your SendGrid API key (starts with SG.)
  • Secret Variable: On (checked) - always keep email API keys secret
  • Deployment Targets: Select Sandbox

​
Twilio Configuration

Add multiple variables for Twilio:
  • Key: TWILIO_ACCOUNT_SID
  • Value: Your Account SID
  • Secret Variable: Off
  • Key: TWILIO_AUTH_TOKEN
  • Value: Your Auth Token
  • Secret Variable: On (checked)
  • Key: TWILIO_PHONE_NUMBER
  • Value: Your Twilio phone number (e.g., +15551234567)
  • Secret Variable: Off

​
Using the AI Agent to Build API Integrations

Now you can use Stardeck’s AI agent to build your API integration. Here are example prompts for common scenarios:

​
Weather App with Current Conditions

Build a weather app that shows current weather for any city.

Requirements:
- Search box where users can enter a city name
- Display current temperature, weather condition, humidity, and wind speed
- Use OpenWeatherMap API with WEATHER_API_KEY environment variable
- Show a weather icon matching the condition
- Handle invalid city names gracefully

​
Weather Dashboard with Forecast

Create a weather dashboard for my local business showing the 5-day forecast.

Requirements:
- Display weather for my city (Bangkok) automatically
- Show 5-day forecast with daily high/low temperatures
- Use WEATHER_API_KEY to fetch data from OpenWeatherMap
- Update automatically every hour
- Show weather icons for each day

​
Location-Based Services with Maps

Add a store locator to my website with an interactive map.

Requirements:
- Display Google Map with markers for my 5 store locations
- Use GOOGLE_MAPS_API_KEY for the map
- Show store details (name, address, hours) when clicking markers
- Add a search box to find nearest store by address
- Mobile-responsive map

​
Email Notifications

Send confirmation emails to customers when they submit the contact form.

Requirements:
- Use SendGrid with SENDGRID_API_KEY to send emails
- Email template with our company logo and branding
- Include customer's message and contact details
- Send copy to our support email
- Handle send failures gracefully

​
SMS Alerts

Send SMS notifications to customers when their order is ready for pickup.

Requirements:
- Use Twilio with TWILIO_ACCOUNT_SID and TWILIO_AUTH_TOKEN
- Send SMS from TWILIO_PHONE_NUMBER
- Message format: "Your order #[ORDER_ID] is ready for pickup at [LOCATION]"
- Store SMS delivery status in database
- Only send to valid phone numbers

​
Multi-API Integration

Build a travel planning tool that combines weather and map data.

Requirements:
- Let users search for a destination
- Show the location on Google Maps using GOOGLE_MAPS_API_KEY
- Display current weather and 5-day forecast using WEATHER_API_KEY
- Show nearby attractions on the map
- Save favorite destinations to database

​
Tips for Effective Prompting

  1. Name your environment variables clearly - The agent will use them automatically
  2. Specify data to display - Be clear about what information you want to show
  3. Mention error handling - APIs can fail, timeout, or return errors
  4. Request caching - Consider asking to cache API responses to save costs
  5. Be specific about frequency - How often should data refresh?
The AI agent understands popular API formats and will implement proper error handling, rate limiting, and best practices automatically.

​
Testing Your Integration

​
Testing Weather API

Test with various scenarios:
  • Valid city: Try “London” or “Bangkok”
  • Invalid city: Try “XYZ123” to test error handling
  • Special characters: Try “São Paulo” to test encoding
  • Rate limits: Make multiple rapid requests to test rate limit handling

​
Testing Email/SMS APIs

For SendGrid and Twilio:
  • Use your personal email/phone during development
  • Check spam folder for test emails
  • Verify API call limits on dashboard
  • Test with invalid recipients to check error handling

​
Monitoring API Usage

  1. Check your API provider’s dashboard regularly
  2. Monitor daily usage against limits
  3. Set up alerts for high usage
  4. Review error logs for failed requests
Always test thoroughly in sandbox mode before deploying to production. Some APIs charge for usage beyond free tiers.

​
Best Practices

​
Security

  • Mark sensitive keys as secret - Email, SMS, and payment APIs should always be secret
  • Restrict API keys - Use HTTP referrer or IP restrictions when available
  • Rotate keys regularly - Change API keys periodically
  • Never commit keys to git - Always use environment variables

​
Performance

  • Cache API responses - Don’t fetch the same data repeatedly
  • Implement rate limiting - Respect API provider’s limits
  • Use webhooks when available - More efficient than polling
  • Handle errors gracefully - APIs can be temporarily unavailable

​
Cost Management

  • Monitor usage - Check dashboards regularly
  • Set spending limits - Use billing alerts
  • Choose the right tier - Upgrade only when needed
  • Optimize requests - Fetch only what you need

​
Going Live with Production

When you’re ready to go live:

​
Moving to Production

  1. Upgrade API plan if needed - Check if free tier is sufficient
  2. Get production API keys - Many services have separate prod keys
  3. Add production environment variables in Stardeck
  4. Set Deployment Targets to Production
  5. Configure webhooks - Update webhook URLs to production domain
  6. Test thoroughly - Verify all API integrations work in production

​
Production Checklist

  • Production API keys obtained
  • Billing/payment method configured with API provider
  • Usage alerts set up
  • API keys configured in Stardeck production environment
  • Error monitoring in place
  • Rate limits appropriate for production traffic
  • Webhook endpoints verified
  • Documentation for team members
Production API keys have different rate limits and may incur costs. Monitor usage closely after launch.

​
Additional Resources

​
Weather APIs

​
Maps & Location

​
Communication

​
AI & ML

Need help with API integration? Contact our support team through your dashboard or reach out to [email protected].