API Documentation

Technical documentation for Weather Dashboard API integration

Note: Weather Dashboard uses WeatherAPI.com as its data provider. This documentation explains how our application interfaces with the WeatherAPI service.

Introduction

Weather Dashboard provides real-time weather data, forecasts, and city search capabilities through integration with the WeatherAPI service. The application makes client-side API requests to fetch weather information.

Base URL

https://api.weatherapi.com/v1/

Authentication

All API requests require an API key for authentication. The key is included as a query parameter:

?key=YOUR_API_KEY
Security Note: In production environments, API keys should be stored securely on the server-side and never exposed in client-side code.

API Endpoints

1. Current Weather

Retrieve real-time weather data for a specified location.

GET /current.json

Parameters

Parameter Type Required Description
key string Required Your API key
q string Required Location query (city name, coordinates, IP, etc.)
aqi string Optional Include air quality data (yes/no). Default: no

Example Request

GET https://api.weatherapi.com/v1/current.json?key=YOUR_API_KEY&q=Kolkata&aqi=yes

Example Response

{ "location": { "name": "Kolkata", "region": "West Bengal", "country": "India", "lat": 22.57, "lon": 88.37, "tz_id": "Asia/Kolkata" }, "current": { "temp_c": 28.5, "temp_f": 83.3, "condition": { "text": "Partly cloudy", "icon": "//cdn.weatherapi.com/weather/64x64/day/116.png" }, "wind_kph": 15.1, "humidity": 72, "feelslike_c": 31.2, "uv": 6, "air_quality": { "us-epa-index": 3 } } }

2. Weather Forecast

Get weather forecast for up to 14 days.

GET /forecast.json

Parameters

Parameter Type Required Description
key string Required Your API key
q string Required Location query
days integer Required Number of forecast days (1-14)
aqi string Optional Include air quality data
alerts string Optional Include weather alerts

Example Request

GET https://api.weatherapi.com/v1/forecast.json?key=YOUR_API_KEY&q=Mumbai&days=7

3. Search/Autocomplete

Search for cities and get autocomplete suggestions.

GET /search.json

Parameters

Parameter Type Required Description
key string Required Your API key
q string Required Search query (minimum 2 characters)

Example Request

GET https://api.weatherapi.com/v1/search.json?key=YOUR_API_KEY&q=Delh

Example Response

[ { "id": 2295019, "name": "Delhi", "region": "Delhi", "country": "India", "lat": 28.67, "lon": 77.22, "url": "delhi-delhi-india" }, { "id": 2295020, "name": "New Delhi", "region": "Delhi", "country": "India", "lat": 28.6, "lon": 77.2, "url": "new-delhi-delhi-india" } ]

Common Response Fields

Location Object

Field Type Description
name string City/location name
region string State/province name
country string Country name
lat number Latitude coordinate
lon number Longitude coordinate
tz_id string Timezone identifier
localtime string Local date and time

Current Weather Object

Field Type Description
temp_c number Temperature in Celsius
temp_f number Temperature in Fahrenheit
condition object Weather condition details
wind_kph number Wind speed in km/h
humidity number Humidity percentage
feelslike_c number Feels like temperature in Celsius
uv number UV index
vis_km number Visibility in kilometers
pressure_mb number Atmospheric pressure in millibars
gust_kph number Wind gust speed in km/h

Rate Limits & Best Practices

Rate Limiting

WeatherAPI implements rate limiting based on your subscription plan:

Best Practices

  1. Cache responses: Store weather data temporarily to avoid redundant API calls
  2. Debounce search: Wait for user to finish typing before making autocomplete requests
  3. Batch requests: If loading multiple cities, add delays between requests
  4. Handle errors: Implement proper error handling for network failures and API errors
  5. Use coordinates: For more precise location data, use latitude/longitude instead of city names
  6. Monitor usage: Track your API usage to stay within rate limits

Error Handling

Common Error Codes

Code Message Description
400 Bad Request Invalid parameters or malformed request
401 Unauthorized Invalid API key
403 Forbidden API key disabled or exceeded quota
404 Not Found Location not found
500 Internal Server Error Server-side error

Error Response Example

{ "error": { "code": 1006, "message": "No matching location found." } }

JavaScript Implementation Example

Fetching Current Weather

async function fetchCurrentWeather(city) { const apiKey = 'YOUR_API_KEY'; const url = `https://api.weatherapi.com/v1/current.json?key=${apiKey}&q=${city}&aqi=yes`; try { const response = await fetch(url); if (!response.ok) { throw new Error(`HTTP error! status: ${response.status}`); } const data = await response.json(); return data; } catch (error) { console.error('Error fetching weather:', error); throw error; } } // Usage fetchCurrentWeather('Kolkata') .then(data => console.log(data)) .catch(error => console.error(error));

Additional Resources