OpenWeather API

Disclaimer This is a portfolio sample. Please keep in mind that:

• The sole purpose of this page is to showcase my understanding and practice of API documentation.

• This content is not made from scratch. It is based on the publicely available official OpenWeather API documentation.

• I focused on demonstrating a practical and user-friendly workflow on a best-effort basis.

• This is content is intentionally incomplete and MUST NOT be used for production projects.

• If you need a comprehensive documentation, please check the official OpenWeather API documentation.

Overview

OpenWeather - One Call 3.0 API provides the following information:

• Essential weather data

• Short-term and long-term forecasts

• Aggregated weather data easily

The OpenWeather One Call API 3.0 provides four endpoints for comprehensive weather data. as shown in the following table:

Endpoint	Scope	Features
/onecall	Current weather and forecasts:	Minute forecast for 1 hour Hourly forecast for 48 hours Daily forecast for 8 days
/timemachine	Weather data for any timestamp	45 years historical archive and 4 days ahead forecast.
/day_summary	Daily aggregation	Daily aggregation of weather data for 45 years archive and 1.5 years ahead forecast.
/overview	Weather overview	Weather overview with a human-readable weather summary for today and tomorrow's forecast, utilizing OpenWeather AI technologies.

Based on our proprietary model, all endpoints are updated every 10 minutes to ensure you always have access to the most accurate and up-to-date information available in JSON, XML, or HTML format..

If you are using Dark Sky API, check our easy-to-follow migration process.

Quick Start Guide

Let's start to use the OpenWeather API by following these steps:

1. Sign up to OpenWeather to create your account.

2. Copy your default API key (later appid).

After completing the sign up process, you'll get a free plan subscription by default.

Free plan subscriptions

Free plan subscriptions (version 2.5) are limited to:

• 60 calls per minute

• 5 day / 3 hour forecast data

Making Your First API Call

Once you get your API key, you can make your first API call. We'll use the default free plan version to call the OpenWeather API to get our weather forecast for the following location:

• lat=33.44 - Latitude

• lon=-94.04 - Longitude

The API call will look as follows:

https://api.openweathermap.org/data/2.5/weather?lat=33.44&lon=-94.04&appid=YOUR_API_KEY

or in CURL:

curl -X GET 
  "https://api.openweathermap.org/data/2.5/weather?lat=40.7128&lon=-74.0060&appid=YOUR_API_KEY"

Reading Your First API Response

The API call will return all the information of the current weather information for the provided location as a response in JSON format:

{
    "coord": {
        "lon": -94.04,
        "lat": 33.44
    },
    "weather": [
        {
            "id": 800,
            "main": "Clear",
            "description": "clear sky",
            "icon": "01n"
        }
    ],
    "base": "stations",
    "main": {
        "temp": 293.03,
        "feels_like": 293.27,
        "temp_min": 292.59,
        "temp_max": 294.19,
        "pressure": 1019,
        "humidity": 84,
        "sea_level": 1019,
        "grnd_level": 1008
    },
    "visibility": 10000,
    "wind": {
        "speed": 0.45,
        "deg": 0,
        "gust": 0.89
    },
    "clouds": {
        "all": 0
    },
    "dt": 1757575986,
    "sys": {
        "type": 2,
        "id": 62880,
        "country": "US",
        "sunrise": 1757591833,
        "sunset": 1757636909
    },
    "timezone": -18000,
    "id": 4133367,
    "name": "Texarkana",
    "cod": 200
}

Empty Responses and Required Parameters

An API response not showing any parameters indicate that the related weather phenomena just did not happen for the data of measurement provided.

An API request without required parameters, such as latitude and longitude, will typically result in an 400 error message (nothing to show as Geocode information).

Weather Condition IDs

Range	Group	Description
200-299	Thunderstorm	Various thunderstorm conditions
300-399	Drizzle	Light precipitation
500-599	Rain	Moderate to heavy rain
600-699	Snow	Various snow conditions
700-799	Atmosphere	Fog, haze, dust, etc.
800	Clear	Clear sky
801-804	Clouds	Partially to fully cloudy

Response information

Check the reference information section for a comprehensive description of the OpenWeather API production version One Call 3.0.

How to Exclude Parts of the Weather Forecast

You can exclude part of the weather forecast in you API call by using the exclude parameter as shown in the follwing example:`

https://api.openweathermap.org/data/2.5/weather?lat=33.44&lon=-94.04&exclude=hourly,daily&appid=YOUR_API_KEY

or in CURL:

curl -X GET 
  "https://api.openweathermap.org/data/2.5/weather?lat=33.44&lon=-94.04&exclude=hourly,daily&appid=YOUR_API_KEY"

Parameters Options

-exclude

Option	Description
current	Current weather data
minutely	Minute forecast for 1 hour
hourly	Hourly forecast for 48 hours
daily	Daily forecast for 8 days
alerts	Weather alerts

-units

Option	Temperature	Wind Speed	Pressure
standard	Kelvin	meter/sec	hPa
metric	Celsius	meter/sec	hPa
imperial	Fahrenheit	miles/hour	hPa

-lan

Language	Code
English	en
French	fr
Italian	it
Russian	ru
Chinese	zh
Spanish	es
German	de
Portuguese	pt
Japanese	ja
Arabic	ar

Getting New API Keys

Whenever you need a new API key, follow theses steps:

1. In your OpenWeather home page, navigate to the API keys tab.

2. Under Create key, provide a name of the API key.

3. Click Generate.

Authentication and Authorization

The OpenWeather API uses API keys authentication. Include your API key in every request as follows using query parameters (recommended):

https://api.openweathermap.org/data/2.5/weather?lat=33.44&lon=-94.04&appid=YOUR_API_KEY

You can also use header authentication as follows:

curl -X GET \
  "https://api.openweathermap.org/data/3.0/onecall?lat=40.7&lon=-74.0" \
  -H "X-API-Key: YOUR_API_KEY"

---

Reference Information (One Call 3.0)

Overview

OpenWeather - One Call 3.0 API provides the following information:

• Essential weather data

• Short-term and long-term forecasts

• Aggregated weather data easily

The OpenWeather One Call API 3.0 provides four endpoints for comprehensive weather data. as shown in the following table:

Endpoint	Scope	Features
/onecall	Current weather and forecasts:	Minute forecast for 1 hour Hourly forecast for 48 hours Daily forecast for 8 days
/timemachine	Weather data for any timestamp	45 years historical archive and 4 days ahead forecast.
/day_summary	Daily aggregation	Daily aggregation of weather data for 45 years archive and 1.5 years ahead forecast.
/overview	Weather overview	Weather overview with a human-readable weather summary for today and tomorrow's forecast, utilizing OpenWeather AI technologies.

Based on our proprietary model, all endpoints are updated every 10 minutes to ensure you always have access to the most accurate and up-to-date information available in JSON, XML, or HTML format..

About Dark Sky API

If you are using Dark Sky API, check our easy-to-follow migration process.

API Keys and API Call Limit

API keys generation depends on your subscription plan. We track the total usage across all of them. The One Call API 3.0 has a default limit of 2,000 calls per day. To change this limit, navigate to the "your account billing plans" tab and update the standard settings.

Rate Limiting by Plan

Plan	Daily Calls	Calls per Minute	Burst Limit
Free	2,000	60	100
Startup	100,000	600	1,000
Developer	1,000,000	3,000	10,000

Rate Limiting Details

• Time Window: Limits reset at midnight UTC

• Per-key Tracking: All API keys under your account share the quota

• Burst Protection: Short bursts allowed up to burst limit

• Geographic: No geographic restrictions on rate limits

Rate Limit Headers

Every response includes rate limiting information:

HTTP/1.1 200 OK
X-RateLimit-Limit: 2000
X-RateLimit-Remaining: 1847
X-RateLimit-Reset: 1640995200
X-RateLimit-Used: 153

Handling Rate Limits

// Example: JavaScript rate limit handling
async function makeRequest(url) {
  try {
    const response = await fetch(url);
    
    if (response.status === 429) {
      const resetTime = response.headers.get('X-RateLimit-Reset');
      const waitTime = (resetTime * 1000) - Date.now();
      console.log(`Rate limited. Retry after ${waitTime}ms`);
      return null;
    }
    
    return await response.json();
  } catch (error) {
    console.error('Request failed:', error);
  }
}

Endpoints and Methods

One Call 3.0 Please note that One Call 3.0 is included in the One Call by Call subscription ONLY. Learn more.

The root URL for the API is https://api.openweathermap.org/data/3.0/onecall. In the following sections you will learn more about the One Call API 3.0 methods and endpoints.

/onecall

Current and forecast data.

GET https://api.openweathermap.org/data/3.0/onecall

Parameters

Name	Required	Type	Description
lat	Yes	float	Geographical latitude.
lon	Yes	float	Geographical lLongitude.
appid	Yes	string	Unique string of alphanumerical characters used to access One Call API resources.
exclude	No	list	Comma-delimited list of parameters (without spaces) to exclude in the response. Learn more in the Parameters Options section.
units	No	string	Units of measurement. If the units parameter is left empty, the standard units measure will be applied by default. Learn more in the Parameters Options section.
lang	No	string	Language of the response. Learn more in the Parameters Options section.

Request Example https://api.openweathermap.org/data/3.0/onecall/overview?lon=-11.8092&lat=51.509865&appid=YOUR_API_KEY

Response Example

{

`   `"lat": 51.509865,

`   `"lon": -0.118092,

`   `"tz": "+01:00",

`   `"date": "2024-05-13",

`   `"units": "metric",

`   `"weather\_overview": "The current weather is overcast with a 

temperature of 16°C and a feels-like temperature of 16°C. 

The wind speed is 4 meter/sec with gusts up to 6 meter/sec 

coming from the west-southwest direction. 

The air pressure is at 1007 hPa with a humidity level of 79%. 

The dew point is at 12°C and the visibility is 10000 meters. 

The UV index is at 4, indicating moderate risk from the 

sun's UV rays. 

The sky is covered with overcast clouds, and there is no precipitation expected at the moment. Overall, it is a moderately cool and cloudy day with light to moderate winds from the west-southwest."

}

/timemachine

Weather data for timestamp.

GET https://api.openweathermap.org/data/3.0/onecall/timemachine

Parameters

Name	Required	Type	Description
lat	Yes	float	Latitude, decimal (-90; 90). If you need the geocoder to automatic convert city names and zip-codes to geo coordinates and the other way around, please use our Geocoding API.
lon	Yes	float	Longitude, decimal (-180; 180). If you need the geocoder to automatic convert city names and zip-codes to geo coordinates and the other way around, please use our Geocoding API.
appid	Yes	string	Your unique API key (you can always find it on your account page under the "API key" tab).
dt	Yes	integer	Timestamp (Unix time, UTC time zone), e.g. dt=1586468027. Data is available from January 1st, 1979 till 4 days ahead.
units	No	string	Units of measurement. standard, metric and imperial units are available. If you do not use the units parameter, standard units will be applied by default.
lang	No	string	You can use the lang parameter to get the output in your language.

Request Example

https://api.openweathermap.org/data/3.0/onecall?lat=33.44&lon=-94.04&appid={API key}

Response Example

{

`   `"lat":33.44,

`   `"lon":-94.04,

`   `"timezone":"America/Chicago",

`   `"timezone\_offset":-18000,

`   `"current":{

`      `"dt":1684929490,

`      `"sunrise":1684926645,

`      `"sunset":1684977332,

`      `"temp":292.55,

`      `"feels\_like":292.87,

`      `"pressure":1014,

`      `"humidity":89,

`      `"dew\_point":290.69,

`      `"uvi":0.16,

`      `"clouds":53,

`      `"visibility":10000,

`      `"wind\_speed":3.13,

`      `"wind\_deg":93,

`      `"wind\_gust":6.71,

`      `"weather":[

`         `{

`            `"id":803,

`            `"main":"Clouds",

`            `"description":"broken clouds",

`            `"icon":"04d"

`         `}

`      `]

`   `},

`   `"minutely":[

`      `{

`         `"dt":1684929540,

`         `"precipitation":0

`      `},

...

`   `],

`   `"hourly":[

`      `{

`         `"dt":1684926000,

`         `"temp":292.01,

`         `"feels\_like":292.33,

`         `"pressure":1014,

`         `"humidity":91,

`         `"dew\_point":290.51,

`         `"uvi":0,

`         `"clouds":54,

`         `"visibility":10000,

`         `"wind\_speed":2.58,

`         `"wind\_deg":86,

`         `"wind\_gust":5.88,

`         `"weather":[

`            `{

`               `"id":803,

`               `"main":"Clouds",

`               `"description":"broken clouds",

`               `"icon":"04n"

`            `}

`         `],

`         `"pop":0.15

`      `},

...

`   `],

`   `"daily":[

`      `{

`         `"dt":1684951200,

`         `"sunrise":1684926645,

`         `"sunset":1684977332,

`         `"moonrise":1684941060,

`         `"moonset":1684905480,

`         `"moon\_phase":0.16,

`         `"summary":"Expect a day of partly cloudy with rain",

`         `"temp":{

`            `"day":299.03,

`            `"min":290.69,

`            `"max":300.35,

`            `"night":291.45,

`            `"eve":297.51,

`            `"morn":292.55

`         `},

`         `"feels\_like":{

`            `"day":299.21,

`            `"night":291.37,

`            `"eve":297.86,

`            `"morn":292.87

`         `},

`         `"pressure":1016,

`         `"humidity":59,

`         `"dew\_point":290.48,

`         `"wind\_speed":3.98,

`         `"wind\_deg":76,

`         `"wind\_gust":8.92,

`         `"weather":[

`            `{

`               `"id":500,

`               `"main":"Rain",

`               `"description":"light rain",

`               `"icon":"10d"

`            `}

`         `],

`         `"clouds":92,

`         `"pop":0.47,

`         `"rain":0.15,

`         `"uvi":9.23

`      `},

...

`   `],

`    `"alerts": [

`    `{

`      `"sender\_name": "NWS Philadelphia - Mount Holly (New Jersey, Delaware, Southeastern Pennsylvania)",

`      `"event": "Small Craft Advisory",

`      `"start": 1684952747,

`      `"end": 1684988747,

`      `"description": "...SMALL CRAFT ADVISORY REMAINS IN EFFECT FROM 5 PM THIS\nAFTERNOON TO 3 AM EST FRIDAY...\n\* WHAT...North winds 15 to 20 kt with gusts up to 25 kt and seas\n3 to 5 ft expected.\n\* WHERE...Coastal waters from Little Egg Inlet to Great Egg\nInlet NJ out 20 nm, Coastal waters from Great Egg Inlet to\nCape May NJ out 20 nm and Coastal waters from Manasquan Inlet\nto Little Egg Inlet NJ out 20 nm.\n\* WHEN...From 5 PM this afternoon to 3 AM EST Friday.\n\* IMPACTS...Conditions will be hazardous to small craft.",

`      `"tags": [

`      `]

`    `},

...

`  `]  

/day_summary

Aggregated weather data for a particular date from 2nd January 1979 till long-term forecast for 1,5 years ahead.

GET https://api.openweathermap.org/data/3.0/onecall/day_summary

Parameters

Name	Required	Description	Description
lat	Yes	float	Latitude, decimal (-90; 90). If you need the geocoder to automatic convert city names and zip-codes to geo coordinates and the other way around, please use our Geocoding API.
lon	Yes	float	Longitude, decimal (-180; 180). If you need the geocoder to automatic convert city names and zip-codes to geo coordinates and the other way around, please use our Geocoding API.
appid	Yes	string	Your unique API key (you can always find it on your account page under the "API key" tab).
date	Yes	string	Date in the YYYY-MM-DD format for which data is requested. Date is available for 45 years archive (starting from 1979-01-02) up to the 1,5 years ahead forecast to the current date.
units	No	string	Units of measurement. standard, metric and imperial units are available. If you do not use the units parameter, standard units will be applied by default.
lang	No	string	You can use the lang parameter to get the output in your language.

Request Example

https://api.openweathermap.org/data/3.0/onecall/day_summary?lat=39.099724&lon=-94.578331&date=2020-03-04&appid={API key}

Response Example

{

`   `"lat":33,

`   `"lon":35,

`   `"tz":"+02:00",

`   `"date":"2020-03-04",

`   `"units":"standard",

`   `"cloud\_cover":{

`      `"afternoon":0

`   `},

`   `"humidity":{

`      `"afternoon":33

`   `},

`   `"precipitation":{

`      `"total":0

`   `},

`   `"temperature":{

`      `"min":286.48,

`      `"max":299.24,

`      `"afternoon":296.15,

`      `"night":289.56,

`      `"evening":295.93,

`      `"morning":287.59

`   `},

`   `"pressure":{

`      `"afternoon":1015

`   `},

`   `"wind":{

`      `"max":{

`         `"speed":8.7,

`         `"direction":120

`      `}

}  

/overview

Weather overview information with a human-readable weather summary for today and tomorrow’s forecast, utilizing OpenWeather AI technologies.

GET https://api.openweathermap.org/data/3.0/onecall/overview

Parameters

Name	Required	Type	Description
lat	Yes	float	Latitude, decimal (-90; 90). If you need the geocoder to automatic convert city names and zip-codes to geo coordinates and the other way around, please use our Geocoding API.
lon	Yes	float	Longitude, decimal (-180; 180). If you need the geocoder to automatic convert city names and zip-codes to geo coordinates and the other way around, please use our Geocoding API.
appid	Yes	string	Your unique API key (you can always find it on your account page under the "API key" tab)
date	No	string	The date the user wants to get a weather summary in the YYYY-MM-DD format. Data is available for today and tomorrow. If not specified, the current date will be used by default. Please note that the date is determined by the timezone relevant to the coordinates specified in the API request.
units	No	string	Units of measurement. standard, metric and imperial units are available. If you do not use the units parameter, standard units will be applied by default.
lang	No	string	You can use the lang parameter to get the output in your language.

Request Example

https://api.openweathermap.org/data/3.0/onecall/overview?lon=-11.8092&lat=51.509865&appid={API key}

Response Example

 {

`   `"lat": 51.509865,

`   `"lon": -0.118092,

`   `"tz": "+01:00",

`   `"date": "2024-05-13",

`   `"units": "metric",

`   `"weather\_overview": "The current weather is overcast with a 

temperature of 16°C and a feels-like temperature of 16°C. 

The wind speed is 4 meter/sec with gusts up to 6 meter/sec 

coming from the west-southwest direction. 

The air pressure is at 1007 hPa with a humidity level of 79%. 

The dew point is at 12°C and the visibility is 10000 meters. 

The UV index is at 4, indicating moderate risk from the 

sun's UV rays. 

The sky is covered with overcast clouds, and there is 

no precipitation expected at the moment. 

Overall, it is a moderately cool and cloudy day 

with light to moderate winds from the west-southwest."

}  

Supported Response Formats

The API supports multiple response formats specified via the mode parameter:

Format	Parameter	Content-Type	Use Case
JSON	mode=json (default)	application/json	Standard API integration
XML	mode=xml	application/xml	Legacy systems
HTML	mode=html	text/html	Direct browser display

Examples

JSON Response (Default)

curl "https://api.openweathermap.org/data/3.0/onecall?lat=40.7&lon=-74.0&appid=YOUR_API_KEY"

{
  "lat": 40.7,
  "lon": -74.0,
  "current": {
    "temp": 298.15,
    "humidity": 65
  }
}

XML Response

curl "https://api.openweathermap.org/data/3.0/onecall?lat=40.7&lon=-74.0&mode=xml&appid=YOUR_API_KEY"

<?xml version="1.0" encoding="UTF-8"?>
<weather>
  <lat>40.7</lat>
  <lon>-74.0</lon>
  <current>
    <temp>298.15</temp>
    <humidity>65</humidity>
  </current>
</weather>

HTML Response

curl "https://api.openweathermap.org/data/3.0/onecall?lat=40.7&lon=-74.0&mode=html&appid=YOUR_API_KEY"

Returns a formatted HTML page suitable for direct browser display.

Request/Response Header Details

Required Request Headers

Accept: application/json
User-Agent: YourApp/1.0

Optional Request Headers

Accept-Language: en-US,en;q=0.9
Cache-Control: no-cache
X-API-Key: YOUR_API_KEY  # Alternative to query parameter

Standard Response Headers

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Cache-Control: public, max-age=600
X-RateLimit-Limit: 2000
X-RateLimit-Remaining: 1999
X-RateLimit-Reset: 1640995200
ETag: "abc123def456"
Last-Modified: Wed, 21 Oct 2024 07:28:00 GMT

Caching Headers

• Cache-Control: Responses cached for 10 minutes (600 seconds)

• ETag: Use for conditional requests to save bandwidth

• Last-Modified: Alternative cache validation method

---

JSON Response Fields

Field Path	Data Type	Description	Notes
cod	Number	Internal parameter	HTTP status code
message	String	Internal parameter	Error message or status
cnt	Number	A number of timestamps returned in the API response	Count of forecast entries
list	Array	Array of forecast data objects	-
list.dt	Number	Time of data forecasted, unix, UTC	Unix timestamp
list.main	Object	Main weather parameters	-
list.main.temp	Number	Temperature	Default: Kelvin, Metric: Celsius, Imperial: Fahrenheit
list.main.feels_like	Number	Human perception temperature	Default: Kelvin, Metric: Celsius, Imperial: Fahrenheit
list.main.temp_min	Number	Minimum forecasted temperature	Default: Kelvin, Metric: Celsius, Imperial: Fahrenheit
list.main.temp_max	Number	Maximum forecasted temperature	Default: Kelvin, Metric: Celsius, Imperial: Fahrenheit
list.main.pressure	Number	Atmospheric pressure on sea level	hPa (hectopascals)
list.main.sea_level	Number	Atmospheric pressure on sea level	hPa (hectopascals)
list.main.grnd_level	Number	Atmospheric pressure on ground level	hPa (hectopascals)
list.main.humidity	Number	Humidity percentage	% (0-100)
list.main.temp_kf	Number	Internal parameter	-
list.weather	Array	Weather conditions array	-
list.weather.id	Number	Weather condition ID	Weather condition code
list.weather.main	String	Group of weather parameters	Rain, Snow, Clouds, etc.
list.weather.description	String	Weather condition within the group	Detailed description
list.weather.icon	String	Weather icon ID	Icon code (e.g., "01d")
list.clouds	Object	Cloud information	-
list.clouds.all	Number	Cloudiness percentage	% (0-100)
list.wind	Object	Wind information	-
list.wind.speed	Number	Wind speed	Default/Metric: m/s, Imperial: mph
list.wind.deg	Number	Wind direction	Degrees (0-360, meteorological)
list.wind.gust	Number	Wind gust speed	Default/Metric: m/s, Imperial: mph
list.visibility	Number	Average visibility	Meters (max: 10,000m)
list.pop	Number	Probability of precipitation	Decimal (0.0-1.0, where 1.0 = 100%)
list.rain	Object	Rain information (optional)	-
list.rain.3h	Number	Rain volume for last 3 hours	mm (millimeters)
list.snow	Object	Snow information (optional)	-
list.snow.3h	Number	Snow volume for last 3 hours	mm (millimeters)
list.sys	Object	System parameters	-
list.sys.pod	String	Part of the day	"n" (night) or "d" (day)
list.dt_txt	String	Time of data forecasted	ISO 8601 format, UTC
city	Object	City information	-
city.id	Number	City ID	Numeric identifier (deprecated)
city.name	String	City name	City name (deprecated)
city.coord	Object	City coordinates	-
city.coord.lat	Number	Geo location latitude	Decimal degrees (-90 to 90)
city.coord.lon	Number	Geo location longitude	Decimal degrees (-180 to 180)
city.country	String	Country code	ISO 3166 country code (e.g., "US", "GB")
city.population	Number	City population	Number of inhabitants
city.timezone	Number	Shift in seconds from UTC	Seconds offset from UTC
city.sunrise	Number	Sunrise time	Unix timestamp, UTC
city.sunset	Number	Sunset time	Unix timestamp, UTC

Complete Response Schema

/onecall Response Structure

{
  "lat": 40.7128,                    // Number: Latitude
  "lon": -74.0060,                   // Number: Longitude
  "timezone": "America/New_York",    // String: IANA timezone
  "timezone_offset": -18000,         // Number: UTC offset in seconds
  
  "current": {                       // Object: Current weather (optional)
    "dt": 1640995200,               // Number: Unix timestamp
    "sunrise": 1640951234,          // Number: Sunrise time (Unix)
    "sunset": 1640983456,           // Number: Sunset time (Unix)
    "temp": 298.15,                 // Number: Temperature
    "feels_like": 299.2,            // Number: Perceived temperature
    "pressure": 1013,               // Number: Atmospheric pressure (hPa)
    "humidity": 65,                 // Number: Humidity percentage
    "dew_point": 291.5,             // Number: Dew point temperature
    "uvi": 5.2,                     // Number: UV index
    "clouds": 20,                   // Number: Cloudiness percentage
    "visibility": 10000,            // Number: Visibility in meters
    "wind_speed": 3.5,              // Number: Wind speed
    "wind_deg": 220,                // Number: Wind direction (degrees)
    "wind_gust": 5.1,               // Number: Wind gust speed (optional)
    "weather": [                    // Array: Weather conditions
      {
        "id": 800,                  // Number: Weather condition ID
        "main": "Clear",            // String: Weather group
        "description": "clear sky", // String: Weather description
        "icon": "01d"               // String: Weather icon ID
      }
    ]
  },
  
  "minutely": [                      // Array: Minute forecast (optional)
    {
      "dt": 1640995260,             // Number: Unix timestamp
      "precipitation": 0.0          // Number: Precipitation volume (mm/h)
    }
  ],
  
  "hourly": [                        // Array: Hourly forecast (optional)
    {
      "dt": 1640995200,             // Number: Unix timestamp
      "temp": 298.15,               // Number: Temperature
      "feels_like": 299.2,          // Number: Perceived temperature
      "pressure": 1013,             // Number: Atmospheric pressure
      "humidity": 65,               // Number: Humidity percentage
      "dew_point": 291.5,           // Number: Dew point
      "uvi": 5.2,                   // Number: UV index
      "clouds": 20,                 // Number: Cloudiness percentage
      "visibility": 10000,          // Number: Visibility in meters
      "wind_speed": 3.5,            // Number: Wind speed
      "wind_deg": 220,              // Number: Wind direction
      "wind_gust": 5.1,             // Number: Wind gust (optional)
      "weather": [                  // Array: Weather conditions
        {
          "id": 800,
          "main": "Clear",
          "description": "clear sky",
          "icon": "01d"
        }
      ],
      "pop": 0.1                    // Number: Probability of precipitation
    }
  ],
  
  "daily": [                         // Array: Daily forecast (optional)
    {
      "dt": 1640995200,             // Number: Unix timestamp
      "sunrise": 1640951234,        // Number: Sunrise time
      "sunset": 1640983456,         // Number: Sunset time
      "moonrise": 1640967890,       // Number: Moonrise time
      "moonset": 1640945678,        // Number: Moonset time
      "moon_phase": 0.25,           // Number: Moon phase (0-1)
      "summary": "Partly cloudy",   // String: Weather summary
      "temp": {                     // Object: Temperature throughout day
        "day": 298.15,              // Number: Day temperature
        "min": 293.2,               // Number: Minimum temperature
        "max": 301.5,               // Number: Maximum temperature
        "night": 295.8,             // Number: Night temperature
        "eve": 299.1,               // Number: Evening temperature
        "morn": 294.3               // Number: Morning temperature
      },
      "feels_like": {               // Object: Perceived temperature
        "day": 299.2,
        "night": 296.5,
        "eve": 300.1,
        "morn": 295.1
      },
      "pressure": 1013,             // Number: Atmospheric pressure
      "humidity": 65,               // Number: Humidity percentage
      "dew_point": 291.5,           // Number: Dew point
      "wind_speed": 3.5,            // Number: Wind speed
      "wind_deg": 220,              // Number: Wind direction
      "wind_gust": 5.1,             // Number: Wind gust (optional)
      "weather": [                  // Array: Weather conditions
        {
          "id": 800,
          "main": "Clear",
          "description": "clear sky",
          "icon": "01d"
        }
      ],
      "clouds": 20,                 // Number: Cloudiness percentage
      "pop": 0.1,                   // Number: Probability of precipitation
      "rain": 0.0,                  // Number: Rain volume (mm) (optional)
      "snow": 0.0,                  // Number: Snow volume (mm) (optional)
      "uvi": 5.2                    // Number: UV index
    }
  ],
  
  "alerts": [                        // Array: Weather alerts (optional)
    {
      "sender_name": "NWS",         // String: Alert source
      "event": "Winter Storm",      // String: Alert event type
      "start": 1640995200,          // Number: Alert start time (Unix)
      "end": 1641081600,            // Number: Alert end time (Unix)
      "description": "Heavy snow expected...", // String: Alert description
      "tags": ["snow", "wind"]      // Array: Alert tags
    }
  ]
}

Errors and Error Handling Error

Opencall 3.0 handles 401, 400, 429, and 5xx error codes. Error response payload returned for all types of errors has the following structure:

{

`    `"cod":400,                          # Error code

`    `"message":"Invalid date format", # Error description

`    `"parameters": [                   # List of request parameters name related to the error

`        `"date"

`    `]

}  

Error Codes

Check the following table for more information about the status and error codes:

Error Code	Description
400	Nothing to show as Geocode information.
401	Unauthorized. You can get 401 error if API token did not provided in the request or in case API token provided in the request does not grant access to this API. You must add API token with granted access to the product to the request before returning it.
404	Not Found. You can get 404 error if data with requested parameters (lat, lon, date etc) does not exist in service database. You must not retry the same request.
429	Too Many Requests. You can get 429 error if the key quota of requests for the provided API to this API was exceeded. You may retry the request after some time or after extending your key quota.
5xx	Unexpected Error. You can get '5xx' error in case of other internal errors. Error Response code will be 5xx. Please contact us and enclose an example of your API request that receives this error in your email to let us analyse it and find a solution for you promptly. You may retry the request which led to this error.

Best Practices

The following table provides the best practices that allow you to get the most out of the OpenWeather API:

Scope	Best Practice
API Key Management	Securely store your API key. Do not hardcode it in your application's source code, especially if the code is publicly accessible. Use environment variables or secure app settings for API key management.
Efficient Use of API Calls	To avoid reaching your API call limit, cache responses whenever possible, especially if you're requesting data that doesn't change frequently. OpenWeather data updates every 10 minutes, so plan your requests accordingly.
Use the Correct Endpoint	OpenWeather offers various endpoints for different types of data (current weather, forecasts, historical data, etc.). Use the specific endpoint that matches your data needs to ensure efficient use of the API.
Use the Correct Endpoint	OpenWeather offers various endpoints for different types of data (current weather, forecasts, historical data, etc.). Use the specific endpoint that matches your data needs to ensure efficient use of the API.
Handle Errors Gracefully	Implement error handling in your application to manage API request failures or unexpected responses. This includes handling HTTP status codes and parsing error messages returned by the API.
Optimize Requests with Parameters	Use API request parameters effectively to get only the data you need. For example, you can exclude parts of the data you don't need with the exclude parameter in the One Call API 3.0.
Respect API Limits	Be aware of your subscription plan's API call limits and ensure your application does not exceed them. Implement logic to throttle requests if necessary.
Use Units and Language Parameters	Customize API responses for your audience by using the units parameter to specify temperature and wind speed units, and the lang parameter to localize weather descriptions.
Geocoding	Use the Geocoding API to convert between city names and geographical coordinates when necessary, as direct requests by city name may be deprecated for some endpoints.
Subscription Management	Keep track of your subscription status and the features available to you. Some features, like the One Call API 3.0, require a separate subscription.
Stay Updated	OpenWeather periodically updates its APIs and documentation. Stay informed about any changes that might affect your application by regularly checking the OpenWeather website or subscribing to their updates.

Glossary

A

• API Key: A unique and required identifier to authenticate requests to the OpenWeather API. It's provided when you create an account on OpenWeather.

• Accumulated Parameters: Data that represents the accumulation of weather elements, such as precipitation, over a specified period.

• Air Pollution API: Provides data on air quality, including concentrations of pollutants like CO, NO2, and PM2.5, for any specified location.

B

• Bulk Downloading: A feature that allows downloading large datasets of current weather or forecasts in JSON format, available for certain account types.

C

• Callback Function: Used in JavaScript to handle asynchronous operations, such as receiving data from the API.

• Climatic Forecast 30 Days: A long-term weather forecast that gives a general idea of the weather conditions for the coming month.

• Current Weather Data: Real-time weather information for any location on Earth, including temperature, humidity, pressure, and more.

D

• Daily Forecast 16 Days: A weather forecast service that provides daily weather data, including temperature and weather conditions, for up to 16 days ahead.

H

• Hourly Forecast 4 Days: A detailed forecast that provides weather data in 3-hour intervals for up to 4 days ahead.

• History API: Provides historical weather data for any location on Earth. Useful for analyzing past weather conditions.

F

• 5 Day / 3 Hour Forecast: A five-day weather forecast with details provided every three hours.

• Fire Weather Index API: Offers information related to the risk of wildfire, which can be critical for fire prevention efforts in vulnerable areas.

G

• Geocoding API: Converts between addresses (like city names) and geographic coordinates (latitude and longitude), and vice versa.

J

• JSON/XML Format: The formats in which API responses can be received. JSON is the default format, but XML is also available for most data types.

M

• Multilingual Support: The API can return data in multiple languages, making it accessible to a global audience.

S

• Statistical Weather Data API: Offers statistical data based on historical weather information, which can be used for research and analysis.

U

• Units of Measurement: The API supports standard (Kelvin, meters/sec), metric (Celsius, meters/sec), and imperial (Fahrenheit, miles/hour) units for temperature, wind speed, and other measurements.

W

• Weather Maps 2.0: A service that provides various weather maps, including forecast, historical, and current weather maps, which can be integrated into web and mobile applications.