Documentation

Getting Started with SupaWeather API

Welcome to SupaWeather API v2.1.0! Our comprehensive weather API provides accurate, real-time weather information sourced from global meteorological stations and satellite data.

Quick Start

Authentication

SupaWeather API supports two authentication methods:

API Key Authentication

Add your API key to the request header:

Code(bash)
 
X-API-Key: your-api-key-here

Bearer Token Authentication

Use JWT tokens for authenticated requests:

Code(bash)
 
Authorization: Bearer your-jwt-token-here

Get Your API Key

1. Visit https://supaweather.com/api-keys
2. Sign up for a free account
3. Generate your API key from the dashboard
4. Choose your subscription plan based on your usage needs

Base URLs

• Production: https://api.supaweather.com/v2
• Staging: https://staging-api.supaweather.com/v2

Your First API Call

Here's how to get current weather conditions for New York City:

Code(bash)
 
curl -X GET "https://api.supaweather.com/v2/weather/current?lat=40.7128&lon=-74.006&units=metric" \
  -H "X-API-Key: your-api-key-here"

Response Example

Code(json)
 
{
  "location": {
    "lat": 40.7128,
    "lon": -74.006,
    "name": "New York",
    "country": "United States",
    "region": "New York",
    "timezone": "America/New_York"
  },
  "current": {
    "temperature": 22.5,
    "feels_like": 24.1,
    "humidity": 65,
    "pressure": 1013.2,
    "wind_speed": 3.2,
    "wind_direction": 220,
    "visibility": 10.0,
    "uv_index": 5.2,
    "condition": {
      "main": "Clouds",
      "description": "Partly cloudy",
      "icon": "02d"
    }
  },
  "timestamp": "2024-01-15T14:30:00Z"
}

Rate Limits

Our API includes rate limiting to ensure fair usage:

• Free Plan: 1,000 requests per day
• Basic Plan: 10,000 requests per day
• Pro Plan: 100,000 requests per day
• Enterprise: Custom limits

Rate limit headers are included in all responses:

• X-RateLimit-Limit: Your rate limit ceiling
• X-RateLimit-Remaining: Number of requests left
• X-RateLimit-Reset: UTC timestamp when the rate limit resets

Error Handling

All errors follow a consistent format:

Code(json)
 
{
  "error": "INVALID_PARAMETERS",
  "message": "Invalid latitude coordinate. Must be between -90 and 90.",
  "timestamp": "2024-01-15T12:00:00Z",
  "request_id": "req-123456789"
}

Common Error Codes

• 400 Bad Request: Invalid request parameters
• 401 Unauthorized: Invalid or missing API key
• 404 Not Found: Resource not available
• 429 Too Many Requests: Rate limit exceeded
• 500 Internal Server Error: Server error

Supported Units

Temperature Units

• metric: Celsius (default)
• imperial: Fahrenheit
• kelvin: Kelvin

Other Measurements

• Wind Speed: m/s (metric), mph (imperial)
• Pressure: hPa (hectopascals)
• Visibility: km (metric), miles (imperial)
• Precipitation: mm (metric), inches (imperial)

Next Steps

Now that you're set up, explore our comprehensive weather data:

• Current Weather & Forecasts - Real-time conditions and predictions
• Historical Data & Climate - Access decades of weather records
• Alerts & Advanced Features - Severe weather monitoring and specialized data

SDKs and Libraries

We provide official SDKs for popular programming languages:

• JavaScript/Node.js: npm install supaweather-sdk
• Python: pip install supaweather
• PHP: composer require supaweather/api-client
• Java: Available on Maven Central
• Go: go get github.com/supaweather/go-client

Support

Need help? We're here for you:

• 📧 Email: [email protected]
• 🌐 Support Portal: https://supaweather.com/support
• 📚 Documentation: This site!
• 💬 Discord: Join our developer community

Terms of Service

By using the SupaWeather API, you agree to our Terms of Service and Privacy Policy.