When Should a Public Data API Use JSON or CSV?
From the earlier reference collection. Read the current software blog.
Choose a format by the shape of the data and the work clients need to do: JSON supports nested structures, while CSV is convenient for flat tables.
Match the format to the shape
CSV works well when each row represents one thing and each column has one value, such as a station identifier, observation time, and water temperature. Spreadsheet users can inspect it quickly, and command-line tools can stream or filter rows without understanding a complex object model.
JSON is a better fit when records contain structured parts. A transit trip might include a route object, stop details, and an array of accessibility features. Encoding those relationships in CSV often requires repeated rows, invented column names, or several linked files.
Consider the client’s task
Suppose a daily file contains 20,000 sensor readings with the same four columns. A CSV download is practical for analysis in a spreadsheet or a small script. A client can select the columns it needs and process one row at a time.
For an endpoint returning one station with its location, current status, and a list of recent readings, JSON keeps each component grouped. A program can read the station object and iterate over the readings without guessing how columns encode a list.
Make the trade-offs explicit
A format alone does not make data clear. CSV needs a stable header, documented character encoding, delimiter and quoting rules, and a defined representation for missing values. JSON needs field names, data types, and clear rules for optional or null values. Both formats need consistent timestamps and units.
It is also reasonable to offer both when audiences have distinct needs. Keep their underlying meanings aligned: a temperature of 12.5 should not silently become a differently rounded or differently unitized value in one download. State which format is intended for bulk export and which is intended for structured application use.
A practical decision
Start by drawing one representative record. If it is a flat set of named values, CSV is likely the simpler exchange format. If it contains arrays, nested objects, or relationships that matter to clients, JSON will usually preserve the structure with less convention.
Then test the format with a realistic client task: load a file, find a record, and interpret a missing value. Choose the version that makes those steps direct, and document any limitations so users can build reliable tools around it.