GET /weather

This endpoint fetches weather-related data for a list of cities specified in the user’s profile, using their stored preferences (like units, selected data fields, and language). It supports weather conditions, air quality, and UV index data.

🔐 Authentication

You must provide an API key either as a query parameter or in the headers:

Query: ?apiKey=YOUR_API_KEY
Header: Authorization: Bearer YOUR_API_KEY
Header: x-api-key: YOUR_API_KEY

🧩 Query Parameters

Name	Type	Required	Description
apiKey	string	No*	API key (alternative to headers)
format	string	No	Response format: `json` (default) or `xml`

🧾 Headers

Header	Value	Required
Authorization	`Bearer YOUR_API_KEY`	No
x-api-key	`YOUR_API_KEY`	No

📦 Response

Returns a list of cities with filtered weather data according to the user’s preferences. See Data Types → WeatherData for the full structure.

✅ Example Successful Response

1{
2"message": [
3  {
4    "city": "Paris",
5    "locale": "fr-FR",
6    "data": {
7      "icon": "https://cdn.skycaster.tv/set-1-gif/01d.gif",
8      "weather_description": "Clear sky",
9      "temperature": 18.5,
10      "humidity": 62,
11      "dew_point": 11.2,
12      "sunrise": "2025-05-17T05:55",
13      "sunset": "2025-05-17T20:10",
14      "heat_index": 18.5,
15      "air_quality": 2,
16      "ozone_level": 89.3
17    }
18  },
19  {
20    "city": "New York",
21    "locale": "en-US",
22    "data": {
23      "icon": "https://cdn.skycaster.tv/set-1-gif/02d.gif",
24      "weather_description": "Partly cloudy",
25      "temperature": 23.4,
26      "humidity": 70,
27      "dew_point": 17.1,
28      "sunrise": "2025-05-17T09:34",
29      "sunset": "2025-05-17T00:30",
30      "heat_index": 25.1
31    }
32  }
33]
34}

❌ Possible Errors

Status Code	Error Message	Description
401	`API key missing`	No valid API key was provided.
404	`No user found`	The API key did not match any stored user.
429	`Rate limit exceeded`	The user has exceeded their rate limit.
500	`Error fetching data`	An internal server error occurred.

⚙️ Internal Notes

Weather data is sourced from the Open-Meteo API.
Air quality data is fetched from the Open-Meteo Air Quality endpoint.
All temperature values are returned in the unit selected by the user (metric or imperial).
Special computed values: Dew Point and Heat Index are calculated from temperature and humidity.
Response is cached server-side for 10 minutes; Cache-Control: public, s-maxage=600.

See Data Types → WeatherData for the full response structure and available field names. Air quality fields (air_quality, ozone_level, pm2_5, etc.) are returned flat alongside weather fields in the same data object.

📞 Need Assistance?

If you have questions or need support:

Contact Support: Reach out via our Support Page .
Email Us: Send inquiries to support@skycaster.tv.