OpenWeather

https://openweathermap.org/
Admin
OpenWeather provides instant access to weather APIs through self-service subscriptions for...
Tokens:235,502
Snippets:1,872
Trust Score:10
Update:3 months ago
Show doc for...
Tokens:
Raw
### Get Solar Panels URL Example

Source: https://openweathermap.org/api/solar-panels-and-energy-prediction-2

An example of the URL used to fetch solar panel data for a given location. This includes a sample `location_id`.

```text
https://api.openweathermap.org/energy/2.0/location/F01E165B-22F3-4591-89D4-F238E92F6885?appid={API key}
```

--------------------------------

### Example API Call by City ID (No Date Specified)

Source: https://openweathermap.org/api/history?collection=historical

Example API call using a city ID. If start and end/cnt are not specified, default historical data may be returned. Ensure you have the correct city ID and API key.

```text
https://history.openweathermap.org/data/2.5/history/city?id=2885679&type=hour&appid={API key}
```

--------------------------------

### API Call with API Key

Source: https://openweathermap.org/faq

This example shows how to include your API key as a parameter in a GET request to OpenWeather's API.

```http
api.openweathermap.org/data/2.5/weather?id=524901&appid=YOUR_API_KEY
```

--------------------------------

### Delete Solar Panel URL Example

Source: https://openweathermap.org/api/solar-panels-and-energy-prediction-2

An example of the URL for deleting a solar panel, demonstrating the use of a specific `panel_id`.

```text
https://api.openweathermap.org/energy/2.0/panel/F01E165B-22F3-4591-89D4-F238E92F6885?appid={API key}
```

--------------------------------

### 7-Day Forecast by City Name (Metric Units)

Source: https://openweathermap.org/api/forecast16?collection=current_forecast

This example demonstrates how to call the API to get a 7-day weather forecast for a city, specifically requesting data in metric units. Remember to replace the placeholders.

```api
api.openweathermap.org/data/2.5/forecast/daily?q={city name}&cnt=7&appid={API key}&units=metric
```

--------------------------------

### Temperature Map Layer Example

Source: https://openweathermap.org/api/weathermaps

Example of how to request a temperature weather map layer. This layer displays temperature variations worldwide.

```text
layer : temp_new
area : worldwide
```

--------------------------------

### Solar Data API URL Example

Source: https://openweathermap.org/api/solar-panels-and-energy-prediction-2

A concrete example of a URL for requesting solar data, specifying location, date, and interval.

```text
https://api.openweathermap.org/energy/2.0/location/018aa7aa-3d5f-85a2-91ee-b1b53c3e98a4/interval_data?date=2021-05-01&interval=1h&appid={API key}
```

--------------------------------

### Basic Relief Map URL Example

Source: https://openweathermap.org/api/relief

An example of a basic URL to retrieve relief maps, including the required API key.

```text
http://maps.openweathermap.org/maps/2.0/relief/{z}/{x}/{y}?appid={API key}
```

--------------------------------

### Example API Call

Source: https://openweathermap.org/api/uvi

An example of a complete API call with latitude and longitude specified. Replace '{API key}' with your actual API key.

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

--------------------------------

### Example CSV Bulk Download Link

Source: https://openweathermap.org/api/bulk

This example shows how to construct a download link for a bulk file in CSV format. Note the change from '.json.gz' to '.csv.gz' in the file name.

```text
https://bulk.openweathermap.org/snapshot/weather_zip_us.csv.gz?appid={API key}
```

--------------------------------

### Hourly Forecast API Call Example by City ID

Source: https://openweathermap.org/api/hourly-forecast

An example of an API call to get hourly forecast data using a city ID.

```text
https://pro.openweathermap.org/data/2.5/forecast/hourly?id=524901&appid={API key}
```

--------------------------------

### Layer Tint URL Example

Source: https://openweathermap.org/api/relief

Shows how to apply a layer tint to Relief maps by setting the 'mix_w' parameter to 0.

```text
http://maps.openweathermap.org/maps/2.0/relief/{z}/{x}/{y}?mix_w=0&appid={API key}
```

--------------------------------

### Hourly Forecast API Call Example by ZIP Code

Source: https://openweathermap.org/api/hourly-forecast

An example of an API call to get hourly forecast data using a ZIP code and country code.

```text
https://pro.openweathermap.org/data/2.5/forecast/hourly?zip=94040,us&appid={API key}
```

--------------------------------

### Example API Call

Source: https://openweathermap.org/api/one-call-4

An example of how to construct the API request URL for a specific alert ID. Ensure you replace `{API key}` with your actual API key.

```text
https://api.openweathermap.org/data/4.0/onecall/alert/8B46C632-DCA7-44D7-8BDF-02445621BAFF?appid={API key}
```

--------------------------------

### Example Current Fire Weather Index API Call

Source: https://openweathermap.org/api/fire-index-api

An example of an API call to get current Fire Weather Index data for a specific latitude and longitude.

```text
https://api.openweathermap.org/data/2.5/fwi?lat=24&lon=-103&appid={API key}
```

--------------------------------

### Example Accumulated Precipitation API Call

Source: https://openweathermap.org/api/accumulated-parameters

An example of a complete API call to the Accumulated Precipitation endpoint, demonstrating the use of latitude, longitude, start and end dates, and an API key.

```http
http://history.openweathermap.org/data/2.5/history/accumulated_precipitation?lat=51.51&lon=-0.12&start=1586853378&end=1589445367&appid={API key}
```

--------------------------------

### URL Example

Source: https://openweathermap.org/api/fire-index-map

An example of a complete URL for fetching a Fire Weather Index map. Replace placeholders with your actual API key and desired date (Unix time).

```text
https://maps.openweathermap.org/maps/2.0/fwi/4/1/6?appid={API key}&date=1600780200
```

--------------------------------

### Example Accumulated Temperature API Call

Source: https://openweathermap.org/api/accumulated-parameters

An example of a complete API call for accumulated temperature, demonstrating the use of latitude, longitude, start and end dates, a threshold value, and an API key.

```text
http://history.openweathermap.org/data/2.5/history/accumulated_temperature?lat=51.51&lon=-0.13&start=1586853378&end=1589445367&threshold=284&appid={API key}
```

--------------------------------

### API Call Example (Forecast)

Source: https://openweathermap.org/appid

An example demonstrating the structure of an API call for forecast data, including the necessary parameters like location ID and API key.

```text
api.openweathermap.org/data/2.5/forecast?id=524901&appid={API key}
```

--------------------------------

### API Response Example (City Name)

Source: https://openweathermap.org/api/history?collection=historical

Example URL for fetching historical data by city name. Replace '{API key}' with your actual API key.

```text
https://history.openweathermap.org/data/2.5/history/city?q=Munchen,DE&appid={API key}
```

--------------------------------

### API Call Example with API Key

Source: https://openweathermap.org/appid

This example demonstrates how to make an API call to retrieve weather data, including the required API key.

```APIDOC
## GET api.openweathermap.org/data/2.5/forecast

### Description
This endpoint retrieves weather forecast data for a specified location using your unique API key.

### Method
GET

### Endpoint
`http://api.openweathermap.org/data/2.5/forecast?id=524901&appid={API key}`

### Parameters
#### Query Parameters
- **appid** (string) - Required - Your unique API key. This key is essential for authenticating your request and accessing the weather data. You can find your API key on your account page under the "API key" tab.

### Request Example
```text
http://api.openweathermap.org/data/2.5/forecast?id=524901&appid=YOUR_API_KEY
```

### Response
#### Success Response (200)
- The response will contain weather forecast data for the specified location. The exact structure of the response depends on the specific data points requested and the API version being used.

#### Response Example
```json
{
  "cod": "200",
  "message": 0,
  "cnt": 40,
  "list": [
    {
      "dt": 1661875200,
      "main": {
        "temp": 298.48,
        "feels_like": 298.74,
        "temp_min": 297.56,
        "temp_max": 300.05,
        "pressure": 1015,
        "sea_level": 1015,
        "grnd_level": 933,
        "humidity": 69,
        "temp_kf": 2.49
      },
      "weather": [
        {
          "id": 800,
          "main": "Clear",
          "description": "clear sky",
          "icon": "01d"
        }
      ],
      "clouds": {
        "all": 0
      },
      "wind": {
        "speed": 3.65,
        "deg": 349,
        "gust": 6.07
      },
      "visibility": 10000,
      "pop": 0.21,
      "sys": {
        "pod": "d"
      },
      "dt_txt": "2022-08-30 12:00:00"
    }
  ],
  "city": {
    "id": 524901,
    "name": "Moscow",
    "coord": {
      "lat": 55.7522,
      "lon": 37.6156
    },
    "country": "RU",
    "population": 1000000,
    "timezone": 10800,
    "sunrise": 1661834104,
    "sunset": 1661887904
  }
}
```
```

--------------------------------

### Example API Call with Parameters

Source: https://openweathermap.org/api/one-call-4

An example of a complete API call including latitude, longitude, units, language, and API key. Ensure you have the correct subscription for One Call 4.0.

```text
https://api.openweathermap.org/data/4.0/onecall/current?lat=52.2297&lon=21.0122&units=metric&lang=en&appid={API key}
```

--------------------------------

### Get Historical Air Pollution Data

Source: https://openweathermap.org/api/air-pollution

This endpoint retrieves historical air pollution data. You need to provide the latitude, longitude, start and end timestamps, and your API key.

```APIDOC
## GET /data/2.5/air_pollution/history

### Description
Retrieves historical air pollution data for a specified location and time range.

### Method
GET

### Endpoint
`http://api.openweathermap.org/data/2.5/air_pollution/history?lat={lat}&lon={lon}&start={start}&end={end}&appid={API key}`

### Parameters
#### Query Parameters
- **lat** (number) - Required - Latitude of the location.
- **lon** (number) - Required - Longitude of the location.
- **start** (integer) - Required - Start date in Unix time (UTC).
- **end** (integer) - Required - End date in Unix time (UTC).
- **appid** (string) - Required - Your unique API key.

### Response
#### Success Response (200)
- **coord** (array) - Coordinates [latitude, longitude].
- **list** (array) - Array of historical data points.
  - **dt** (integer) - Date and time, Unix, UTC.
  - **main** (object)
    - **aqi** (integer) - Air Quality Index (1-5).
  - **components** (object)
    - **co** (number) - Concentration of CO (μg/m3).
    - **no** (number) - Concentration of NO (μg/m3).
    - **no2** (number) - Concentration of NO2 (μg/m3).
    - **o3** (number) - Concentration of O3 (μg/m3).
    - **so2** (number) - Concentration of SO2 (μg/m3).
    - **pm2_5** (number) - Concentration of PM2.5 (μg/m3).
    - **pm10** (number) - Concentration of PM10 (μg/m3).
    - **nh3** (number) - Concentration of NH3 (μg/m3).

### Response Example
```json
{
  "coord": [
    50,
    50
  ],
  "list": [
    {
      "dt": 1605182400,
      "main": {
        "aqi": 1
      },
      "components": {
        "co": 201.94053649902344,
        "no": 0.01877197064459324,
        "no2": 0.7711350917816162,
        "o3": 68.66455078125,
        "so2": 0.6407499313354492,
        "pm2_5": 0.5,
        "pm10": 0.540438711643219,
        "nh3": 0.12369127571582794
      }
    }
  ]
}
```
```

--------------------------------

### API Call Example with JSONP Callback

Source: https://openweathermap.org/api/forecast16

This example demonstrates how to make an API call and receive the response as a JSONP callback function. This is useful for integrating with JavaScript applications.

```text
test(
{
 "coord":{
    "lon":-0.13,
    "lat":51.51
 },
 "weather":[
    {
       "id":300,
       "main":"Drizzle",
       "description":"light intensity drizzle",
       "icon":"09d"
    }
 ],
 "base":"stations",
 "main":{
    "temp":280.32,
    "pressure":1012,
    "humidity":81,
    "temp_min":279.15,
    "temp_max":281.15
 },
 "visibility":10000,
 "wind":{
    "speed":4.1,
    "deg":80,
    "gust":6.1
 },
 "clouds":{
    "all":90
 },
 "dt":1485789600,
 "sys":{
    "type":1,
    "id":5091,
    "message":0.0103,
    "country":"GB",
    "sunrise":1485762037,
    "sunset":1485794875
 },
 "id":2643743,
 "name":"London",
 "cod":200
}
)
```

--------------------------------

### Get Historical Weather Data by City Name (with end date)

Source: https://openweathermap.org/api/history?collection=historical

Retrieve hourly historical weather data for a specified city using its name and country code, along with a start and end date.

```APIDOC
## GET /data/2.5/history/city

### Description
Retrieves hourly historical weather data for a specified city.

### Method
GET

### Endpoint
https://history.openweathermap.org/data/2.5/history/city

### Parameters
#### Query Parameters
- **q** (string) - Required - City name, state code and country code divided by comma. Example: London,UK
- **type** (string) - Required - Type of the call, must be `hour`.
- **appid** (string) - Required - Your unique API key.
- **start** (integer) - Optional - Start date in Unix time (UTC). Example: 1369728000
- **end** (integer) - Optional - End date in Unix time (UTC). Example: 1369789200
```

--------------------------------

### API Call Example with JavaScript Callback

Source: https://openweathermap.org/api/forecast30

This example demonstrates how to make an API call and handle the JSON response using a JavaScript callback function for JSONP.

```javascript
test(
{
 "coord":{
    "lon":-0.13,
    "lat":51.51
 },
 "weather":[
    {
       "id":300,
       "main":"Drizzle",
       "description":"light intensity drizzle",
       "icon":"09d"
    }
 ],
 "base":"stations",
 "main":{
    "temp":280.32,
    "pressure":1012,
    "humidity":81,
    "temp_min":279.15,
    "temp_max":281.15
 },
 "visibility":10000,
 "wind":{
    "speed":4.1,
    "deg":80
 },
 "clouds":{
    "all":90
 },
 "dt":1485789600,
 "sys":{
    "type":1,
    "id":5091,
    "message":0.0103,
    "country":"GB",
    "sunrise":1485762037,
    "sunset":1485794875
 },
 "id":2643743,
 "name":"London",
 "cod":200
}
)
```

--------------------------------

### URL Example for Weather Maps

Source: https://openweathermap.org/api/weather-map-1h

This is an example URL demonstrating how to request a specific weather map layer (HRD0 - Relative humidity) for a given date and time. Replace '{API key}' with your actual API key.

```text
https://maps.openweathermap.org/maps/2.0/weather/1h/HRD0/4/1/6?date=1618898990&appid={API key}
```

--------------------------------

### Get Historical Weather Data by City Name (with count)

Source: https://openweathermap.org/api/history?collection=historical

Retrieve hourly historical weather data for a specified city using its name and country code, along with a start date and a count of hourly records.

```APIDOC
## GET /data/2.5/history/city

### Description
Retrieves hourly historical weather data for a specified city using a count of records.

### Method
GET

### Endpoint
https://history.openweathermap.org/data/2.5/history/city

### Parameters
#### Query Parameters
- **q** (string) - Required - City name, state code and country code divided by comma. Example: London,UK
- **type** (string) - Required - Type of the call, must be `hour`.
- **appid** (string) - Required - Your unique API key.
- **start** (integer) - Optional - Start date in Unix time (UTC). Example: 1369728000
- **cnt** (integer) - Optional - A number of timestamps in response (one per hour). Can be used instead of `end`.
```

--------------------------------

### Example Weather Maps 2.0 API Call

Source: https://openweathermap.org/api/weather-map-2

An example of a complete URL for fetching a specific weather map layer with custom parameters. Ensure you replace `{API key}` with your actual key.

```text
http://maps.openweathermap.org/maps/2.0/weather/TA2/{z}/{x}/{y}?date=1552861800&opacity=0.9&fill_bound=true&appid={API key}
```

--------------------------------

### Get Historical Data by City ID

Source: https://openweathermap.org/api/history?collection=historical

Retrieves historical weather data for a specified city using its unique ID. You can define the time range using start and end dates, or specify the number of data points to retrieve.

```APIDOC
## GET /data/2.5/history/city

### Description
Retrieves historical weather data for a specified city using its unique ID. This endpoint allows for flexible data retrieval by specifying time ranges or the number of data points.

### Method
GET

### Endpoint
https://history.openweathermap.org/data/2.5/history/city

### Parameters
#### Query Parameters
- **id** (string) - Required - City ID. The list of city IDs can be downloaded from the provided link.
- **type** (string) - Required - Type of the call, must be `hour`.
- **appid** (string) - Required - Your unique API key.
- **start** (integer) - Optional - Start date in Unix time (UTC). Example: `start=1369728000`.
- **end** (integer) - Optional - End date in Unix time (UTC). Example: `end=1369789200`.
- **cnt** (integer) - Optional - Amount of returned data (one per hour, can be used instead of `end`).
- **units** (string) - Optional - Units of measurement: `standard` (default, Kelvin, m/s), `metric` (Celsius, m/s), `imperial` (Fahrenheit, miles/hour).

### Request Example
```http
GET https://history.openweathermap.org/data/2.5/history/city?id=2885679&type=hour&appid={API key}
```

### Response
#### Success Response (200)
- The response contains historical weather data for the specified city and time range.

#### Response Example
```json
{
  "example": "response body"
}
```

**Note:** For Professional and Expert plans, the maximum historical data depth in one API response is one week. For longer periods, multiple queries are necessary.
```

--------------------------------

### Get City History by Date Range

Source: https://openweathermap.org/history

Retrieves hourly historical weather data for a specified city within a given date range. Requires city name, country code, start and end dates (Unix timestamps), and an API key.

```APIDOC
## GET /data/2.5/history/city

### Description
Retrieves hourly historical weather data for a specified city within a given date range. Requires city name, country code, start and end dates (Unix timestamps), and an API key.

### Method
GET

### Endpoint
https://history.openweathermap.org/data/2.5/history/city

### Parameters
#### Query Parameters
- **q** (string) - Required - City name, state code and country code divided by comma, please refer to ISO 3166 for the state codes or country codes. You can specify the parameter not only in English. In this case, the API response should be returned in the same language as the language of requested location name if the location is in our predefined list of more than 200,000 locations.
- **type** (string) - Required - type of the call, keep this parameter in the API call as `hour`
- **appid** (string) - Required - Your unique API key (you can always find it on your account page under the "API key" tab)
- **start** (integer) - Optional - Start date (unix time, UTC time zone), e.g. start=1369728000
- **end** (integer) - Optional - End date (unix time, UTC time zone), e.g. end=1369789200

### Request Example
```
https://history.openweathermap.org/data/2.5/history/city?q=London,UK&appid={API key}
```

### Response
#### Success Response (200)
- **data** (array) - Historical weather data points.
- **city_info** (object) - Information about the city.

#### Response Example
{
  "example": "{\"list\":[{\"dt\":1369728000,\"main\":{\"temp\":283.15,\"feels_like\":282.15,\"temp_min\":282.15,\"temp_max\":284.15,\"pressure\":1012,\"humidity\":80}},...],\"city\":{\"id\":2643743,\"name\":\"London\",\"coord\":{\"lat\":51.5073219,\"lon\":-0.1276474},\"country\":\"GB\",\"population\":0,\"timezone\":3600,\"sunrise\":1369715400,\"sunset\":1369774200}}" 
}
```

--------------------------------

### Example API Call for 1 Minute Timeline

Source: https://openweathermap.org/api/one-call-4

An example of a complete API call URL for the 1-minute timeline endpoint, demonstrating the inclusion of latitude, longitude, and API key.

```text
https://api.openweathermap.org/data/4.0/onecall/timeline/1min?lat=51.5&lon=-0.1&appid={API key}
```

--------------------------------

### JSON Response Example

Source: https://openweathermap.org/api/current

An example of the API response when data is requested in JSON format.

```APIDOC
## JSON Response Example

```json
{
   "coord":{
      "lon":-0.13,
      "lat":51.51
   },
   "weather":[
      {
         "id":300,
         "main":"Drizzle",
         "description":"light intensity drizzle",
         "icon":"09d"
      }
   ],
   "base":"stations",
   "main":{
      "temp":280.32,
      "pressure":1012,
      "humidity":81,
      "temp_min":279.15,
      "temp_max":281.15
   },
   "visibility":10000,
   "wind":{
      "speed":4.1,
      "deg":80
   },
   "clouds":{
      "all":90
   },
   "dt":1485789600,
   "sys":{
      "type":1,
      "id":5091,
      "message":0.0103,
      "country":"GB",
      "sunrise":1485762037,
      "sunset":1485794875
   },
   "id":2643743,
   "name":"London",
   "cod":200
  }
```
```

--------------------------------

### Start Session - AI Weather Assistant

Source: https://openweathermap.org/api/uvi

Initiates a session with the AI Weather Assistant to ask questions about weather and receive related advice. This method returns an HTTP 200 on successful creation.

```APIDOC
## POST /weather-assistant

### Description
Starts a session to interact with the AI Weather Assistant, enabling users to ask questions about weather conditions and receive advice.

### Method
POST

### Endpoint
/weather-assistant

### Headers
- **Content-Type**: application/json
- **X-Api-Key**: [your OpenWeather API key]

### Request Body
(No specific request body schema provided, but implies a prompt or query will be sent)

### Response
#### Success Response (200)
- (Response details not explicitly defined, but indicates successful session initiation)

### Request Example
(No explicit request example provided in the source text)

### Response Example
(No explicit response example provided in the source text)
```
Tokens:
Raw