OpenWeatherMap API Getting Started: Quickstart Guide (2026)

Getting started overview

Integrating with the OpenWeatherMap API requires obtaining an API key and constructing URL requests to specific endpoints. The API offers access to current weather conditions, forecasts, and historical data, with various plans available from a free tier to paid subscriptions offering higher call limits and data granularity. This guide covers the essential steps to make your initial API call.

Before making requests, ensure you have an active API key, which is generated upon account registration. OpenWeatherMap API requests are typically made over HTTPS with parameters specified in the URL query string, including geographic coordinates or city names, and your unique API key. The API returns data in JSON format.

Quick Reference Steps

Create an account and get keys

To begin using the OpenWeatherMap API, you must first create an account and obtain an API key. This key authenticates your requests and links them to your usage plan.

Account Registration

1. Navigate to the OpenWeatherMap website.
2. Click on the "Sign Up" or "Registration" link, typically found in the top right corner.
3. Complete the registration form with your email, desired username, and password.
4. Accept the terms and conditions.
5. You may need to verify your email address by clicking a link sent to your inbox.

Obtaining Your API Key

Upon successful registration and login, an API key is automatically generated for your account. You can find this key in your profile settings or the API keys section of the OpenWeatherMap dashboard.

1. Log in to your OpenWeatherMap account.
2. Go to the "API keys" tab.
3. Your default API key will be displayed. You can also generate additional keys if needed for different projects or environments.
4. Copy this key. It is a hexadecimal string and will be required for every API request you make.

Note that newly generated API keys may take a few minutes, or in some cases up to an hour, to become active (OpenWeatherMap FAQ on API Key Activation).

Your first request

After obtaining your API key, you can make your first API call. This example demonstrates fetching current weather data for a specific city using the Current Weather Data API endpoint. We will use cURL for simplicity, but the principles apply to any HTTP client library.

Current Weather Data Endpoint

The base URL for current weather data is https://api.openweathermap.org/data/2.5/weather.

Key parameters include:

• q: City name, state code, and country code (e.g., London,uk).
• lat and lon: Geographical coordinates (latitude and longitude).
• appid: Your API key.
• units: Units of measurement (metric, imperial, or standard for Kelvin).

Example Request (cURL)

Replace YOUR_API_KEY with your actual API key.

curl "https://api.openweathermap.org/data/2.5/weather?q=London,uk&appid=YOUR_API_KEY&units=metric"

Example Response (JSON)

A successful response will return a JSON object containing various weather parameters:

{
  "coord": {
    "lon": -0.1257,
    "lat": 51.5085
  },
  "weather": [
    {
      "id": 800,
      "main": "Clear",
      "description": "clear sky",
      "icon": "01d"
    }
  ],
  "base": "stations",
  "main": {
    "temp": 15.02,
    "feels_like": 14.73,
    "temp_min": 13.88,
    "temp_max": 16.36,
    "pressure": 1018,
    "humidity": 72
  },
  "visibility": 10000,
  "wind": {
    "speed": 3.09,
    "deg": 240
  },
  "clouds": {
    "all": 0
  },
  "dt": 1678886400,
  "sys": {
    "type": 2,
    "id": 2075535,
    "country": "GB",
    "sunrise": 1678864000,
    "sunset": 1678905600
  },
  "timezone": 0,
  "id": 2643743,
  "name": "London",
  "cod": 200
}

Parsing the Response

The response contains nested JSON objects. For instance, the current temperature is accessible via main.temp. You would use standard JSON parsing libraries in your chosen programming language to extract this information.

Python Example

import requests

api_key = "YOUR_API_KEY"
city = "London,uk"
units = "metric"

url = f"https://api.openweathermap.org/data/2.5/weather?q={city}&appid={api_key}&units={units}"

response = requests.get(url)
data = response.json()

if data["cod"] == 200:
    current_temp = data["main"]["temp"]
    weather_description = data["weather"][0]["description"]
    print(f"Current temperature in {city}: {current_temp}°C")
    print(f"Weather description: {weather_description}")
else:
    print(f"Error: {data.get('message', 'Unknown error')}")

JavaScript (Node.js with node-fetch) Example

import fetch from 'node-fetch';

const apiKey = "YOUR_API_KEY";
const city = "London,uk";
const units = "metric";

const url = `https://api.openweathermap.org/data/2.5/weather?q=${city}&appid=${apiKey}&units=${units}`;

async function getWeatherData() {
  try {
    const response = await fetch(url);
    const data = await response.json();

    if (data.cod === 200) {
      const currentTemp = data.main.temp;
      const weatherDescription = data.weather[0].description;
      console.log(`Current temperature in ${city}: ${currentTemp}°C`);
      console.log(`Weather description: ${weatherDescription}`);
    } else {
      console.error(`Error: ${data.message || 'Unknown error'}`);
    }
  } catch (error) {
    console.error('Failed to fetch weather data:', error);
  }
}

getWeatherData();

These examples illustrate how to construct the request and parse the JSON response to extract relevant weather information. Error handling is included to manage unsuccessful API calls.

Common next steps

After successfully making your first call, consider these common next steps to further integrate the OpenWeatherMap API into your applications:

• Explore Other Endpoints: The OpenWeatherMap API documentation details various endpoints, including the 5-day / 3-hour forecast, the One Call API (combining current, minute, hourly, and daily forecast data), and historical weather data.
• Implement Geocoding: Instead of hardcoding city names, use a geocoding service (like Google Maps Geocoding API) to convert addresses or place names into latitude and longitude coordinates for more precise weather data retrieval.
• Handle Rate Limits: Be aware of the rate limits associated with your OpenWeatherMap plan. Implement retry mechanisms with exponential backoff for transient errors (e.g., HTTP 429 Too Many Requests) to manage these limits effectively.
• Error Handling: Implement robust error handling for different HTTP status codes and API-specific error messages. The cod field in the JSON response indicates success (200) or an error.
• Unit Conversion and Localization: Allow users to select their preferred units (Celsius, Fahrenheit, Kelvin) and potentially localize weather descriptions if your application targets a global audience.
• Integrate into a Frontend: Display the fetched weather data in a web or mobile application interface.
• Monitor Usage: Track your API call usage through your OpenWeatherMap dashboard to stay within your plan's limits.

Troubleshooting the first call

When making your initial OpenWeatherMap API call, you might encounter common issues. Here are some troubleshooting tips:

• 401 Unauthorized (Invalid API Key):
  • Check API Key: Ensure your API key is correctly copied and pasted into the appid parameter. Double-check for typos or extra spaces.
  • API Key Activation: Newly generated API keys can take some time (up to 10 minutes, sometimes longer) to become active. Wait a bit and try again (OpenWeatherMap API Key Status FAQ).
  • Account Status: Verify that your OpenWeatherMap account is active and not suspended.
• 404 Not Found (City Not Found):
  • City Name Accuracy: Ensure the city name, state code, and country code (e.g., q=London,uk) are spelled correctly and valid. Try using latitude and longitude coordinates for more reliability.
  • Parameter Order: Confirm that parameters like q, lat, lon, and appid are correctly formatted in the URL query string.
• 429 Too Many Requests (Rate Limit Exceeded):
  • Check Plan Limits: Review the OpenWeatherMap pricing page to understand the call limits for your current plan (especially the free plan).
  • Reduce Frequency: If you are making many requests in a short period, pause and try again after a few minutes.
  • Upgrade Plan: If your application requires higher call volumes, consider upgrading to a paid subscription.
• Network Issues:
  • Internet Connection: Verify your internet connection is stable.
  • Firewall/Proxy: If you are in a corporate network, ensure firewalls or proxies are not blocking outbound HTTPS requests to api.openweathermap.org.
• Incorrect JSON Parsing:
  • Inspect Raw Response: If your code is failing to parse the JSON, print the raw response body to confirm it's valid JSON and matches the expected structure. Online JSON validators can help.
  • Key Paths: Double-check the exact key paths (e.g., data['main']['temp']) against the OpenWeatherMap API response structure documentation.

Consult the OpenWeatherMap FAQ and official API documentation for more detailed error codes and troubleshooting guidance.