Weatherstack Getting Started: API Keys & First Request

Getting started overview

Integrating with Weatherstack requires obtaining an API access key and constructing HTTP GET requests to the appropriate endpoints. The API provides current weather, historical data, and forecasts, with responses delivered in JSON format. The core process involves:

1. Account Creation: Registering on the Weatherstack website to generate an API key.
2. API Key Retrieval: Locating the unique access_key in your account dashboard.
3. First Request: Sending an authenticated HTTP GET request to a Weatherstack endpoint with your API key and a location query.

This guide focuses on these initial steps to ensure a successful first interaction with the Weatherstack API. For a comprehensive overview of all available endpoints and parameters, consult the Weatherstack API documentation.

Quick start reference

The following table summarizes the essential steps for getting started:

Create an account and get keys

To begin using the Weatherstack API, you must register for an account and obtain your authentication credentials. Weatherstack offers a Free Plan that includes 250 requests per month, sufficient for initial testing and small projects.

Account registration

1. Navigate to the Weatherstack signup page.
2. Enter your email address and create a password.
3. Agree to the terms of service and complete the registration process.
4. You may receive an email to verify your account. Follow the instructions in the email to activate your account.

API key retrieval

Upon successful registration and login, your unique API access key will be displayed in your Weatherstack account dashboard. This key is a string of alphanumeric characters and is essential for authenticating all your API requests. Keep this key secure and do not expose it in client-side code or public repositories.

The API key is typically found under the 'API Access Key' section of your dashboard. It will look similar to YOUR_ACCESS_KEY_HERE.

Your first request

Once you have your API access key, you can make your first API call. This example demonstrates how to fetch current weather data for a specific location using the current endpoint. Weatherstack API requests are standard HTTP GET requests, and the API key is passed as a URL query parameter named access_key.

API endpoint structure

All Weatherstack API requests follow a base URL structure:

http://api.weatherstack.com/current
  ? access_key = YOUR_ACCESS_KEY
  & query = YOUR_LOCATION

• http://api.weatherstack.com/current: The base URL for current weather data. Weatherstack uses HTTP for requests on the free tier, but recommends HTTPS for paid plans to secure data in transit, as detailed in the Weatherstack security documentation. HTTPS encrypts data between the client and server, protecting against eavesdropping and tampering, a fundamental principle of internet security as described by the Mozilla Developer Network's HTTPS explanation.
• access_key: Your unique API access key.
• query: The location for which you want weather data (e.g., 'New York', 'London', '51.5,0.1').

Example request with cURL

cURL is a command-line tool and library for transferring data with URLs. It is commonly used for testing API endpoints.

curl "http://api.weatherstack.com/current?access_key=YOUR_ACCESS_KEY&query=New%20York"

Replace YOUR_ACCESS_KEY with your actual API key and New%20York with the desired location. The %20 is URL encoding for a space character.

Example response (JSON)

A successful request will return a JSON object similar to this (truncated for brevity):

{
  "request": {
    "type": "City",
    "query": "New York, United States of America",
    "language": "en",
    "unit": "m"
  },
  "current": {
    "observation_time": "03:10 PM",
    "temperature": 20,
    "weather_code": 113,
    "weather_icons": [
      "https://assets.weatherstack.com/images/wsymbols01_png_64/wsymbol_0001_sunny.png"
    ],
    "weather_descriptions": [
      "Sunny"
    ],
    "wind_speed": 0,
    "wind_degree": 0,
    "wind_dir": "N",
    "pressure": 1024,
    "precip": 0,
    "humidity": 60,
    "cloudcover": 0,
    "feelslike": 20,
    "uv_index": 6,
    "visibility": 16
  }
}

This response provides current weather conditions for New York, including temperature, weather description, humidity, and more. For details on all fields, refer to the Weatherstack current weather documentation.

Example request with Python

The requests library is a common choice for making HTTP requests in Python.

import requests

ACCESS_KEY = 'YOUR_ACCESS_KEY'
LOCATION = 'London'

params = {
    'access_key': ACCESS_KEY,
    'query': LOCATION
}

api_result = requests.get('http://api.weatherstack.com/current', params)
api_response = api_result.json()

if 'current' in api_response:
    temperature = api_response['current']['temperature']
    description = api_response['current']['weather_descriptions'][0]
    print(f"Current temperature in {LOCATION}: {temperature}°C, {description}")
else:
    print(f"Error: {api_response.get('error', 'Unknown error')}")

Remember to replace YOUR_ACCESS_KEY with your actual key.

Common next steps

After successfully making your first request, consider these common next steps for further integration:

• Explore other endpoints: Weatherstack offers historical weather data and weather forecasts. Understand the different endpoints and their parameters to retrieve specific data.
• Error handling: Implement robust error handling in your application. The API returns specific error codes and messages for invalid requests, rate limits, or other issues. The Weatherstack error codes documentation provides a complete list.
• Upgrade plan: If your project requires more than 250 requests per month, consider upgrading to a paid Weatherstack plan. Paid plans offer higher request volumes, HTTPS encryption, and additional features.
• Integrate into an application: Incorporate the API calls into your web application, mobile app, or backend service. Display current weather, provide forecast information, or use historical data for analysis.
• Caching: To optimize performance and reduce API call volume, implement caching mechanisms for weather data that does not change frequently.

Troubleshooting the first call

Encountering issues with your first API call is common. Here are some troubleshooting tips:

• Invalid API Key: Double-check that you have copied your access_key correctly from your Weatherstack dashboard. A common mistake is including extra spaces or incorrect characters.
• Missing API Key: Ensure the access_key parameter is present in your request URL. The API will return an authentication error if it's missing.
• Incorrect Endpoint: Verify that you are using the correct base URL for the desired data (e.g., /current, /historical, /forecast).
• Invalid Query: Ensure your query parameter is a valid location. The API supports various formats, including city names, IP addresses, and latitude/longitude coordinates. Test with a simple known location like 'London' or 'New York' first.
• Rate Limit Exceeded: If you are on the free plan, you are limited to 250 requests per month. If you exceed this, the API will return a rate limit error. Check your dashboard for your current usage.
• Network Issues: Confirm that your machine has an active internet connection and that no firewalls or proxies are blocking outgoing HTTP requests to api.weatherstack.com.
• Check Error Response: The Weatherstack API returns detailed error objects in JSON format. Always inspect the error field in the response for specific messages and codes, as described in the Weatherstack error documentation.