How to Use the OpenWeatherMap API — A Practical Guide.

Overview

The OpenWeatherMap API provides current weather data for any location in the world, including temperature, humidity, wind speed, and general conditions (e.g., clear skies, clouds, rain). Data is returned in JSON format and can be requested by city name or geographic coordinates. This guide covers how to authenticate, make a request, and handle both successful responses and errors.

Authentication

This API requires a free API key to make requests. Without a valid key, all requests will return an error.

How to get your API key:
1.) Sign up for a free account at https://home.openweathermap.org/users/sign_up

2.)Verify your email address via the confirmation link sent to your inbox.

3.)Log in and navigate to the API keys tab in your account.

4.)Copy your default key (or generate a new one).

Note: New API keys can take up to 2 hours to activate. If you receive an "Invalid API key" error immediately after signing up, this is expected — simply wait and try again.

Using your key:
Your API key must be included in every request as a query parameter called appid. For example:

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

Base URL & Endpoint

All requests to the current weather data endpoint use this base URL:
https://api.openweathermap.org/data/2.5/weather

You send a GET request to this URL, along with the parameters below, to retrieve current weather data for a location.

Parameters

Parameter	Required?	Type	Description
q	Required	string	City name (e.g., Lagos, London). Can also include country code (e.g., Lagos,NG) for more precise results.
appid	Required	string	Your unique API key, used to authenticate the request.
units	Optional	string	Sets the unit format for temperature. Options: standard (Kelvin, default if omitted), metric (Celsius), imperial (Fahrenheit).

Example Requests & Responses
1.) Basic request (default units — Kelvin)
Request:
https://api.openweathermap.org/data/2.5/weather?q=Lagos&appid=YOUR_API_KEY

Response:

{
"coord": {"lon": 3.75, "lat": 6.5833},
"weather": [{"main": "Clouds", "description": "overcast clouds"}],
"main": {
"temp": 302.18,
"feels_like": 305.94,
"humidity": 70
},
"wind": {"speed": 4.15},
"sys": {"country": "NG"},
"name": "Lagos",
"cod": 200
}

Note: temperature is returned in Kelvin since no units parameter was set.

2.) Request with metric units
Request:
https://api.openweathermap.org/data/2.5/weather?q=Lagos&appid=YOUR_API_KEY&units=metric

Response (partial):

{
"main": {
"temp": 29.03,
"feels_like": 32.79,
"humidity": 70
},
"name": "Lagos"
}

Same location, now readable in Celsius.

3.) Request for a different city
Request:
https://api.openweathermap.org/data/2.5/weather?q=London&appid=YOUR_API_KEY&units=metric

Response (partial):

{
"weather": [{"main": "Clear", "description": "clear sky"}],
"main": {
"temp": 19.94,
"feels_like": 19.3,
"humidity": 50
},
"name": "London"
}

Demonstrates the same endpoint working for any valid city name.

4.) Error response — invalid city name
Request:
https://api.openweathermap.org/data/2.5/weather?q=asdkjasnd&appid=YOUR_API_KEY
Response:

{
"cod": "404",
"message": "city not found"
}

Error Handling

Error	Cause	Solution
401 Unauthorized — "Invalid API key"	Your API key is incorrect, or was very recently generated and hasn't activated yet.	Double-check your key for typos. If it was just generated, wait up to 2 hours and try again.
404 Not Found — "city not found"	The city name in the q parameter is misspelled or doesn't exist.	Check the spelling, or add a country code for precision (e.g., q=Lagos,NG).
429 Too Many Requests	You've exceeded your plan's rate limit (calls per minute/day).	Wait before making more requests, or check your usage on your OpenWeatherMap dashboard.

Quick Start

1.) Sign up for a free account at https://home.openweathermap.org/users/sign_up and verify your email.

2.) Copy your API key from the API keys tab (allow up to 2 hours for it to activate).

3.) Build a request using the base URL, your key, and a city name:
https://api.openweathermap.org/data/2.5/weather?q=YOUR_CITY&appid=YOUR_API_KEY&units=metric

4.) Paste the URL into your browser or an API tool (e.g., Postman).

5.) You'll receive a JSON response with current weather data for that city.

Conclusion

This documentation covers everything needed to start making requests to the OpenWeatherMap current weather API — from generating an API key to handling common errors. All examples in this guide were tested directly against the live API to ensure accuracy.
For more advanced use cases, such as extended forecasts or historical weather data, refer to OpenWeatherMap's official documentation at https://openweathermap.org/api