Documentation

Current Weather & Forecasts

Get real-time weather conditions and comprehensive forecasts for any location worldwide. Our weather data comes from a global network of meteorological stations and advanced weather models.

Current Weather Conditions

Get Current Weather

Retrieve real-time weather conditions including temperature, humidity, wind, and atmospheric data.

Endpoint: GET /weather/current

Parameters

Parameter	Type	Required	Description
`lat`	number	Yes	Latitude (-90 to 90)
`lon`	number	Yes	Longitude (-180 to 180)
`units`	string	No	Temperature units: `metric`, `imperial`, `kelvin`
`lang`	string	No	Language for weather descriptions (default: `en`)

Example Request

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

Example Response

Code(json)
 
{
  "location": {
    "lat": 51.5074,
    "lon": -0.1278,
    "name": "London",
    "country": "United Kingdom",
    "region": "England",
    "timezone": "Europe/London"
  },
  "current": {
    "temperature": 18.3,
    "feels_like": 17.8,
    "humidity": 72,
    "pressure": 1015.4,
    "wind_speed": 4.1,
    "wind_direction": 225,
    "visibility": 8.5,
    "uv_index": 3.2,
    "condition": {
      "main": "Rain",
      "description": "Light rain",
      "icon": "10d"
    }
  },
  "timestamp": "2024-01-15T16:45:00Z"
}

Weather Forecasts

Standard Weather Forecast

Get detailed weather predictions for up to 16 days, including hourly and daily forecasts.

Endpoint: GET /weather/forecast

Parameters

Parameter	Type	Required	Description
`lat`	number	Yes	Latitude coordinate
`lon`	number	Yes	Longitude coordinate
`days`	integer	No	Number of forecast days (1-16, default: 7)
`hourly`	boolean	No	Include hourly data (default: false)
`units`	string	No	Unit system (default: metric)

Example Request

Code(bash)
 
curl -X GET "https://api.supaweather.com/v2/weather/forecast?lat=37.7749&lon=-122.4194&days=5&hourly=true" \
  -H "X-API-Key: your-api-key-here"

Example Response

Code(json)
 
{
  "location": {
    "lat": 37.7749,
    "lon": -122.4194,
    "name": "San Francisco",
    "country": "United States",
    "region": "California",
    "timezone": "America/Los_Angeles"
  },
  "forecast": {
    "daily": [
      {
        "date": "2024-01-16",
        "temperature": {
          "min": 12.1,
          "max": 19.4
        },
        "condition": {
          "main": "Clouds",
          "description": "Partly cloudy",
          "icon": "02d"
        },
        "precipitation": {
          "probability": 20,
          "amount": 0.0
        },
        "wind": {
          "speed": 5.2,
          "direction": 270
        }
      }
    ],
    "hourly": [
      {
        "datetime": "2024-01-16T00:00:00Z",
        "temperature": 14.2,
        "condition": {
          "main": "Clear",
          "description": "Clear sky",
          "icon": "01n"
        },
        "precipitation": 0.0,
        "wind_speed": 3.8
      }
    ]
  }
}

Marine Weather Forecast

Specialized forecasts for marine and coastal areas, including wave conditions, tides, and sea temperature.

Endpoint: GET /weather/forecast/marine

Parameters

Parameter	Type	Required	Description
`lat`	number	Yes	Latitude coordinate
`lon`	number	Yes	Longitude coordinate
`days`	integer	No	Forecast days (1-7, default: 3)

Example Request

Code(bash)
 
curl -X GET "https://api.supaweather.com/v2/weather/forecast/marine?lat=25.7617&lon=-80.1918&days=3" \
  -H "X-API-Key: your-api-key-here"

Example Response

Code(json)
 
{
  "location": {
    "lat": 25.7617,
    "lon": -80.1918,
    "name": "Miami Beach",
    "country": "United States",
    "region": "Florida",
    "timezone": "America/New_York"
  },
  "marine_forecast": [
    {
      "date": "2024-01-16",
      "wave_height": {
        "significant": 1.2,
        "max": 1.8
      },
      "wave_period": 8.5,
      "wave_direction": 120,
      "sea_temperature": 24.3,
      "tide": {
        "high": [
          {
            "time": "06:23",
            "height": 0.8
          },
          {
            "time": "18:45",
            "height": 0.9
          }
        ],
        "low": [
          {
            "time": "00:12",
            "height": 0.1
          },
          {
            "time": "12:34",
            "height": 0.2
          }
        ]
      },
      "wind": {
        "speed": 6.2,
        "direction": 110,
        "gusts": 8.9
      },
      "visibility": 12.0
    }
  ]
}

Weather Stations

Find Nearby Weather Stations

Discover weather monitoring stations near any location to assess data quality and get station-specific observations.

Endpoint: GET /weather/stations

Parameters

Parameter	Type	Required	Description
`lat`	number	Yes	Latitude coordinate
`lon`	number	Yes	Longitude coordinate
`radius`	integer	No	Search radius in km (1-100, default: 50)
`limit`	integer	No	Max stations to return (1-50, default: 10)

Example Request

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

Example Response

Code(json)
 
{
  "stations": [
    {
      "id": "KNYC",
      "name": "Central Park Weather Station",
      "location": {
        "lat": 40.7829,
        "lon": -73.9654,
        "name": "Central Park",
        "country": "United States",
        "region": "New York"
      },
      "elevation": 39.6,
      "distance": 6.2,
      "status": "active",
      "last_observation": "2024-01-15T16:00:00Z",
      "station_type": "automatic"
    },
    {
      "id": "KJFK",
      "name": "John F. Kennedy International Airport",
      "location": {
        "lat": 40.6413,
        "lon": -73.7781,
        "name": "JFK Airport",
        "country": "United States",
        "region": "New York"
      },
      "elevation": 3.4,
      "distance": 18.7,
      "status": "active",
      "last_observation": "2024-01-15T16:00:00Z",
      "station_type": "automatic"
    }
  ],
  "count": 2
}

Best Practices

Choosing Coordinates

Use decimal degrees format (e.g., 40.7128, -74.006)
Ensure latitude is between -90 and 90
Ensure longitude is between -180 and 180
For best accuracy, use coordinates with at least 4 decimal places

Forecast Accuracy

1-3 days: Highly accurate temperature and precipitation forecasts
4-7 days: Good accuracy for general conditions and trends
8-16 days: Useful for long-term planning, focus on general patterns

Performance Tips

Cache forecast data for 30-60 minutes to reduce API calls
Use the hourly=false parameter if you don't need hourly data
Consider using weather station data for hyperlocal conditions

Marine Forecasts

Marine forecasts are optimized for:

Coastal areas: Within 50km of coastline
Open ocean: Offshore maritime conditions
Large lakes: Great Lakes and similar water bodies

Wave height measurements:

Significant wave height: Average of the highest 1/3 of waves
Maximum wave height: Largest individual wave expected

Code Examples

JavaScript/Node.js

Code(javascript)
 
const axios = require("axios");

async function getCurrentWeather(lat, lon) {
  try {
    const response = await axios.get(
      "https://api.supaweather.com/v2/weather/current",
      {
        params: { lat, lon, units: "metric" },
        headers: { "X-API-Key": process.env.SUPAWEATHER_API_KEY },
      },
    );

    return response.data;
  } catch (error) {
    console.error("Weather API error:", error.response?.data || error.message);
    throw error;
  }
}

// Usage
getCurrentWeather(40.7128, -74.006)
  .then((weather) => console.log(weather))
  .catch((error) => console.error(error));

Python

Code(python)
 
import requests
import os

def get_weather_forecast(lat, lon, days=7):
    url = "https://api.supaweather.com/v2/weather/forecast"
    params = {
        "lat": lat,
        "lon": lon,
        "days": days,
        "units": "metric"
    }
    headers = {
        "X-API-Key": os.getenv("SUPAWEATHER_API_KEY")
    }

    response = requests.get(url, params=params, headers=headers)
    response.raise_for_status()

    return response.json()

# Usage
forecast = get_weather_forecast(51.5074, -0.1278, days=5)
print(f"5-day forecast for {forecast['location']['name']}")

PHP

Code(php)
 
<?php
function getMarineForecast($lat, $lon, $days = 3) {
    $url = "https://api.supaweather.com/v2/weather/forecast/marine";
    $params = http_build_query([
        'lat' => $lat,
        'lon' => $lon,
        'days' => $days
    ]);

    $context = stream_context_create([
        'http' => [
            'method' => 'GET',
            'header' => 'X-API-Key: ' . getenv('SUPAWEATHER_API_KEY')
        ]
    ]);

    $response = file_get_contents($url . '?' . $params, false, $context);
    return json_decode($response, true);
}

// Usage
$marineForecast = getMarineForecast(25.7617, -80.1918);
echo "Marine forecast: " . json_encode($marineForecast, JSON_PRETTY_PRINT);
?>

Historical Weather Data - Access past weather records
Weather Alerts - Get severe weather warnings
Radar & Satellite - Visual weather data

Last modified on July 7, 2025

Getting Started Alerts Advanced

Current Weather & Forecasts

Current Weather Conditions

Get Current Weather

Parameters

Example Request

Example Response

Weather Forecasts

Standard Weather Forecast

Parameters

Example Request

Example Response

Marine Weather Forecast

Parameters

Example Request

Example Response

Weather Stations

Find Nearby Weather Stations

Parameters

Example Request

Example Response

Best Practices

Choosing Coordinates

Forecast Accuracy

Performance Tips

Marine Forecasts

Code Examples

JavaScript/Node.js

Python

PHP

Related Endpoints