API Technical Discussions

Response format is unusual and hard to use

First, let me applaud the Census Bureau for doing this, it's an awesome project.


I'm glad to see JSON as the response format for the API, but structure makes it really hard to use. I also haven't seen this list-of-lists format for individual records before.


What would work much better would be one of the following:


a) an array of objects. Within each object, each field name is a key, each value is the value associated with that key. This is a common pattern and easy to use from functional-oriented languages like JavaScript, and easily maps into any language that has hash tables.


b) a list of lists, but make each list a column rather than a row. That means some kind of header for the column names, and then all values in each column in a list. Alternatively, the top-level object could be an object with a "_keys" field that contains the column names and then one key-value pair per column, with the column name as the key and all the values in a list as the value.


Both formats make iteration and quick access to specific fields a lot easier. Most developers will likely convert the data that's coming back from the API into such a structure before using it, so saving us the step would be helpful.



5 votes
7 up votes
2 down votes
Idea No. 242