> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stardeck.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Integrating External APIs

> Learn how to integrate external APIs like weather services, maps, email providers, and more into your Stardeck applications

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

<Info>
  This guide uses a weather API as the main example, but the same principles apply to any external
  API integration.
</Info>

## Prerequisites

Before you begin, ensure you have:

* An active Stardeck app
* Familiarity with [environment variables](/environment-variables) in Stardeck
* An account with the API service you want to use

## Popular API Services

Here are some commonly integrated APIs:

* **Payment Gateways**: Stripe, Omise, PayPal - [See detailed payment integration guide](/payment-gateways)
* **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

<Note>
  For payment gateway integrations (Stripe, Omise), check out our comprehensive [Payment Gateway
  Integration Guide](/payment-gateways) which covers credit card processing, webhooks, and Thai QR
  payments.
</Note>

## Setting Up OpenWeatherMap (Example)

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

### Creating an Account

1. Go to [openweathermap.org](https://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**

<Note>
  The free tier includes 1,000 API calls per day, which is perfect for development and small
  applications.
</Note>

### 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)

<Warning>
  API keys may take a few minutes to activate after account creation. If you get authentication
  errors, wait 10-15 minutes and try again.
</Warning>

### 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](https://console.cloud.google.com)
2. Create a new app 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](https://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](https://www.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 app as environment variables.

### Adding API Keys

1. Open your app 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

<Note>
  For public APIs like weather services, API keys can be non-secret if rate-limited per key. For
  production, consider marking as secret.
</Note>

### 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

<Success>
  Your API credentials are now configured! The dev server will automatically restart to apply these
  changes.
</Success>

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

<Info>
  The AI agent understands popular API formats and will implement proper error handling, rate
  limiting, and best practices automatically.
</Info>

## 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

<Warning>
  Always test thoroughly in sandbox mode before deploying to production. Some APIs charge for usage
  beyond free tiers.
</Warning>

## 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

<Warning>
  Production API keys have different rate limits and may incur costs. Monitor usage closely after
  launch.
</Warning>

## Additional Resources

### Weather APIs

* [OpenWeatherMap Documentation](https://openweathermap.org/api)
* [WeatherAPI Docs](https://www.weatherapi.com/docs/)

### Maps & Location

* [Google Maps Platform](https://developers.google.com/maps/documentation)
* [Mapbox Documentation](https://docs.mapbox.com/)

### Communication

* [SendGrid Documentation](https://docs.sendgrid.com/)
* [Twilio Documentation](https://www.twilio.com/docs)

### AI & ML

* [OpenAI API Documentation](https://platform.openai.com/docs)
* [Anthropic API Documentation](https://docs.anthropic.com/)

***

Need help with API integration? Contact our support team through your dashboard or reach out to [support@stardeck.ai](mailto:support@stardeck.ai).