API foundations — course checkpoint

You started this course able to copy a URL. You finish able to read a spec, name an instrument precisely, predict what a job will cost, tell four kinds of failure apart, and say why a number you fetched is trustworthy.

Unit 1 — how an API answers a question

A request is one complete question with no memory attached: base URL, path, query parameters, token. The path says which thing; the query parameters say how you want it. Some of them change the shape of the answer entirely — filter=last_close turns an array of rows into a single bare number.

The token travels in the URL as api_token, which means it travels into logs, history and screenshots. Keep it server-side; never call the API from browser JavaScript.

fmt=json for programs and nested documents, fmt=csv for spreadsheets and bulk loads. Always send it explicitly — not just because the defaults differ per endpoint, but because three of them (/real-time, /div, /splits) document JSON and serve CSV, and /calendar/dividends serves a 422.

And the spec is a description, not a validator. It is where you learn that the interval enum is all five of 1m, 5m, 15m, 30m, 1h, that intraday volume can be null, and that /symbol-change-history is US-only — and it is not where you learn what the server rejects, because the server rejects almost nothing. period=weekly, fmt=xml, filter=last_bogus, from=notadate and a missing "required" interval all return 200 and an answer to a different question. The one thing it does check, a typed parameter, comes back 422, not 400.

Unit 2 — naming the thing you want

SYMBOL.EXCHANGE, because a ticker is only unique within a venue. AAPL.US, VOW3.XETRA, HSBA.LSE — and .US is a combined code covering XNAS, XNYS, OTCM, XCBO, not a single exchange.

For US tickers the API defaults to .US, so /eod/AAPL really does work. /eod/VOW3 returns 404 Ticker Not Found — the default is an assumption, not a search. Write the suffix anyway.

Tickers change: MMC → MRSH on 2026-01-14, MPW → MPT on 2026-02-02, four Invesco ETFs on 2026-02-23 alone. A series keyed on a ticker just stops, silently. Key on something stable.

And five codes in /exchanges-list are not venues at all — FOREX, CC, GBOND, MONEY, EUFUND — they are namespaces so that EURUSD.FOREX and US10Y.GBOND fit the same grammar. INDX works but is not in the list at all.

Unit 3 — limits, cost and failure

Two walls, and two different currencies. The daily quota counts calls — 100,000/day on paid plans, 20/day on Free, read from /user. The rate limit counts requests — a published 1,000 per minute, per minute and never per second, with the live header currently reading 1200. The X-RateLimit-Limit and X-RateLimit-Remaining headers arrive on every response, not just a throttled one, so the gauge is free to watch; Retry-After is the throttled case only.

On a 1-call endpoint you spend a whole day's quota in 100 minutes. On a 10-call one, 10 minutes; on a 100-call one, a minute. Paced evenly, 100,000 calls is about 69 requests per minute and you never touch the rate limit at all.

The account endpoint reports the daily quota in a field called dailyRateLimit. It is the quota. Remaining today = dailyRateLimit + extraLimit − apiRequests — and check apiRequestsDate against today first, because on a quiet morning it is still yesterday's.

Calls cost 1, 5, 10 or 100 depending on the endpoint. 3,000 tickers one at a time is 3,000 calls; /eod-bulk-last-day/US is 100. A failed bulk request still costs its 100.

Retry only 429 and 5xx, with backoff. 400, 422, 401, 403, 404 will never succeed on repetition, and retrying a 429 without waiting causes the next one.

Unit 4 — trusting what comes back

close and volume for a settled day are history, once the venue's revision window has passed — inside it, a recent volume can still be corrected. adjusted_close is recomputed by every dividend: 499.23 raw against 121.06 adjusted on 2020-08-28 as fetched on 2026-07-28, where split-only would be 124.81 and always will be. Reproducibility means recording the exact URL, the fetch timestamp and the fields used — the reason the middle number in that sentence carries a date and the other two do not.

EOD has a date and no time. Intraday has timestamp, gmtoffset and datetime, and a bar is stamped at its start — 1628876400 − 1628876100 = 300 seconds. from/to are strings on /eod and integers on /intraday.

Null is "we don't have it", zero can mean "not applicable here" (US10Y.GBOND and EUR.FOREX both report volume: 0), and a missing row is a day that never existed. Four rows in a five-day window, averaged over five, is 20% low and reports no error.

The five-point check, ported to an API response

Reading the Market gave you a five-point sanity check for a number on a chart. Here it is, aimed at a JSON payload instead.

1. Timestamp — which time field, whose timezone, how old? date versus timestamp plus gmtoffset. A delayed quote is 15–20 minutes old by design, not by fault.
2. Adjustment — close or adjusted_close? The adjusted column is not stable across pulls, so a result computed from it needs a fetch date attached.
3. Sample — how many rows came back, against how many trading days you expected? Missing rows are silent, and a renamed ticker truncates a series without an error.
4. Source agreement — does a second route agree? The same symbol via /eod and /real-time, or AAPL against AAPL.US, or one venue against another. Disagreement is information: it is nearly always a different venue, a different adjustment, or a different timestamp — and you now know how to check all three.
5. Plausibility — a 4,000% day is a decimal error, a split artefact, or a null that somebody filled with zero, until proven otherwise. 200 OK means the request succeeded, not that the answer is right.

Thirty seconds, five questions, and most bad numbers die before they reach anything that matters.

Before you sit it

Each of these is a minute at your desk. Any one that is not names the lesson to reopen first.

• Name the part of a request that carries your key and the part that selects the data — Which part of a request is doing the work?
• Say why AAPL on its own is not a name — Why isn't AAPL enough to name a stock?
• Say how one request can consume a hundred calls — Why did one request use 100 calls?
• Say how you tell a zero from a null from a day that never happened — Is that a zero, a null, or a day that never happened?

Try it now

1. Here is the spec entry for /splits/{ticker}, an endpoint this course has not called, read on 28 September 2026 and laid out as two tables. From the two tables alone, predict the required parameters, the enums, the nullable fields, the format you get with no fmt, and what AAPL.US returns; take the call cost from the table in the cost lesson. Then score yourself against the live answer below the tables, and against this: called on 28 September 2026 with no fmt, it answered Content-Type: application/csv.

2. Run the five-point check on the real response below, /eod/AAPL with no suffix for one September week, writing one sentence per point. If any point takes longer than ten seconds, that is the part of your setup worth fixing.

3. Price your next data job in calls before you write a line of it, and write down which of the two walls it would hit first.

Checkpoint quiz next, then Course 2, which takes the price and trading endpoints apart properly — EOD, intraday, delayed quotes, ticks, bulk-by-exchange, adjustments and trading hours. Nothing in this course recommended an instrument, a strategy or a course of action; it described how a market-data API behaves and how to check what it hands you. That is a skill, not a signal.