Getting Started

OpenWeather’s current weather endpoint has three required parameters: appid, lat and lon. These correspond to your application’s API key and the latitude and longitude of the location you want to retrieve the weather forecast for.

To get an API key for appid you will need to create an account and generate an API key from OpenWeather. For lat and lon, you can drop a pin in any map app or use OpenWeather’s Geocoding API to look up a city or zip code.

In addition to the required parameters, you should also choose the units format —passed as the units parameter—which can be metric (°C, m/s), imperial (°F, mph), or standard (Kelvin, m/s), the default. Atmospheric pressure, precipitation, and visibility are always reported in hPa, mm, and m regardless of the units you choose.

Using the Current Weather Endpoint

Now that you have your query parameters, you can make a request. Just specify your application’s API key, GPS coordinates, and measurement units as query parameters.

Here is a complete example:

curl -s https://api.openweathermap.org/data/2.5/weather?appid=YOUR_API_KEY&lat=40.6501&lon=-73.9496&units=imperial | jq

This command returns a response like this:

{
    "coord": {
        "lon": -73.9496,
        "lat": 40.6501
    },
    "weather": [
        {
            "id": 801,
            "main": "Clouds",
            "description": "few clouds",
            "icon": "02n"
        }
    ],
    "base": "stations",
    "main": {
        "temp": 30.81,
        "feels_like": 23.36,
        "temp_min": 28.02,
        "temp_max": 32.13,
        "pressure": 1043,
        "humidity": 42,
        "sea_level": 1043,
        "grnd_level": 1042
    },
    "visibility": 10000,
    "wind": {
        "speed": 8.05,
        "deg": 340
    },
    "clouds": {
        "all": 20
    },
    "dt": 1734137918,
    "sys": {
        "type": 2,
        "id": 2037026,
        "country": "US",
        "sunrise": 1734091893,
        "sunset": 1734125346
    },
    "timezone": -18000,
    "id": 5110302,
    "name": "Brooklyn",
    "cod": 200
}

Here are the key fields and their meanings:

1. coord: Contains the geographical coordinates of the location. These may differ from the coordinates in the request.

   • lat: Latitude of the location.

   • lon: Longitude of the location.

2. weather: An array of weather condition objects that in most cases will contain just a single element. In cases where the array contains more than one element the first element in the array should be considered primary.

   • id: Weather condition ID.

   • main: Group of weather parameters (e.g., Rain, Snow, Extreme, etc.).

   • description: Weather condition within the group.

   • icon: Weather icon ID.

3. base: Internal parameter used by OpenWeather.

4. main: Contains main weather data.

   • temp: Current temperature.

   • feels_like: Human perception of weather temperature.

   • temp_min: Minimum temperature at the moment.

   • temp_max: Maximum temperature at the moment.

   • pressure: Atmospheric pressure in hectopascals.

   • humidity: Humidity percentage.

5. visibility: Visibility in meters.

6. wind: Contains wind information.

   • speed: Wind speed.

   • deg: Wind direction in degrees.

7. clouds: Cloudiness percentage.

   • all: Cloudiness percentage.

8. rain: Rain volume.

   • 1h: Rain volume for the last 1 hour (if available).

   • 3h: Rain volume for the last 3 hours (if available).

9. snow: Snow volume.

   • 1h: Snow volume for the last 1 hour (if available).

   • 3h: Snow volume for the last 3 hours (if available).

10. dt: Time of data calculation, Unix timestamp.

11. sys: Contains additional information.

    • type: Internal parameter.

    • id: Internal parameter.

    • country: Country code.

    • sunrise: Sunrise time, Unix timestamp.

    • sunset: Sunset time, Unix timestamp.

12. timezone: Shift in seconds from UTC.

13. id: City ID.

14. name: City name.

15. cod: Internal parameter indicating the status of the response.

Including weather, the Current Weather endpoint returns up to fifteen other top-level fields. Two of these—base and cod—are internal parameters, and two—rain and snow—are objects that may be omitted if no precipitation occurs.

The remaining top-level fields are coord, main, visibility, wind, clouds, dt, sys, timezone, id, and name. Of these, visibility, dt, timezone, id, and name are simple values, while the rest (coord, main, etc.) are objects with their own nested fields.

These fields provide a comprehensive overview of the current weather conditions at a specified location.

Displaying Weather Icons

Each weather condition object includes an ID (id), a title (main), a short description (description), and an icon ID (icon). To get the corresponding image, append the icon ID to https://openweathermap.org/img/wn/ and add @2x.png for retina resolution or .png for standard resolution.

OpenWeather provides a full list of weather codes.

Conclusion

We’ve seen how to pull the current weather forecast from OpenWeather, explored the response fields, and learned how to turn icon IDs into image URLs. With these pieces in place, we can start building apps that show real-time weather or visualize this data in dashboards. There’s even a 5-day forecast endpoint if you want to go further.

Photo credit: Shutterstock