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

Getting started overview

Integrating OpenWeatherMap into a project involves a few core steps: account registration, API key retrieval, and making an initial API call. This guide focuses on these foundational actions to help developers quickly begin consuming weather data. OpenWeatherMap provides access to various weather data types, including current conditions, forecasts, and historical data, through a RESTful API interface OpenWeatherMap API documentation.

The API uses simple HTTP requests and typically returns data in JSON format, making it compatible with most programming languages and web development frameworks. Understanding the structure of these requests and responses is key to successful integration. The process generally requires an API key for authentication, which is linked to your user account and tracks usage against your plan limits.

Here's a quick reference table outlining the essential steps to get started:

Create an account and get keys

To begin using the OpenWeatherMap API, you must first register for an account. This account will provide access to your API keys, which are necessary for authenticating your requests. OpenWeatherMap offers a free tier that allows up to 1,000,000 calls per month for certain APIs, making it suitable for initial development and small projects.

1. Navigate to the registration page: Go to the OpenWeatherMap sign-up page.
2. Complete the registration form: Provide a username, email address, and password. You will also need to accept the terms and conditions.
3. Verify your email: After submitting the form, OpenWeatherMap will send a verification email to the address you provided. Click the link in this email to activate your account.
4. Log in: Once your email is verified, log in to your OpenWeatherMap account.
5. Access API keys: After logging in, navigate to the API keys section of your personal cabinet. A default API key is typically generated automatically upon account creation.

Your API key is a unique alphanumeric string that identifies your application when making API requests. It is crucial to keep this key secure and avoid exposing it in client-side code or public repositories. If your key is compromised, you can generate a new one from the API keys page.

Your first request

With an active account and API key, you can now make your first request to the OpenWeatherMap API. A common starting point is to fetch current weather data for a specific city. This example uses the Current Weather Data API. The base URL for most OpenWeatherMap API calls is api.openweathermap.org.

The Current Weather Data API endpoint requires a city name (or ID, or coordinates) and your API key. The general structure for a request by city name is:

https://api.openweathermap.org/data/2.5/weather?q={city name}&appid={API key}

Replace {city name} with the name of the city you want weather data for (e.g., London) and {API key} with your actual API key.

Example using cURL

cURL is a command-line tool and library for transferring data with URLs, commonly used for making HTTP requests. It's an effective way to test API endpoints directly from your terminal cURL man page.

Open your terminal or command prompt and execute the following command, replacing YOUR_API_KEY with your actual OpenWeatherMap API key:

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

A successful response will return a JSON object containing current weather conditions for London. The data includes temperature, humidity, wind speed, and weather description, among other details. For example, a partial response might look like this:

{
  "coord": {"lon": -0.13, "lat": 51.51},
  "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": 1650649733,
  "sys": {
    "type": 1,
    "id": 2688,
    "country": "GB",
    "sunrise": 1650682121,
    "sunset": 1650734208
  },
  "timezone": 3600,
  "id": 2643743,
  "name": "London",
  "cod": 200
}

Note that temperatures are often returned in Kelvin by default. You can specify units (units=metric for Celsius, units=imperial for Fahrenheit) in your request URL OpenWeatherMap current weather parameters.

Common next steps

After successfully making your first API call, you can explore other features and integrate the data more deeply into your applications:

• Explore other endpoints: OpenWeatherMap offers various APIs beyond current weather, such as 5-day/3-hour forecasts, One Call API (combining current, forecast, and historical data), and Geocoding API for converting city names to coordinates OpenWeatherMap API references.
• Implement error handling: Design your application to gracefully handle API errors, such as invalid API keys, rate limits, or network issues. The cod field in the JSON response often indicates the status code.
• Manage API key securely: Implement best practices for storing and using your API key. Avoid hardcoding it directly into your application's source code, especially for production environments. Consider environment variables or secure configuration management systems.
• Understand rate limits: Be aware of the call limits associated with your OpenWeatherMap plan. The free tier has generous limits, but exceeding them will result in 429 Too Many Requests errors. Implement caching strategies or adjust your polling frequency if necessary.
• Choose appropriate units: Specify units=metric or units=imperial in your API requests to receive temperature data in Celsius or Fahrenheit, respectively, rather than the default Kelvin.
• Integrate with a library: While OpenWeatherMap does not provide official SDKs, many community-maintained libraries exist for popular programming languages. These libraries can simplify API interaction and JSON parsing.

Troubleshooting the first call

If your first API call does not return the expected data, consider the following common issues:

• Invalid API Key (HTTP 401 Unauthorized): This is the most frequent issue. Double-check that your API key is correct and has been activated. It can take a few minutes for a newly generated API key to become active OpenWeatherMap API key FAQ. Ensure there are no typos or extra spaces.
• Incorrect Endpoint or Parameters (HTTP 400 Bad Request): Verify that the API endpoint URL is correct and that all required parameters (like q for city name and appid for your key) are included and correctly formatted. Consult the OpenWeatherMap API reference for the specific endpoint you are using.
• City Not Found (HTTP 404 Not Found or cod:404): If you receive a 404 status or a response indicating the city cannot be found, check the spelling of the city name. For ambiguous names, consider adding the country code (e.g., q=London,uk).
• Rate Limit Exceeded (HTTP 429 Too Many Requests): If you make too many requests within a short period, you might hit your plan's rate limit. Wait a few minutes and try again. For continuous integration, implement delays or caching.
• Network Issues: Ensure your internet connection is stable and that no firewalls or proxies are blocking the request to api.openweathermap.org.
• JSON Parsing Errors: If the API returns data but your application fails to process it, ensure your JSON parser is correctly handling the response structure. Using a tool like JSON.org's examples can help verify expected formats.

Always inspect the HTTP status code and the response body for detailed error messages, as these often provide specific clues about what went wrong.