Vote upto Idea Response format is unusual and hard to use Vote downto Idea Response format is unusual and hard to use

Rank20

Idea#14

This idea is active.
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.

Comment

Submitted by rkosara 11 months ago

Vote Activity Show

Similar Ideas Show

Events

  1. The idea was posted
    11 months ago

Comments (3)

  1. Phillip Thomas

    I disagree, for three reasons.

    a) Either option would cause the response time to slow down, creating the JSON object (or just one object in general) is almost universally faster then creating an array/list (both objects in themselves for some languages) of objects. The API sends out data for many requests, so even a slight increase in response time would be unacceptable for some applications.

    b) The size of the returned data would be increased, causing more bandwidth, storage, and processing time.

    c) What is easier for one developer may cause problems for other developers. Currently a developer can do anything with the data once it has been retrieved from the API's server. Forcing the cost of multiple objects could not only break what currently exists, but slow down the apps created by developers, which would become noticeable with larger queries.

    11 months ago
    1 Vote upto Comment
    0 Vote downto Comment
  2. david.john.maccormack

    rkosara,

    Thank you for the feedback.

    One of our primary design goals for the API was to make sure it works well with mobile apps. The current response format has a small footprint where column headers are specified in the first row and the results are in the following rows. If we use a format similar to what you've outlined then we would effectively be repeating the column headers for every row and that would increase the size of the response -- significantly in some cases. For many of our internal use cases it would have an unacceptable impact on performance.

    That being said, we're not opposed to providing an alternative format which is triggered with an additional CGI parameter in the URL. I'd like to get feedback from other users. What do you think of the format rkosara proposed? Would you prefer something different and, if so, why?

    Thanks.

    11 months ago
    0 Vote upto Comment
    0 Vote downto Comment
  3. alanj

    I was wishing for an array when I started working with the API, but I understand the reasons for the current output. It would be nice to have different options.

    11 months ago
    1 Vote upto Comment
    0 Vote downto Comment