OpenWeatherMap Getting Started: API Key & First Call (2026)

Getting started overview

Integrating with OpenWeatherMap involves a sequence of steps designed to get you from account creation to a successful API call. This guide outlines the process, covering account registration, API key acquisition, and making your initial request to retrieve weather data. Understanding each step ensures proper authentication and data retrieval from the OpenWeatherMap API endpoints.

The general workflow for getting started with OpenWeatherMap is as follows:

1. Account Creation: Register for a user account on the OpenWeatherMap website.
2. API Key Retrieval: Locate the automatically generated API key within your account dashboard.
3. API Call Construction: Formulate a request to an OpenWeatherMap endpoint, including your API key.
4. Data Retrieval: Execute the request and process the returned JSON data.

This process is applicable across various OpenWeatherMap services, including the Current Weather Data API, One Call API, and Geocoding API, each requiring the API key for authentication. For a comprehensive list of available services and their specific parameters, refer to the OpenWeatherMap API references.

Quick Reference Table

The table below summarizes the key actions and resources needed to get started with OpenWeatherMap:

Create an account and get keys

To access any OpenWeatherMap API, you must first register for an account and obtain an API key. This key serves as your primary authentication credential for all API requests. OpenWeatherMap offers a free plan that includes 1,000,000 calls per month, suitable for initial development and personal projects.

Follow these steps to create your account and retrieve your API key:

1. Navigate to the Registration Page: Go to the OpenWeatherMap registration page.
2. Complete the Registration Form: Fill in the required details, including your username, email, and password. You may also need to agree to the terms of service.
3. Verify Your Email: After submitting the form, OpenWeatherMap typically sends a verification email. Click the link in this email to activate your account.
4. Log In: Once your account is activated, log in to the OpenWeatherMap website.
5. Access API Keys Section: In your account dashboard, navigate to the "API Keys" section. OpenWeatherMap automatically generates a default API key upon account creation.
6. Copy Your API Key: Your API key will be displayed. It's a string of alphanumeric characters (e.g., b6907d289e10d714a6e88b3076121111). Copy this key, as you will need to include it in every API request. You can also generate additional keys or rename existing ones from this section.

It can take a few minutes for a newly generated API key to become active on the OpenWeatherMap servers. If your first request returns an authentication error, wait approximately 10-15 minutes and try again. For security best practices, treat your API key like a password and avoid exposing it in client-side code or public repositories. Consider using environment variables or a secure backend service to manage API keys, as recommended by general API security guidelines like those provided by Google Cloud's API key security documentation.

Your first request

With your OpenWeatherMap API key in hand, you can now make your first request to retrieve weather data. A common starting point is the Current Weather Data API, which provides real-time weather information for a specified location. This example uses the city name "London" and demonstrates how to make a basic GET request.

The base URL for the Current Weather Data API is https://api.openweathermap.org/data/2.5/weather. You will need to append parameters for the city (q) and your API key (appid).

Example Request: Current Weather for London

Using cURL, a command-line tool for making HTTP requests, you can execute the following command. Replace YOUR_API_KEY with the actual key you obtained from your OpenWeatherMap account.

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

Alternatively, you can make this request directly in your web browser by navigating to the constructed URL:

https://api.openweathermap.org/data/2.5/weather?q=London&appid=YOUR_API_KEY

Expected Response

A successful request will return a JSON object containing current weather data for London. The structure of the response will include details such as:

• coord: Geographical coordinates of the location.
• weather: Array of weather conditions (e.g., "clear sky", "clouds").
• main: Main weather parameters like temperature, humidity, pressure.
• wind: Wind speed and direction.
• sys: Sunrise and sunset times.
• name: City name.

Here is an truncated example of a successful JSON response:

{
  "coord": {
    "lon": -0.1257,
    "lat": 51.5085
  },
  "weather": [
    {
      "id": 800,
      "main": "Clear",
      "description": "clear sky",
      "icon": "01d"
    }
  ],
  "base": "stations",
  "main": {
    "temp": 282.55,
    "feels_like": 281.86,
    "temp_min": 280.37,
    "temp_max": 284.26,
    "pressure": 1023,
    "humidity": 100
  },
  "visibility": 10000,
  "wind": {
    "speed": 1.5,
    "deg": 350
  },
  "clouds": {
    "all": 1
  },
  "dt": 1678253047,
  "sys": {
    "type": 1,
    "id": 7695,
    "country": "GB",
    "sunrise": 1678256400,
    "sunset": 1678297200
  },
  "timezone": 0,
  "id": 2643743,
  "name": "London",
  "cod": 200
}

The cod: 200 field indicates a successful HTTP request, aligning with standard HTTP status codes as defined by the IETF RFC 9110 for HTTP Semantics.

Common next steps

After successfully making your first request, several common next steps can enhance your use of OpenWeatherMap data:

1. Explore Other Endpoints: OpenWeatherMap offers various APIs beyond current weather, such as One Call API for comprehensive weather data (current, forecast, historical in one call), Geocoding API for converting city names to coordinates, and Historical Data API. Review the OpenWeatherMap API documentation to identify the best endpoints for your project requirements.
2. Integrate into an Application: Move beyond cURL by integrating the API calls into your preferred programming language. OpenWeatherMap supports various languages, and examples are often available for Python, JavaScript, and PHP within their documentation. This involves using HTTP client libraries to send requests and JSON parsers to handle responses.
3. Handle Different Units: The default temperature unit is Kelvin. You can specify other units (e.g., Celsius, Fahrenheit) by appending the units parameter to your request (e.g., &units=metric for Celsius or &units=imperial for Fahrenheit).
4. Error Handling: Implement robust error handling in your application. OpenWeatherMap returns specific HTTP status codes and JSON error messages for issues like invalid API keys, rate limits, or incorrect parameters. For example, a cod: 401 typically indicates an unauthorized request due to an invalid API key, and a cod: 429 indicates exceeding your rate limits.
5. Monitor API Usage: Keep track of your API call volume in your OpenWeatherMap account dashboard to ensure you stay within your plan's limits, especially if using the free tier.
6. Upgrade Your Plan (If Needed): If your project requires higher call volumes, more advanced features, or specific data parameters (such as minute-by-minute forecasts), consider upgrading to a paid plan. Paid plans start at $40/month for increased call volumes and features.

Troubleshooting the first call

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

• "Invalid API key" (HTTP 401):
  • Verify key accuracy: Double-check that the API key in your request exactly matches the key in your OpenWeatherMap account dashboard. Copy-pasting is recommended to avoid typos.
  • Key activation delay: New API keys can take 10-15 minutes to become active. Wait a short period and try again.
  • Expired or revoked key: Ensure your API key has not been revoked or expired (though this is less common for newly generated keys).
• "City not found" or incorrect data:
  • Check spelling: Ensure the city name (q parameter) is spelled correctly.
  • Specify country code: For common city names, adding a country code (e.g., q=London,GB instead of q=London) can improve accuracy. Refer to the OpenWeatherMap Geocoding API documentation for proper country code formatting.
  • Use geographical coordinates: If city names are ambiguous, consider using latitude and longitude (lat and lon parameters) instead of q.
• "Calls limit exceeded" (HTTP 429):
  • Check usage: Review your API usage statistics in your OpenWeatherMap account dashboard. The free tier has a limit of 1,000,000 calls per month.
  • Rate limiting: If you are making many requests in a short period, you might be hitting per-minute or per-hour rate limits. Introduce delays between your requests.
  • Upgrade plan: If sustained high usage is required, consider moving to a paid subscription.
• No response or connection error:
  • Internet connection: Ensure your device has an active internet connection.
  • Firewall/proxy: Check if a firewall or proxy is blocking outgoing HTTP requests to api.openweathermap.org.
  • Temporarily down: Although rare, OpenWeatherMap's servers could be experiencing temporary issues. Check the OpenWeatherMap API status page (if available, usually linked from their primary API documentation) or their social media for outage announcements.
• Incorrect JSON parsing:
  • Validate JSON: Use an online JSON validator to ensure the response is well-formed.
  • Check data types: Confirm that your parsing logic correctly handles the data types returned (e.g., numbers for temperatures, strings for descriptions).