📡 APIs and JSON: From Asking for the Time to Asking the World

1️⃣ What Is an API?

API stands for Application Programming Interface. Continuing the analogy from the previous chapter:

An NTP server is the world's time office. The ESP32 sends it a request, and the server returns a response.

An API is a standard way for devices and programs to communicate. You can think of it as:

One program asking another program a question.

💬 Examples

Question	Server	Response
What time is it?	NTP server	UTC time
What is today's weather?	Weather API such as OpenWeatherMap	Temperature, humidity and conditions
What is the exchange rate?	Financial API	US dollar / Hong Kong dollar rate

An ESP32 that knows how to:

1. connect to the internet,
2. send a request,
3. receive a response, and
4. parse the returned data

can query almost any public API in the world.

2️⃣ Requests and Responses: The Backbone of an API

🚀 Request

A request normally contains:

• a URL—the server address, such as https://api.open-meteo.com/...;
• a method, commonly GET; and
• optional parameters such as a city name, latitude or longitude.

GET https://api.open-meteo.com/v1/forecast?latitude=22.2&longitude=113.5&current_weather=true

📦 Response

After receiving the request, the server returns data as text. It commonly uses JSON (JavaScript Object Notation).

3️⃣ What Is JSON?

JSON is a structured data format designed to be readable by both humans and computers.

{
  "latitude": 22.2,
  "longitude": 113.5,
  "current_weather": {
    "temperature": 28.7,
    "windspeed": 15.2,
    "weathercode": 1,
    "time": "2025-10-29T14:30"
  }
}

Here, current_weather contains several key–value pairs. A program can read each field directly, for example:

doc["current_weather"]["temperature"]

4️⃣ How Does an ESP32 Use an API?

In addition to connecting to Wi-Fi and using NTP, an ESP32 can:

• use an HTTP client library such as HTTPClient.h;
• send a GET request; and
• parse the response with ArduinoJson.

HTTPClient http;
http.begin("https://api.open-meteo.com/v1/forecast?latitude=22.2&longitude=113.5&current_weather=true");
int httpCode = http.GET();
if (httpCode == 200) {
    String payload = http.getString();
    Serial.println(payload);
}
http.end();

5️⃣ Why Learn JSON?

NTP only returns time, but an API can return almost any kind of data.

Type	API	Available data
Weather	OpenWeather / Open-Meteo	Temperature, humidity and wind speed
Exchange rates	Exchange-rate API	Currency conversion rates
Date and time	WorldTime API	Time in different regions
Transport	Transport API	Bus and flight data

🧠 Extension Tasks for Independent Study

• Wi-Fi + API + JSON experiment: read an online weather report and control an LED's colour temperature according to the air temperature.
• NTP + API combined task: make an ESP32 retrieve and display the weather automatically at 08:00 each morning.

🎓 Summary

Concept	Function	Analogy
RTC	A hardware clock that keeps time offline	A wristwatch
NTP	A network time-synchronisation service	Asking the world's time office
API	A way for programs to communicate	Asking a question
JSON	A structured data format	A standard reply format

Translation notice: This English page was generated automatically by AI and has not yet been reviewed by a human. It will be checked and revised page by page when time permits.