Make your first API call

Request current weather by coordinates and inspect the JSON response.

In this guide, you’ll make your first successful request to the Current Weather API and learn how to handle the response and common errors.

Before you start, you need:

• An active OpenWeather account. If you don’t have an OpenWeather account, create one at https://home.openweathermap.org/users/sign_up.
• An active API key
• A terminal with curl
• Latitude and longitude for the location you want to query

OpenWeather recommends using coordinates for weather requests. Convert city names, ZIP codes, or addresses with the Geocoding API before calling this endpoint.

1. Get an API key

   OpenWeather generates an API key when you create an account.

   1. Sign in to your account.
   2. In the top menu, click your name > My API keys.

   Your API key is listed under the Key column.

   Make sure the status of your API key is Active. If the status is Inactive, click the toggle icon to activate your API key.
2. Make your first call

   Store your API key in an environment variable so you don’t paste secrets into shell history or source files.

   export OPENWEATHER_API_KEY="YOUR_API_KEY"
   curl --request GET \
     --url "https://api.openweathermap.org/data/2.5/weather?lat=48.8534&lon=2.3488&units=metric&appid=$OPENWEATHER_API_KEY"
   

   This request uses:

   • lat and lon to identify Paris by coordinates
   • units=metric so temperatures are returned in Celsius
   • appid to authenticate the request with your API key
3. Inspect the JSON response

   If the request succeeds, the API returns a 200 status and a JSON object like this:

   {
     "coord": {
       "lon": 2.3488,
       "lat": 48.8534
     },
     "weather": [
       {
         "id": 803,
         "main": "Clouds",
         "description": "broken clouds",
         "icon": "04d"
       }
     ],
     "main": {
       "temp": 16.13,
       "feels_like": 15.55,
       "temp_min": 15.06,
       "temp_max": 18.54,
       "pressure": 1022,
       "humidity": 67
     },
     "visibility": 10000,
     "wind": {
       "speed": 2.57,
       "deg": 40
     },
     "clouds": {
       "all": 75
     },
     "dt": 1717406455,
     "sys": {
       "country": "FR",
       "sunrise": 1717386622,
       "sunset": 1717444055
     },
     "timezone": 7200,
     "name": "Paris",
     "cod": 200
   }
   

   Key fields to handle in your application:

   • main.temp and main.feels_like use the unit system requested with units. In this tutorial, they are Celsius because the request uses units=metric.
   • weather[0].id is the stable weather condition code. Use it for application logic, and use weather[0].description for display text.
   • weather[0].icon maps to OpenWeather’s icon assets. For more info, see Weather conditions and icons.
   • rain, snow, and wind.gust are optional. Check whether they exist before reading nested values.
   • dt, sys.sunrise, and sys.sunset are Unix timestamps in UTC.
   • timezone is the location’s shift from UTC in seconds. Use it when rendering local times.
4. Troubleshoot request errors

   If your request fails, check the response status and error message.

   Status	Likely cause	Fix
   400 Bad Request	A required query parameter is missing or invalid.	Confirm that lat is between -90 and 90, lon is between -180 and 180, and both parameters are present.
   401 Unauthorized	The API key is missing, inactive, or invalid.	Confirm that appid uses an active key from My API keys.
   429 Too Many Requests	The API key exceeded its rate limit.	Wait at least one minute before retrying, or reduce request frequency in your app.

5. Next steps

   You can now:

   • Review the full API reference
   • Try units=imperial or remove units to compare default Kelvin values
   • Request mode=xml or mode=html if your integration needs another response format