Computing Foundations › APIs and the Web › Day 28
Day 28: Consuming a Public API from the Command Line
After this lesson you will be able to read an API's documentation and build a working client from scratch — form the request, send it with curl, parse the JSON reply, handle errors and rate limits, and present the result — the exact motion every AI API call needs.
Hands-on lab for this lesson
Lab files on GitHub: https://github.com/ai-roadmap-365/ai-roadmap-365.github.io/tree/main/labs/sections/computing-foundations/day-028-consuming-a-public-api-from-the
- Get the hands-on files. Clone the labs repository once (you can reuse this clone for every lesson). This works on macOS, Linux, and Windows (PowerShell or WSL):
git clone https://github.com/ai-roadmap-365/ai-roadmap-365.github.io.git cd ai-roadmap-365.github.io - Open this lesson's lab. Move into the directory for this specific day. Every lab lives at the same predictable path — section / subsection / week / day:
cd labs/sections/computing-foundations/day-028-consuming-a-public-api-from-the - Read the lab guide. Open `README.md` in that directory. It lists the exact commands, what each does, the expected output, and how to check your work — read it before running anything.
- Run it and check your work. Follow the README's "How to run" section: run the example first to see the finished result, then complete the numbered exercises in `starter/`, then run the tests. The tests pass (exit 0) only when your work is correct.
bash tests/run_tests.sh # or the test command named in the lab README
You can also open the lab as a local page (works offline, shows the file tree and expected output).
Learning objectives
By the end of this lesson you will be able to:
- Read API documentation and locate the four things every request needs: endpoint, parameters, authentication, and response shape
- Build and send a request from the command line with curl, quoting the URL and setting a timeout
- Parse a JSON response for the fields you want using jq and python3, reading nested fields by path
- Handle a failed request and a missing field gracefully so a client fails with a clear message instead of garbage
- Choose an appropriate free public API to practice on, and explain when a call needs an API key and when it does not
- Decide when a curl one-liner should graduate to a shell script and then to a real program with an HTTP client library
- Explain why calling an AI model is the same request-and-parse skill, with a JSON body and an auth header added
Prerequisites
- Days 22-27 (the APIs and the Web category): what an API is, REST, JSON, authentication, webhooks, rate limits and pagination
- A terminal with curl and python3 (both preinstalled on macOS and Linux); network access to reach a free public API
Why this matters
-
This is the week assembling itself. HTTP, REST, JSON, authentication, rate limits and error handling become one working thing today.
-
Reading documentation quickly is the transferable skill, and it is the one you will use on every API for the rest of your career.
-
A one-liner that works is worth more than a program that nearly does, and knowing when to stop being a one-liner is judgement worth naming.
-
Every model API is consumed this way first. You run the provider’s
curlexample before you write a line of code. -
Tomorrow starts version control, and this is the last day of the API week.
The idea in plain language
-
Building an API client is always the same six stages, whatever the service.
-
Read the docs, build the request, send it, parse the response, handle errors, present the result.
-
curlsends;jqparses. Two tools, both ubiquitous, both composable. -
Each stage can fail in its own way, which is why error handling is a stage rather than an afterthought.
-
You are not expected to memorise an API. You are expected to read its contract and hold it to that contract.
Historical background
-
The first web APIs were consumed by hand, with
curland a text editor, because no client libraries existed yet. -
That remains the fastest way to understand one, which is why documentation still opens with a
curlexample three decades on. -
jqarrived in 2012, and made JSON tractable at the command line for the first time — before it, people reached for Python for even trivial extraction. -
The shell pipeline from Day 10 turned out to fit APIs perfectly: fetch, transform, filter, present, each stage doing one job.
-
Client libraries came later and did not replace this. They are what you build with; the command line is what you debug with.
What it is — and what it is not
It is:
- A pipeline: request, response, extraction, presentation.
- The fastest way to learn an unfamiliar API.
- A genuine deliverable — plenty of production automation is exactly this.
It is not:
-
Not a replacement for a program. Once you need branching, state or tests, move to a language.
-
Not fragile by nature, but it becomes fragile without error handling. A pipeline that assumes success produces confident nonsense.
-
Not just for exploring. A
curlandjqscript undercronis a perfectly respectable production system for the right job. -
Not the same as scraping. You are consuming a published contract, not guessing at a layout.
Why it was created and what problems it solves
-
Immediate feedback. You see the real response in one command, before committing to any design.
-
No project setup. No virtual environment, no dependencies, no scaffolding between you and the answer.
-
A reproducible reference. The command that worked is the command you paste into a bug report or a colleague’s terminal.
-
Composition. Every tool from Day 10 applies, because the response is text.
-
Portability.
curlexists on every machine you will ever connect to, including ones where you cannot install anything.
How it works
The six-stage pipeline
-
Read the docs. Find the endpoint, the required and optional parameters, the authentication rule, and the shape of the response.
-
Build the request. Assemble the URL and its query string —
?to start,&betweenname=valuepairs. -
Send it. One command.
curlfetches and prints the raw response. -
Parse the JSON. Pull out the fields you want with
jqorpython3. -
Handle errors. Check the request actually succeeded and the field was present, so a blip or a typo produces a clear message rather than garbage.
-
Present the result. A clean, readable line.
- Each stage feeds the next, and each fails differently. That is why stage five is not optional: skip it and the first flaky moment turns a tidy client into a wall of confusing output.
Reading the docs is the core skill
Every API’s documentation answers the same four questions:
-
What is the base URL and the endpoint?
-
What parameters does it take, which are required, and what values are allowed?
-
What authentication does it need?
-
What does a successful response look like — which fields, nested how?
-
Good docs show an example request and response side by side.
-
Copy the example, confirm it works, then change one piece at a time. That discipline is what makes an unfamiliar API usable in minutes.
From curl to jq to a report
curl -s "https://api.open-meteo.com/v1/forecast?latitude=52.52&longitude=13.41¤t=temperature_2m,wind_speed_10m"
-sis silent — it hides the progress meter so only the JSON prints.
{
"current_units": { "temperature_2m": "°C", "wind_speed_10m": "km/h" },
"current": { "time": "2026-07-12T12:30", "temperature_2m": 29.5, "wind_speed_10m": 16.9 }
}
curl -s "https://api.open-meteo.com/v1/forecast?latitude=52.52&longitude=13.41¤t=temperature_2m,wind_speed_10m" \
| jq '.current.temperature_2m'
-
That prints
29.5. -
The path reads left to right: enter the
currentobject, take itstemperature_2mfield — exactly the nesting you saw in the response. -
Swap in
.current.wind_speed_10mand you have the wind. Two fields, two paths, and you have what you came for.
The two tools, and their alternatives
-
For sending,
curlis the universal default: everywhere, scriptable, verbose when you need it. -
httpieis friendlier for exploring — colour output and simpler syntax — at the cost of an extra install. -
When a one-liner strains, move to a language. Python’s
requestsor JavaScript’sfetchturn the request into a few readable lines you can wrap in logic. -
For parsing,
jqhandles JSON beautifully at the command line. -
python3 -m json.toolis built in and pretty-prints without any install, and a short script gives you a whole language to reshape the data.
An everyday analogy
Cooking from an unfamiliar recipe.
| The kitchen | The client |
|---|---|
| Reading the recipe first | Reading the docs |
| Checking you have the ingredients | Required parameters |
| Following it exactly, once | Running their example verbatim |
| Then adjusting one thing | Changing one parameter at a time |
| Tasting as you go | Checking the response at each stage |
| Plating it | Presenting the result |
-
Nobody improvises a recipe they have never cooked. Run their example first, unchanged, and confirm it works.
-
Change one thing at a time, or you will not know which change broke it.
Examples in practice
-
A weather line in your shell prompt, refreshed by a one-liner.
-
A daily digest script that fetches, extracts three fields, and mails them — scheduled with Day 14’s cron.
-
A
jqpath that returnsnullbecause the field is nested one level deeper than you assumed. -
An empty response that was actually a
429, because nobody checked the status before parsing. -
A pipeline that broke when a value contained a space, because a variable was unquoted — Day 12’s rule, again.
Implications: security, privacy, performance, scalability, and cost
-
Security: never put a key in the URL. Day 25’s rule, and the command line makes it especially tempting.
-
Your shell history records every command, including any credential you typed inline. Read them from the environment.
-
Privacy: responses may contain personal data you are about to write to a file or a log. Decide what you keep.
-
Performance: each
curlis a fresh connection, paying the Day 15 handshake every time. For many calls, that is the argument for moving into a program with a session. -
Cost: a loop of one-liners against a metered API is a bill with no cap. Add a counter and a limit before you leave it running.
-
Always check the status before parsing. An HTML error page reaching
jqis a confusing failure with an obvious cause.
Alternatives: free, open source, and commercial
| Tool | Type | Where it fits |
|---|---|---|
curl + jq | Free, ubiquitous | Exploring, debugging, and plenty of real automation |
httpie | Free, open source | Exploring by hand, with better ergonomics |
python3 + requests | Free, open source | The moment you need logic, retries or tests |
python3 -m json.tool | Free, built in | Pretty-printing with nothing installed |
| Official SDKs | Usually free | Production use of a specific service |
| Postman / Insomnia | Free tiers | Saved collections and team sharing |
-
Learn
jq’s basics and stop there. Paths,select, and-rcover almost everything; the rest of the language is a rabbit hole. -
The moment you write your second
if, move to Python. That is the signal, and it is reliable.
Comparison with related concepts
| Term | What it actually is |
|---|---|
| Query string | ?name=value&name=value appended to a path |
-s | Silent: suppress curl’s progress meter |
jq path | A route into nested JSON, read left to right |
-r | Raw output: strings without their quotes |
| Exit code | How your script knows whether the call worked |
| Pipeline | Day 10’s idea, applied to an API response |
When to use it — and when not to
-
Use the command line first, always. Confirm the endpoint works before writing any code around it.
-
Keep it a one-liner while it fits on one line and needs no branching.
-
Promote it to a script when you want it repeatable, scheduled, or shared.
-
Promote it to a program at the first of three signals: you need a data structure, you need to catch an error and continue, or you want a test.
-
Do not build a large client in shell. Day 12’s boundary applies here exactly.
-
Do not parse without checking the status. It is one flag and it prevents the most confusing class of failure.
-
Do not leave a loop running unattended without a cap on iterations.
The AI connection
-
Every provider’s quickstart is a
curlcommand, and running it is the fastest way to confirm your key works before any code exists. -
A failing SDK call, reproduced in
curl, tells you immediately whether the problem is the request or the library. -
jqreads a model response cleanly —.choices[0].message.contentor the equivalent — which is how you check output without a program. -
Streaming is visible from the command line, arriving in chunks, which makes the mechanism concrete.
-
Token counts come back in the response, and extracting them with
jqis how you measure cost per call before scaling anything up.
Knowledge check
quiz:
question: "A pipeline that fetches JSON and extracts a field with `jq` starts printing parse errors. The endpoint works in a browser. What should you check first?"
options:
- "The HTTP status code, since an error response body is often HTML rather than JSON"
- "The jq path, since the response structure has probably changed"
- "The shell quoting on the URL, since & would background the command"
- "The Content-Type header, since jq requires it to be set correctly"
answer_index: 0
explanation: "jq is being handed something that is not JSON, and the usual reason is that the request failed — a 429, a 500, or an authentication error whose body is an HTML page. Checking the status before parsing turns a baffling parse error into a clear one."
Hands-on exercise
Build the client one stage at a time, adding error handling as you go. Worked through fully in the Day 28 lab directory.
| What you are doing | Command |
|---|---|
| Fetch and look | curl -s "$URL" |
| Pretty-print it | curl -s "$URL" | python3 -m json.tool |
| Extract one field | curl -s "$URL" | jq '.current.temperature_2m' |
| Strip the quotes | curl -s "$URL" | jq -r '.current.time' |
| Capture the status too | curl -s -w '\n%{http_code}' "$URL" |
| Fail on an error status | curl -sf "$URL" || echo "request failed" |
| Present it | printf '%s°C, wind %s km/h\n' "$t" "$w" |
Expected output
29.5
2026-07-12T12:30
200
request failed
29.5°C, wind 16.9 km/h
-rremoved the quotes, which matters the moment you put the value in a string.-fmakes curl exit non-zero on an error status, which is how the shell learns the call failed.
Validate your work
- You read the API’s documentation and identified all four contract questions
- You ran their example unchanged before altering anything
- You extracted two fields at different depths
- Your script fails loudly on a bad status rather than parsing an error page
- Your script produces a clean, readable line as its output
-
bash tests/run_tests.shreports 0 failures
Troubleshooting
-
Only part of the URL is fetched. The shell split it at
&. Quote the whole URL. -
jqreturnsnull. The path is wrong. Pretty-print the response and read the actual nesting. -
jq: command not found. Usepython3 -m json.toolto inspect, and a short Python one-liner to extract. -
The value comes out with quotes around it. Add
-r. -
The script keeps going after a failure. Add
-fto curl andset -euo pipefailto the script.
Common mistakes
- Parsing before checking the status.
- Unquoted URLs, which the shell rearranges for you.
- A key in the URL, which then lives in your shell history.
- Building the whole script before testing any stage of it.
Practice assignment
-
Pick a public API you have never used and get one successful call within ten minutes, using only its documentation.
-
Build a three-field report from its response, with error handling on every stage.
-
Break it deliberately four ways — bad URL, bad parameter, no network, wrong
jqpath — and confirm each produces a distinct, clear message. -
Schedule it with cron and confirm it still works with the minimal environment from Day 14.
Extension challenge
-
Rewrite your shell client in Python and compare the two side by side. Note exactly which lines got simpler and which got longer — that comparison is the judgement this lesson is really teaching.
-
Add retry with backoff from yesterday’s lesson, and prove it does not retry a
4xx. -
Chain two APIs, using a value from the first as a parameter to the second, and handle the case where the first returns nothing.
-
Measure the connection cost. Time twenty separate
curlcalls against twenty requests over one reused connection in Python. The ratio is the argument for graduating.
Quiz
Q1. In the six-stage API client pipeline, what is the correct order of the stages?
- Send, read the docs, build the request, present, parse, handle errors
- Build the request, read the docs, parse, send, present, handle errors
- Read the docs, build the request, send, parse the JSON, handle errors, present
- Parse the JSON, send, build the request, read the docs, present, handle errors
Show answer
Answer: C. Read the docs, build the request, send, parse the JSON, handle errors, present
Every client follows the same path: read the documentation, build the request from it, send it with curl, parse the JSON reply, handle whatever went wrong, and present a clean result. Each stage feeds the next.
Q2. Why must you wrap an API URL in double quotes when it contains a query string like ?a=1&b=2?
- Quotes make the request run faster
- Quotes encrypt the URL before sending it
- curl cannot read a URL longer than one parameter unless it is quoted
- A bare & means background, so curl gets only the first parameter
Show answer
Answer: D. A bare & means background, so curl gets only the first parameter
An unquoted & tells the shell to run the command in the background, cutting the URL off after the first parameter. Double quotes pass the whole URL, & and ? included, to curl intact.
Q3. Given the response {"current": {"temperature_2m": 12.4}}, which jq path prints 12.4?
- jq '.current.temperature_2m'
- jq '.current'
- jq '.temperature_2m'
- jq 'temperature_2m.current'
Show answer
Answer: A. jq '.current.temperature_2m'
A jq path reads left to right through the nesting: enter the current object, then take its temperature_2m field. The path mirrors exactly how the field is nested in the JSON.
Q4. Which statement about free public APIs is correct?
- Every public API requires an API key before you can call it
- Some public APIs need no key at all
- Free APIs never return JSON, only plain text
- You must install a special library to call any public API
Show answer
Answer: B. Some public APIs need no key at all
Many excellent public APIs are "no-key": Open-Meteo, Open Notify, and JSONPlaceholder all respond to an anonymous request, which is why they are ideal for learning the request-and-parse loop.
Q5. What is the single most transferable skill in consuming any new API?
- Memorizing every endpoint of the service
- Writing the client in a compiled language
- Reading the docs to find endpoints and parameters
- Guessing the field names until one works
Show answer
Answer: C. Reading the docs to find endpoints and parameters
You are never expected to memorize an API. Every API's docs answer the same four questions — endpoint, parameters, auth, response shape — so learning to read that contract makes any new service usable in minutes.
Q6. Your curl command prints nothing at all. Which is the best first thing to check?
- Reinstall curl from scratch
- Delete your parse step and hope it works
- Assume the API has permanently shut down
- Run the raw curl command alone first
Show answer
Answer: D. Run the raw curl command alone first
Isolate the stages: run the raw curl first. If it prints JSON, the fetch works and the problem is in your parse; if it prints nothing, the request or the network is the issue — check quoting and add --max-time to fail fast.
Q7. When should a curl one-liner graduate into a real program with an HTTP client library?
- When logic grows: loops, retries, branching, or several calls
- Never — a shell one-liner can do anything a program can
- Immediately — one-liners are never appropriate for real work
- Only when the API starts requiring a key
Show answer
Answer: A. When logic grows: loops, retries, branching, or several calls
Start at the command line to understand an API, then move the request into code exactly when the problem outgrows a single readable line — loops, retries, real error branching, or combining calls. The request itself does not change.
Q8. Why is consuming a weather API called the direct prerequisite for every AI API call in the course?
- Weather models and language models use the same training data
- Calling an AI model is the same motion with a different URL and body
- AI APIs return weather data by default
- Language models can only be reached through weather services
Show answer
Answer: B. Calling an AI model is the same motion with a different URL and body
A language-model call is this exact pattern: send a request to the model's endpoint, attach a JSON body describing the prompt, add an Authorization header, and parse the JSON reply. Endpoint, parameters, headers, auth, parse — every piece is what you practice on a free weather API.
Glossary
- API client
- A program — even a single command — that sends a request to a remote service and uses the response it gets back. Today you build one for weather.
- endpoint
- The URL a request is sent to, naming the specific resource or operation you want, like an address on an envelope.
- query parameter
- A name=value pair carried in the URL after a ?, joined by &, that specifies the details of your request (for example latitude=52.52).
- JSON parsing
- Pulling the fields you want out of a JSON response by their path, so a larger reply becomes the one or two values your program needs.
- jq
- A command-line tool that reads JSON structurally and extracts fields by path (for example .current.temperature_2m), the way grep extracts lines by pattern.
- curl
- A small, ubiquitous command-line program that makes an HTTP request to a URL and prints the response — the standard way to send an API call from a terminal.
- error handling
- Checking whether a request actually succeeded and whether the expected field was present, so a failure produces a clear message instead of garbage or a crash.
- free tier
- A level of an API that costs nothing to use within stated limits; free public APIs like Open-Meteo make them ideal for learning without a bill.
- no-auth API
- A public API that requires no key or token to call — anyone can send an anonymous request and get a response, as with Open-Meteo, Open Notify, and JSONPlaceholder.
- request pipeline
- The six repeatable stages of any API client: read the docs, build the request, send it, parse the JSON, handle errors, and present the result.
- HTTP client library
- A library inside a programming language (such as Python's requests or JavaScript's built-in fetch) that sends HTTP requests from code, used when a shell one-liner outgrows a single line.
- documentation
- The reference an API publishes describing its endpoints, parameters, authentication, and response shape; reading it is the core transferable skill of consuming any API.
- rate limit
- A cap a service places on how many requests you may send in a period; a polite client stays within it, spacing requests and honoring any Retry-After header.
Sources and further reading
- Open-Meteo — Free Weather API — Open-Meteo (accessed 2026-07-12) — The no-key weather API this lesson and lab build a client for; documents the forecast endpoint and its parameters.
- curl Documentation — curl / Daniel Stenberg (accessed 2026-07-12) — Reference for the command-line HTTP tool used to send every request in this lesson.
- jq Manual — jq (accessed 2026-07-12) — Reference for the command-line JSON processor used to parse responses by path.
- Working with JSON — MDN Web Docs (accessed 2026-07-12) — Background on the JSON format that nearly every API responds in.
- JSONPlaceholder — Free fake REST API — JSONPlaceholder (accessed 2026-07-12) — A free no-key test API used to practice reading lists and indexing arrays.
Kept in this browser, no account needed. Your progress page turns the whole record into one link you can bookmark or open on another device.