Collections are groups of datapoints which occur multiple times for a geographic region. For example, there is only one population for a geographic region; however, there can be multiple airports, hospitals, or universities for a geographic region. These types of data are called point-level data, meaning that they reference a point on a map. The API will organize point-level data into collections of datapoints.

Collections are also used when retrieving datapoints that are broken out by codes. For example, the occupation statistics for a geographic region are broken out by occupation code, and the industry statistics are broken out by industry code. The API will organize these data points into collections as well.

Developers will be familiar with the notion of arrays. Database administrators will be familiar with the notion of parent and child tables, connected by foreign constraints. Collections serve the same purpose.

Structure of a Collection

The API returns collections of datapoints using a structure of items and data. Items are the members, or “rows” within a collection. Data are the requested datapoints within a member of a collection, plus any nested collections.

For those familiar with relational databases:

• A collection is equivalent to a child table
• A collection item is equivalent to a unique value for the primary key of a child table
• Collection data are equivalent to the other columns in the child table.
• Collections can be nested, just like a child table can have a “grandchild” table.

Examples of Collection Structure

The following example shows collections and items in the request and the response.

var request = {
  "data": {
    "datapoints": [
      ...
    ],
    "collections": [
      {
        "collection": "...",
        "datapoints": [
          ...
        ]
      }
    ]
  },
  "criteria": {
    ...
  }
};

var response = {
  "resultset": {
    "geography": ...,
    "data": [
      {
        "collection": "x",
        "items": [
          {
            "item": "a",
            "data": [
              ... 
            ]
          },
          {
            "item": "b",
            "data": [
              ... 
            ]
          }
        ]
      }
    ]
  }
};

This same structure can be seen in this excerpt from a response buffer showing the population of the Burlington, VT Metro Area, plus the commercial airports within the metro area:

var request = { "data": { "datapoints": [ "dem.acs.pop.total.val" ], "collections": [ { "collection": "trn.airport", "datapoints": [ "trn.airport.name", "trn.airport.runway" ] } ] }, "criteria": { "geography": "cbsa:burlington-south-burlington-vt-metro-area" } }; var response = { "resultset": { "geography": "cbsa:burlington-south-burlington-vt-metro-area", "data": [ { "datapoint": "dem.acs.pop.total.val", "period": "2017", "source": "acs5", "value": 216751 }, { "collection": "trn.airport", "items": [ { "item": "BTV", "period": "2017", "data": [ { "datapoint": "trn.airport.name", "value": "Burlington Intl" }, { "datapoint": "trn.airport.runway", "value": 8319 } ] } ] } ] } };

Collections with Geographic Context

Collections may have their own geographic context. This can occur because requested datapoints are not available for the primary geography and must be provided in a correlated geography. For example, a request could be made for the population for the city of Burlington, VT, plus the correlated Occupational Employment Statistics (OES) data. Since OES data is not available at the city level, the collection will be shown for the metropolitan area associated with the city. The API will reflect this change of geographic context with geography elements, as shown in the following example. [Note that in this example, only a limited amount of OES data is shown for brevity. The documentation on Scope explains how to limit collections using criteria.]

var request = {
{
  "data": {
    "datapoints": [
      "dem.acs.pop.total.val"
    ],
    "collections": [
      {
        "collection": "wkf.oes.occ",
        "datapoints": [
          "wkf.oes.occ.desc",
          "wkf.oes.occ.emp.val"
        ]
      }
    ]
  },
  "criteria": {
    "geography": "city:burlington-vt"
  }
}

var response = {
{
  "resultset": {
    "geography": "city:burlington-vt",
    "data": [
      {
        "datapoint": "dem.acs.pop.total.val",
        "period": "2017",
        "source": "acs5",
        "value": 42453
      },
      {
        "collection": "wkf.oes.occ",
        "geography": "cbsa:burlington-south-burlington-vt-metro-area",
        "items": [
          {
            "item": "15-1132",
            "period": "2018",
            "data": [
              {
                "datapoint": "wkf.oes.occ.desc",
                "value": "Software Developers, Applications"
              },
              {
                "datapoint": "wkf.oes.occ.emp.val",
                "value": 510
              }
            ]
          },
          {
            "item": "15-1133",
            "period": "2018",
            "data": [
              {
                "datapoint": "wkf.oes.occ.desc",
                "value": "Software Developers, Systems Software"
              },
              {
                "datapoint": "wkf.oes.occ.emp.val",
                "value": 700
              }
            ]
          }
        ]
      }
    ]
  }
};

Note that collections may have multiple geographic contexts. For example, a request could be made for the population for the city of Atlanta, GA, plus the correlated County Business Patterns (CBP) industry data. Since CBP data is not available at the city level, the collection will be shown for the counties associated with the city. Some cities, such as Atlanta, GA, reside within multiple counties.  In these cases, the collection will show multiple geographies.

Nested Collections

Collections may be nested. This means that each item within a collection has a subordinate collection as well. For example, a request could be made for the population of the city of Burlington, VT, plus the number of bachelor’s degrees in two specific majors for large universities within the city. The first collection is the universities within the city, and the second collection is the majors within each university. This is shown in the following example. [Note that in this example, only a limited amount of IPEDS data is shown for brevity. The documentation on Scope  explains how to limit collections using criteria.]

var request = {
{
  "data": {
    "datapoints": [
      "dem.acs.pop.total.val"
    ],
    "collections": [
      {
        "collection": "edu.ipeds.inst",
        "datapoints": [
          "edu.ipeds.inst.name",
          "edu.ipeds.inst.ugrad"
        ],
        "collections": [
          {
            "collection": "edu.ipeds.inst.deg",
            "datapoints": [
              "edu.ipeds.inst.deg.desc",
              "edu.ipeds.inst.deg.bach.val"
            ]
          }
        ]
      }
    ]
  },
  "criteria": {
    "geography": "city:burlington-vt"
  }
}

var response = {
  "resultset": {
    "geography": "city:burlington-vt",
    "data": [
      {
        "datapoint": "dem.acs.pop.total.val",
        "period": "2017",
        "source": "acs5",
        "value": 42453
      },
      {
        "collection": "edu.ipeds.inst",
        "items": [
          {
            "item": "230852",
            "period": "2018",
            "data": [
              {
                "datapoint": "edu.ipeds.inst.name",
                "value": "Champlain College"
              },
              {
                "datapoint": "edu.ipeds.inst.ugrad",
                "value": 4965
              },
              {
                "collection": "edu.ipeds.inst.deg",
                "items": [
                  {
                    "item": "11.02",
                    "period": "2018",
                    "data": [
                      {
                        "datapoint": "edu.ipeds.inst.deg.desc",
                        "value": "Computer Programming"
                      },
                      {
                        "datapoint": "edu.ipeds.inst.deg.bach.val",
                        "value": 8
                      }
                    ]
                  },
                  {
                    "item": "11.07",
                    "period": "2018",
                    "data": [
                      {
                        "datapoint": "edu.ipeds.inst.deg.desc",
                        "value": "Computer Science"
                      },
                      {
                        "datapoint": "edu.ipeds.inst.deg.bach.val",
                        "value": 31
                      }
                    ]
                  }
                ]
              }
            ]
          }
        ]
      }
    ]
  }
};