How to start

General overview

This page is a comprehensive guide for you to access the capabilities of OpenWeather's APIs. From initial registration to making API calls, you'll find detailed instructions, relevant links, and examples to facilitate your integration process. Whether you're a novice or an expert, this page provides clarity on harnessing and utilizing weather data for any location on the globe.

How to start work with our API

Start work with our service is easy and includes several steps:

  1. Sign up and get an API key if you have not yet. Please find detailed instructions in the section "How to get access".
  2. Follow the product tech documentation page to find the product you are interested in and the pricing page to learn details about the prices, tariffs and limits.
  3. Make an API call according to the product tech documentation and remember to add an API key to each API call. You can find detailed instructions on API call request in the section "How to make an API call".

You can find more information on the FAQ page.

How to get access

In order to use our services, first of all, you need to get your personal API key. How to do it:

  1. Click on Sign up and fill out a short form and get an API key (APPID) on your account page.
  2. Verify your email address via a confirmation letter that will be sent to you.
  3. Check your Inbox again to find our welcome email that contains your API key and important information.

Congratulations! Now you have an OpenWeather account with a free subscription plan and can immediately start using our services.

You can find a list of products available for your tariff plan on the pricing page on our OpenWeather website. If needed you can always upgrade your subscription plan to access a broader list of products.

Please review our product tech documentation page to find products you are interested in and check technical information on for each product. Product page documentation is an essential guide with actual examples and comprehensive description of API calls, responses and parameters.

How to make API call

In this section you will learn how to make an API call and find API call examples and API responses. We recommend checking documentation page and API docs for particular products (just click on product you are interested in on the documentation page to find actual examples and comprehensive description of API calls, responses and parameters).

How to create API call

To create an API call you need to send an HTTP request on the server using the URL from the chosen product documentation page and add your API key. There are many instruments and HTTP client services which can be used for sending requests. In the instruction below we use Postman as an example.

Parameters in API call

API call is presented in product tech page documentation page and contains URL of API request and a list and description of the parameters that users must complete before making a call.

Parameters are divided into:

Required parameters - parameters which are mandatory to fill out. All mandatory parameters marked as “required” in the list of API call parameters, for example your API key is a required parameter and must be added to each API call.

Optional parameters - parameters which you can add into API requests on your discretion if some changes in the API response data or format are needed. In other cases optional parameters can be skipped. All optional parameters marked as “optional” in the list of API call parameters. Please read product tech documents to find out what parameter settings are available for this product and API call.

API call to Current weather data

In this section you can find examples of API calls with only mandatory and optional parameters and responses to "Current weather data" product.

API call to the Current weather data has the structure below:

API call

https://api.openweathermap.org/data/2.5/weather?lat={lat}&lon={lon}&appid={API key}

Parameters description is presented in table below:

Parameters
lat required Latitude. 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 required Longitude. 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 required Your unique API key (you can always find it on your account page under the "API key" tab)
mode optional Response format. Possible values are xml and html. If you don't use the mode parameter format is JSON by default. Learn more
units optional 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. Learn more
lang optional You can use this parameter to get the output in your language. Learn more

As you can see parameters lat, lon and appid are mandatory whereas mode, units and lang are optional.
So, to make a successful API call request you must fill out lat, lon and appid parameters. Below you will find examples of API calls and responses to Current weather data for London with only mandatory and optional fields. London coordinates: lat=51.508 lon=-0.126

Example of API call to Current weather data with only mandatory parameters for London

https://api.openweathermap.org/data/2.5/weather?lat=51.508&lon=-0.126&appid={API key}

Example of API call to Current weather data with only mandatory parameters for London Postman view

Example of API call to Current weather data with only mandatory parameters

Example of API response to Current weather data with only mandatory parameters for London

Example of API response 
                

{
   "coord":{
      "lon":-0.126,
      "lat":51.508
   },
   "weather":[
      {
         "id":500,
         "main":"Rain",
         "description":"light rain",
         "icon":"10d"
      }
   ],
   "base":"stations",
   "main":{
      "temp":292.11,
      "feels_like":292.33,
      "temp_min":290.64,
      "temp_max":293.25,
      "pressure":1014,
      "humidity":87
   },
   "visibility":10000,
   "wind":{
      "speed":5.14,
      "deg":120
   },
   "rain":{
      "1h":0.8
   },
   "clouds":{
      "all":75
   },
   "dt":1692348966,
   "sys":{
      "type":2,
      "id":2075535,
      "country":"GB",
      "sunrise":1692334215,
      "sunset":1692386339
   },
   "timezone":3600,
   "id":2643743,
   "name":"London",
   "cod":200
}

If you want to add any small turnings in the API response data and format you need to include relevant optional parameters and its value using ampersand (&).

Example of API call to Current weather data with optional parameter units for London

https://api.openweathermap.org/data/2.5/weather?lat=51.508&lon=-0.126&units=metric&appid={API key}

Example of API call to Current weather data with optional parameter units for London Postman view

Example of API call to Current weather data with optional parameter

Example of API response to Current weather data with optional parameter units for London

Example of API response 
                
  {
   "coord":{
      "lon":-0.126,
      "lat":51.508
   },
   "weather":[
      {
         "id":500,
         "main":"Rain",
         "description":"light rain",
         "icon":"10d"
      }
   ],
   "base":"stations",
   "main":{
      "temp":18.86,
      "feels_like":19.07,
      "temp_min":17.42,
      "temp_max":19.95,
      "pressure":1014,
      "humidity":87
   },
   "visibility":10000,
   "wind":{
      "speed":5.14,
      "deg":120
   },
   "rain":{
      "1h":0.31
   },
   "clouds":{
      "all":75
   },
   "dt":1692348736,
   "sys":{
      "type":2,
      "id":2075535,
      "country":"GB",
      "sunrise":1692334215,
      "sunset":1692386340
   },
   "timezone":3600,
   "id":2643743,
   "name":"London",
   "cod":200
}

API errors

In case of incorrected API call you will receive an API error response. You can find detailed information about some popular errors in the FAQ.

API care recommendations

Like any other things you are using, the API requires some attention. To let it serve you properly, we suggest that you carefully read these instructions and care recommendations. Please mind that all our tariff plans have caps on the quantity of calls made to API and it varies depending on the subscription type. In case you don’t obtain an API response due to hitting the limit of calls, we would ask you to repeat your request in 10 minutes. On this occasion, we also recommend keeping the API request unamended, since it would help our internal caching service to process your request timely.

Get support

To get assistance please contact us info@openweathermap.org

We use cookies to personalize content and to analyze our traffic. Please decide if you are willing to accept cookies from our website.
Advanced Settings