Tech Writing Sample #2

How to Use the OpenWeather API (for beginners)

By Taylor Banks
A step-by-step guide to getting your OpenWeather API key and testing your first request using Postman without writing a single line of code.

Overview

What is an API?

An Application Programming Interface (API) is a tool that allows two pieces of software to communicate with each other. The client system makes a request to the API, and the API responds by retrieving the requested data and returning it to client.

What is OpenWeather?

OpenWeather is a free public API that provides weather data from all over the world. It is useful for any software that requires reliable realtime weather data, including:

• weather apps
• smart thermostats, sprinklers, or lighting systems
• event planning
• transporation & logistics

Why We’re Using Postman

Postman provides a visual interface that will allow us to test OpenWeather directly without writing any code.

Walkthrough: Testing Openweather API with Postman

Step 1: Sign Up for OpenWeather and Get Your API Key

1. Create an OpenWeather Account
2. At the top of the screen, click API
3. Scroll untill you see “Current Weather Data” and click Subscribe
   • Note: OpenWeather has many different APIs, but for the purposes of this tutorial, we are only interested in “Current Weather Data.”
4. Scroll until you see “Free Access”, then click Get API
   • Note: OpenWeather offers tiered subscriptions, but for the purposes of this tutorial, we are only interested in Free Access.
5. At the top of the screen, click API Keys

OpenWeather will have generated a default API key. Please wait one to two hours for the key to become active, then proceed to step two.

Step 2: Download and Install Postman

If you don’t already have Postman, download it here. It’s free and available for all major platforms.

Step 3: Make your first request

1. On OpenWeather, click API, then scroll until you see “Current Weather Data”
2. Click API Doc
3. Copy the generic API Call
4. Open Postman and click Send an API Request
5. Set “Method” to GET and paste in the generic API Call
6. Edit the API Call using your unique API key and and any geographical coordiantes.
   • Note: For this tutorial, I’ve chosen the coordinates (39.24, -77.26)
7. Click Send

Verifying A Successful Request

A successful request should produce a response in JSON at the bottom of the page. You will also see “200 OK” highlighted in green in the top right corner of the reponse. If you hover over it, it will say, “Request Successful. The server has responded as required.”

Breaking Down the Response

The API will give you a JSON object filled with structured weather data. Here are the most useful parts:

Coordinates:

These are the coordinates you provided.

{
   "coord": {
      "lon": 39.24,
      "lat": -77.26
   }
}

Weather

This lists a main weather condition (Rain, Clear, Clouds, etc) followed by a more detailed condition in plain English.

"weather": [
        {
            "id": 800,
            "main": "Clear",
            "description": "clear sky",
            "icon": "01d"
        }
    ]

Main

This section holds temperature-related data, such as the minimum and maximum temperatures, humidity and what temperature it actually feels like outside.

 "main": {
        "temp": 305.77,
        "feels_like": 312.77,
        "temp_min": 304.8,
        "temp_max": 307.32,
        "pressure": 1021,
        "humidity": 65,
        "sea_level": 1021,
        "grnd_level": 1005
    }

Visibility & Wind

This tells you the wind direction in meteorological degrees, and the wind speed and gust in meters/second. It also rates the visibility on a scale from 0 to 10,000 meters.

"visibility": 10000,
    "wind": {
        "speed": 0.45,
        "deg": 0,
        "gust": 1.34
    }

Clouds

This tells you cloudiness as a percentage. If rain or snow are predicted, then it would instead display the expected precipitation in millimeters per hour.

"clouds": {
        "all": 7
    },

Sys

This section displays a two letter country code in ISO 3166 format, along with the UNIX timestamps for sunrise and sunset in UTC. You can safely ignore the “type” and “id” fields, which are internal and undocumented.

"sys": {
        "type": 2,
        "id": 2011816,
        "country": "US",
        "sunrise": 1750758218,
        "sunset": 1750811957
    }

Timezone, ID, Name & Cod

These fields give extra metadata: the city name, its timezone offset from UTC, the city’s unique ID in OpenWeather, and a status code confirming the request was successful.

"timezone": -14400,
    "id": 4351708,
    "name": "Clarksburg",
    "cod": 200

Ways to Alter the API Call

Note: A list of city IDs can be downloaded here. OpenWeather recommends that you call the API by city ID to get unambiguous results for your city.

Note: A list of supported languages can be found here.

Caution: If requesting by zipcode, the search assumes USA as a default unless country is specified.

Troubleshooting: Common Errors and How to Fix Them

If something isn’t working when you test the OpenWeather API in Postman, start here. These are the most common issues beginners run into.

1. Invalid API Key (401) ❌

{
  "cod": 401,
  "message": "Invalid API key"
}

Problem:

• The API didn’t recognize your key.

Solution:

• Copy your key directly from your OpenWeather dashboard.
• Wait a few minutes if the key is brand new.

2. City Not Found (404)❓

{
  "cod": "404",
  "message": "city not found"
}

Problem:

• The API didn’t recognize the city name.

Solution:

• Double-check spelling.
• Add a country code (Ex: q=paris, FR).
• Avoid special characters and extra white space.

3. Requests Stop Working (With or Without Error Message)📈

Problem:

• Free plans are limited to 60 calls per minute.

Solution:

• Wait a bit, or upgrade if you’re making a lot of requests.

4. Sunrise/Sunset Times Look Wrong 🕐

"sunrise": 1750758218,
"sunset": 1750811957

Problem:

• Sunrise and Sunset times are in UTC.

Solution

• Use the timezone value to calculate local time.
• Convert timestamps using the Unix Time Converter.

Wrapping Up

You just completed this journey—from zero to your first working API request.

You now understand:

🔑 How to get and use an OpenWeather API key

📬 How to send a request to OpenWeather API using Postman

🛠️ How to read the response and spot common errors

Next Steps

If you’re ready to go further, here’s what you can try next:

• Test different cities – Add country codes or try using coordinates instead of names.
• Add optional parameters – Use units=imperial or lang=es to customize the response.
• Use the API in code – Try making the same request in Python or JavaScript.
• Explore other endpoints – Check out forecast, air pollution, and geolocation APIs.
• Build a small project – Show the weather for your city in a web app or script.

This guide was created as part of a technical writing portfolio project. All screenshots were taken as of June 2025.