> ## Documentation Index
> Fetch the complete documentation index at: https://arnaud.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](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

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

<Steps titleSize="h2">
  <Step title="Get an API key">
    OpenWeather generates an API key when you create an account.

    1. [Sign in to your account](https://openweathermap.org/home/sign_in).
    2. In the top menu, click your name > **My API keys**.

    Your API key is listed under the **Key** column.

    <Info>Make sure the status of your API key is **Active**. If the status is **Inactive**, click the toggle icon to
    activate your API key.</Info>
  </Step>

  <Step title="Make your first call">
    Store your API key in an environment variable so you don't paste secrets into shell history or source files.

    <CodeGroup>
      ```bash theme={null}
      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"
      ```
    </CodeGroup>

    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
  </Step>

  <Step title="Inspect the JSON response">
    If the request succeeds, the API returns a `200` status and a JSON object like this:

    ```json theme={null}
    {
      "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](/essentials/weather-conditions).
    * `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.
  </Step>

  <Step title="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.                                |
  </Step>

  <Step title="Next steps">
    You can now:

    * Review the full [API reference](/api-reference/current-weather-data)
    * Try `units=imperial` or remove `units` to compare default Kelvin values
    * Request `mode=xml` or `mode=html` if your integration needs another response format
  </Step>
</Steps>