OpenWeatherMap

Current Weather API

Reference Guide

Endpoint: GET /data/2.5/weather

Version: 2.5.0
Date: April 2026
Prepared by: Pratik Jadhav
Table of Contents
1. Overview ................................................................................................................................ 1
2. Getting Started ....................................................................................................................... 2
2.1 Obtain an API Key ............................................................................................................ 2
2.2 Make the First API Call ..................................................................................................... 2
2.3 Test Using Postman ......................................................................................................... 2
3. Authentication ........................................................................................................................ 4
4. Endpoint Reference ............................................................................................................... 5
4.1 Endpoint ........................................................................................................................... 5
4.2 Parameters ....................................................................................................................... 5
4.3 Request Format ................................................................................................................ 5
4.4 Response Format ............................................................................................................. 5
4.4.1 Response Fields ........................................................................................................ 6
4.5 Response Codes .............................................................................................................. 7
4.6 Error Response Format .................................................................................................... 8
5. Code Examples...................................................................................................................... 9
5.1 Python .............................................................................................................................. 9
5.2 JavaScript (Fetch API) .....................................................................................................10
6. Error Handling .......................................................................................................................12
7. Use Cases ............................................................................................................................13
7.1 Travel Application ............................................................................................................13
7.2 Agriculture Dashboard .....................................................................................................13
1. Overview
The OpenWeatherMap Current Weather API is a REST API that returns real-time weather data
for a specified location. The API accepts an HTTP GET request with a city name and returns a
JSON response containing current temperature, humidity, wind speed, atmospheric pressure,
and sky conditions.

This document describes version 2.5 of the API and covers a single endpoint:
GET [Link]

Target audience: Application developers integrating weather data into web or mobile
applications, and technical writers documenting REST APIs.

Base URL: [Link]

API version path: /data/2.5/

1
2. Getting Started
This section describes how to obtain an API key and make the first API call.

2.1 Obtain an API Key

1. Navigate to [Link] and create a free account.
2. After logging in, select API Keys from the account dashboard.
3. Copy the default API key, or select Generate to create a new one.
4. Wait up to two hours for the key to activate before making requests.

2.2 Make the First API Call

Construct the request URL using your API key and a city name. The following example retrieves
current weather data for Nashik, India:

[Link]
s=metric

Paste the URL into a web browser. A successful request returns a JSON response with a 200
OK status code.

2.3 Test Using Postman

Postman is a REST API client that allows you to construct requests, inspect responses, and
manage API keys securely using environment variables.

To test the request URL in Postman:

1. Open Postman and create a new Workspace named OpenWeatherMap Docs.

2. Create a new Collection named Current Weather API.
3. Select Environments and create a new environment named OWM Environment.
4. Add a variable named api_key and paste your API key into the Value field.
5. Create a new GET request with the following URL:

[Link]

6. In the Params tab, add the following query parameters:

2
Key Value
q Nashik,IN
appid {{api_key}}
units metric

7. Select Send. Verify that the response returns a 200 OK status code and a JSON body.

Figure 1. Postman showing a 200 OK response from the /data/2.5/weather endpoint.

3
3. Authentication
The Current Weather API uses API key authentication. You must include your API key as the
appid query parameter in every request.

Authentication method Location Parameter name

API key Query string appid

The following example shows a correctly authenticated request:

GET
[Link]
&units=metric

4
4. Endpoint Reference
4.1 Endpoint
GET [Link]

This endpoint retrieves current weather conditions for a specified city. The response includes
temperature, humidity, pressure, wind speed, cloud coverage, and geographic coordinates.

4.2 Parameters
All parameters are passed as query string parameters appended to the base URL.

Parameter Type Required Description

q String Yes City name. Append a country code to avoid ambiguity.
Example: Nashik,IN or London,GB.
appid String Yes Your unique API key.
units String No Unit system for temperature values. Accepted values: metric
(Celsius), imperial (Fahrenheit), standard (Kelvin).

4.3 Request Format

The endpoint accepts HTTP GET requests only.

Sample request:
GET
[Link]
&units=metric

4.4 Response Format

A successful request returns a 200 OK status code and a JSON response body. The following is
a sample response for Nashik, India:

{
"coord": {
"lon": 73.8,
"lat": 19.9833
},
"weather": [
{
"id": 804,
"main": "Clouds",
"description": "overcast clouds",
"icon": "04n"

5
 }
],
"base": "stations",
"main": {
"temp": 24.52,
"feels_like": 25.25,
"temp_min": 24.52,
"temp_max": 24.52,
"pressure": 1009,
"humidity": 85,
"sea_level": 1009,
"grnd_level": 936
},
"visibility": 10000,
"wind": {
"speed": 4.93,
"deg": 251,
"gust": 9.07
},
"clouds": {
"all": 99
},
"dt": 1782501254,
"sys": {
"country": "IN",
"sunrise": 1782520061,
"sunset": 1782568061
},
"timezone": 19800,
"id": 1261731,
"name": "Nashik",
"cod": 200
}

4.4.1 Response Fields

The following table describes each field in the response body.

Field Type Description

[Link] Number Longitude of the city.
[Link] Number Latitude of the city.
weather[0].id Integer Weather condition code assigned by OpenWeatherMap.
weather[0].main String Weather condition group. Example: Clouds, Rain, Clear.
weather[0].description String Detailed weather condition. Example: overcast clouds.
weather[0].icon String Weather icon code used to retrieve the corresponding icon
image.
base String Internal data source identifier. Not required for integration.
[Link] Number Current temperature. Unit depends on the units parameter.
main.feels_like Number Perceived temperature. Unit depends on the units parameter.
main.temp_min Number Minimum temperature at the time of calculation.

6
 Field Type Description
main.temp_max Number Maximum temperature at the time of calculation.
[Link] Integer Atmospheric pressure at sea level, in hPa.
[Link] Integer Humidity percentage.
main.sea_level Integer Atmospheric pressure at sea level, in hPa.
main.grnd_level Integer Atmospheric pressure at ground level, in hPa.
visibility Integer Visibility in metres. Maximum reported value: 10,000.
[Link] Number Wind speed. Unit depends on the units parameter.
[Link] Integer Wind direction in meteorological degrees. 0 = North, 90 =
East.
[Link] Number Maximum wind gust speed. Unit depends on the units
parameter.
[Link] Integer Cloud coverage percentage.
dt Integer Time of data calculation expressed as a Unix UTC timestamp.
[Link] String Country code for the city. Example: IN, GB, US.
[Link] Integer Sunrise time expressed as a Unix UTC timestamp.
[Link] Integer Sunset time expressed as a Unix UTC timestamp.
timezone Integer Shift in seconds from UTC. Example: 19800 = UTC+5:30
(IST).
id Integer OpenWeatherMap city identifier.
name String City name as matched by the API.
cod Integer Internal API response code. Mirrors the HTTP status code in
most cases.

4.5 Response Codes

The API returns standard HTTP status codes. The following table describes each possible
response code for this endpoint.

HTTP status code Meaning Cause

200 OK Success Request processed successfully. Weather data
returned.
401 Unauthorized Authentication failed The API key is invalid, missing, or not yet active.
Allow up to two hours after key creation.
404 Not Found City not found The value passed to the q parameter does not
match any known city. Verify spelling or append a
country code.

7
 HTTP status code Meaning Cause
429 Too Many Rate limit exceeded The free-tier request limit has been reached.
Requests Review usage on the OpenWeatherMap
dashboard.

4.6 Error Response Format

When the API returns a non-200 status code, the response body contains a message field
describing the error.

401 Unauthorized
Sample error response:
{
"cod": 401,
"message": "Invalid API key. Please see [Link]
for more info."
}

404 Not Found

Sample error response:
{
"cod": "404",
"message": "city not found"
}

8
5. Code Examples
The following examples demonstrate how to call the endpoint and parse the response in
commonly used programming languages. Replace your_api_key_here with your actual API key
before running the code.

5.1 Python
import requests

url = "[Link]
params = {
"q": "Nashik,IN",
"appid": "your_api_key_here",
"units": "metric"
}

response = [Link](url, params=params)

if response.status_code == 200:
data = [Link]()
print("City :", data["name"])
print("Temperature :", data["main"]["temp"], "°C")
print("Humidity :", data["main"]["humidity"], "%")
print("Condition :", data["weather"][0]["description"])
else:
print("Error:", response.status_code, [Link]()["message"])

Figure 2. Python script output showing a successful response from the /data/2.5/weather endpoint.

9
5.2 JavaScript (Fetch API)
const apiKey = "your_api_key_here";
const city = "Nashik,IN";
const url = `[Link]
+ `?q=${city}&appid=${apiKey}&units=metric`;

fetch(url)
.then(response => {
if (![Link]) {
throw new Error(`HTTP error: ${[Link]}`);
}
return [Link]();
})
.then(data => {
[Link]("City :", [Link]);
[Link]("Temperature:", [Link], "°C");
[Link]("Condition :", [Link][0].description);
})
.catch(error => [Link]("Request failed:", error));

Figure 3: JSFiddle JavaScript panel showing the code

10
Figure 4. JavaScript Fetch API output in the browser console showing temperature and weather condition for Nashik.

11
6. Error Handling
All error responses from the API include a cod field and a message field in the JSON body.
Applications must evaluate the HTTP status code and handle each error condition explicitly.

Error cod value Common cause Recommended action

401 Unauthorized 401 (integer) Invalid or missing API key Verify the appid parameter
value. Confirm the key is active
in your account dashboard.
404 Not Found "404" (string) Unrecognised city name Check spelling. Append the
country code. Example:
Nashik,IN.
429 Too Many 429 Free-tier rate limit Reduce call frequency. Upgrade
Requests exceeded to a paid plan if sustained
throughput is required.
500 Internal 500 Server-side error Retry the request after a short
Server delay. If the error persists,
consult the OpenWeatherMap
status page.

12
7. Use Cases
7.1 Travel Application
A travel application can call this endpoint before a user's scheduled departure to display current
conditions at the destination city. The application passes the destination name to the q
parameter and renders the [Link] and weather[0].description fields as the primary display
values.

Relevant response fields:

• [Link]: Current temperature at the destination
• weather[0].description: Human-readable condition string
• weather[0].icon: Icon code for visual rendering

7.2 Agriculture Dashboard

A farming operations dashboard can use this endpoint to assess whether field conditions are
suitable for equipment operation. The application evaluates humidity, wind speed, and visibility
thresholds and presents an advisory to the operator.

Relevant response fields:

• [Link]: Soil moisture proxy
• [Link] and [Link]: Equipment safety thresholds
• visibility: Operational visibility for machinery

13