API Integration: Beginner's Blog Tutorial

Almost every app you use is glued together with APIs: the weather widget on your phone, the payment step in a webshop, the login-with-Google button. An API is simply a URL you can send a request to, and which answers with data instead of a web page. This tutorial shows you how to call one, read the answer, handle errors, and finish with a small weather tool you can actually use. Every request in this guide was run before it was written down.

What you need

• A terminal with curl (preinstalled on Windows 10+, macOS and Linux)
• Either Node.js or Python installed — both paths are covered, pick one
• No API key. We use the free Open-Meteo weather API, which needs no registration

Step 1: Your first API call

Paste this in your terminal:

curl "https://api.open-meteo.com/v1/forecast?latitude=52.37&longitude=4.89&current_weather=true"

You get back a block of JSON, something like:

{
  "latitude": 52.38,
  "longitude": 4.9,
  "current_weather": {
    "temperature": 17.3,
    "windspeed": 14.8,
    "weathercode": 3,
    "time": "2026-08-29T12:00"
  }
}

That is the whole trick. Three things to notice:

• The part after the ? is the query string: key=value pairs separated by &. Here it says: this location, and include the current weather.
• The answer is JSON: nested keys and values, readable by every programming language.
• The coordinates 52.37, 4.89 are Amsterdam. Swap in your own city and run it again.

Step 2: Read the response in code

JavaScript (Node.js 18 or newer) — create weather.js:

const url =
  "https://api.open-meteo.com/v1/forecast" +
  "?latitude=52.37&longitude=4.89&current_weather=true";

const response = await fetch(url);
const data = await response.json();

console.log(`Temperature: ${data.current_weather.temperature} °C`);
console.log(`Wind speed: ${data.current_weather.windspeed} km/h`);

Run it with node weather.js. The built-in fetch function sends the request; .json() parses the body.

Python — install the requests library once with pip install requests, then create weather.py:

import requests

url = "https://api.open-meteo.com/v1/forecast"
params = {
    "latitude": 52.37,
    "longitude": 4.89,
    "current_weather": True,
}

response = requests.get(url, params=params, timeout=10)
data = response.json()

weather = data["current_weather"]
print(f"Temperature: {weather['temperature']} °C")
print(f"Wind speed: {weather['windspeed']} km/h")

Note how params replaces hand-writing the query string. The library handles the encoding for you.

Step 3: Handle errors like a professional

APIs fail: networks drop, servers restart, you send a typo. Every response carries a status code that tells you what happened:

• 200 — OK, here is your data
• 400 — your request is malformed (check your parameters)
• 401 / 403 — you are not allowed (missing or wrong key)
• 404 — this endpoint or resource does not exist
• 429 — slow down, you are sending too many requests
• 500 and up — the server itself has a problem; retry later

Never assume 200. In JavaScript:

const response = await fetch(url);
if (!response.ok) {
  throw new Error(`API returned ${response.status}`);
}
const data = await response.json();

In Python:

response = requests.get(url, params=params, timeout=10)
response.raise_for_status()  # throws on 4xx/5xx
data = response.json()

Also set a timeout (as above). Without one, a hanging server hangs your program with it.

Step 4: Authentication — when an API wants a key

Open-Meteo is open, but most APIs want to know who is calling. The two patterns you will meet most often:

API key in a header (most common):

curl -H "Authorization: Bearer YOUR_API_KEY" https://api.example.com/v1/items

API key as a query parameter (older APIs):

curl "https://api.example.com/v1/items?api_key=YOUR_API_KEY"

Two rules that save careers:

• Never hardcode keys in your source code. Put them in an environment variable and read them with process.env.API_KEY (Node) or os.environ["API_KEY"] (Python).
• Never commit keys to Git. Add your .env file to .gitignore before your first commit, not after.

Step 5: The project — a city weather tool

Let's chain two APIs: Open-Meteo's geocoder turns a city name into coordinates, then the forecast API gives us the weather there. Create city-weather.js:

const city = process.argv[2];
if (!city) {
  console.log("Usage: node city-weather.js <city>");
  process.exit(1);
}

// Step 1: city name -> coordinates
const geoUrl =
  "https://geocoding-api.open-meteo.com/v1/search" +
  `?name=${encodeURIComponent(city)}&count=1`;
const geoResponse = await fetch(geoUrl);
if (!geoResponse.ok) throw new Error(`Geocoder returned ${geoResponse.status}`);
const geo = await geoResponse.json();

if (!geo.results || geo.results.length === 0) {
  console.log(`City not found: ${city}`);
  process.exit(1);
}
const { latitude, longitude, name, country } = geo.results[0];

// Step 2: coordinates -> current weather
const weatherUrl =
  "https://api.open-meteo.com/v1/forecast" +
  `?latitude=${latitude}&longitude=${longitude}&current_weather=true`;
const weatherResponse = await fetch(weatherUrl);
if (!weatherResponse.ok) throw new Error(`Forecast returned ${weatherResponse.status}`);
const weather = await weatherResponse.json();

const current = weather.current_weather;
console.log(`${name}, ${country}: ${current.temperature} °C, wind ${current.windspeed} km/h`);

Run it:

node city-weather.js Tokyo
Tokyo, Japan: 27.4 °C, wind 9.7 km/h

Notice encodeURIComponent: city names with spaces or accents must be encoded before they go into a URL. Forgetting this is one of the most common beginner API bugs.

Step 6: Respect rate limits

Free APIs allow a limited number of requests per minute or day. Three habits keep you inside them:

• Cache what does not change. Weather from two minutes ago is still weather; store the response and reuse it.
• Back off on 429. Wait a few seconds and retry once, instead of hammering.
• Read the docs page on limits before building. It is always shorter than debugging a ban.

What about webhooks?

An API call is you asking a service for data. A webhook is the reverse: the service calls a URL of yours when something happens (a payment succeeds, a form is submitted). You need a publicly reachable URL to receive them, which makes them a natural next step once you deploy something — our serverless tutorial gets you a public endpoint in minutes.

Where to go next

• Extend the weather tool: add a 3-day forecast (the daily parameter in the Open-Meteo docs).
• Pick any API you already pay for — your e-mail tool, your webshop — and read its API docs. You will now recognise every concept.
• Browse the Web Development chapter for the JavaScript and Python foundations behind this guide.

Did a request fail where the guide said it would work? Report the step and we will retest it.