Boxdata πŸ”—

β€œBoxdata” are the records that correspond to published CrunchBoxes. These endpoints enable you to create new CrunchBoxes and view records for previously created boxes.

Catalog πŸ”—

/datasets/{id}/boxdata/

A Shoji Catalog of boxdata for a given dataset.

GET catalog πŸ”—

When authenticated and authorized to view the given dataset, GET returns 200 status with a Shoji Catalog of boxdata associated with the dataset. Otherwise, the response status is 404.

Catalog tuples contain the following keys:

Name Type Description
title string Human friendly identifier
notes string Other information relevant for this CrunchBox
header string header information for the CrunchBox
footer string footer information for the CrunchBox
dataset string URL of the dataset associated with the CrunchBox
revision string Dataset revision ID when the box was computed
filters object A Crunch expression indicating which filters to include in the CrunchBox
where object A Crunch expression indicating which variables to include in the CrunchBox. An undefined value is equivalent to specifying all dataset variables.
weight string URL of the weight to apply, or null for unweighted. If not specified, the server will use the user’s currently applied weight.
creation_time string A timestamp of the date when this CrunchBox was created

The corresponding CrunchBoxes can be accessed at https://s.crunch.io/widget/index.html#/ds/{boxdata_id}/.

{
    "element": "shoji:catalog",
    "self": "https://beta.crunch.io/api/datasets/e7834a/boxdata/",
    "index": {
        "https://beta.crunch.io/api/datasets/e7834a/boxdata/44a4d477d70c85da4b8298677e527ad8/": {
            "user_id": "00002",
            "footer": "This is for the footer",
            "notes": "just a couple of variables",
            "title": "z and str",
            "dataset": "https://beta.crunch.io/api/datasets/e7834a/",
            "header": "This is for the header",
            "creation_time": "2017-03-14T00:13:42.024000+00:00",
            "revision": "77d70a",
            "where": {
                "function": "select",
                "args": [{
                    "map": {
                      "000002": {"variable": "https://beta.crunch.io/api/datasets/e7834a/variables/000002/"},
                      "000003": {"variable": "https://beta.crunch.io/api/datasets/e7834a/variables/000003/"}
                    }
                }]
            },
            "filters": [
              {"filter": "https://beta.crunch.io/api/datasets/e7834a/filters/da9d86e43381443d9d708dc29c0c6308/"},
              {"filter": "https://beta.crunch.io/api/datasets/e7834a/filters/80638457c8bd4731990eebdc3baee839/"}
            ],
            "weight": "https://beta.crunch.io/api/datasets/e7834a/variables/000012/",
            "id": "44a4d477d70c85da4b8298677e527ad8"
        },
        "https://beta.crunch.io/api/datasets/e7834a/boxdata/75ff1d67ed698e0986f1c1c3daebf9a2/": {
            "user_id": "00002",
            "title": "xz",
            "dataset": "https://beta.crunch.io/api/datasets/e7834a/",
            "revision": "f43d21",
            "filters": null,
            "creation_time": "2017-03-14T00:13:42.024000+00:00",
            "where": {
                "function": "select",
                "args": [{
                    "map": {
                      "000000": {"variable": "https://beta.crunch.io/api/datasets/e7834a/variables/000000/"}
                    }
                }]
            },
            "weight": null,
            "id": "75ff1d67ed698e0986f1c1c3daebf9a2"
        }
    }
}

POST catalog πŸ”—

Use POST to create a new CrunchBox. Note that new boxdata is only created when there is a new combination of where and filter data. If the same variables and filters are indicated by the POST data, the existing combination will result in a modification of metadata associated with the cube data. This is to keep avoid recomputing analysis needlessly.

A successful POST returns with 202 Continue status, containing a Progress URL in the response body and the URL to the created boxdata entity in the Location header. See Progress for how to handle the response body.

Once the box has finished computing, the CrunchBox can be accessed at https://s.crunch.io/widget/index.html#/ds/{boxdata_id}/.

A POST to this resource must be a Shoji Entity with the following β€œbody” attributes:

Name Description
title Human friendly identifier
notes Other information relevant for this CrunchBox
header header information for the CrunchBox
footer footer information for the CrunchBox
filters A Crunch expression indicating which filters to include
where | A Crunch expression indicating which variables to include
——————– β€”β€”- β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”-
variables | Array of URLs pointing to folders or variables to include
Note: variables and where cannot be used together
weight URL of a weight variable; cubes are unweighted if omitted
display_settings Options to customize how it looks and behaves
{
    "element": "shoji:entity",
    "body": {
        "where": {
            "function": "select",
            "args": [{
                "map": {
                  "000002": {"variable": "https://beta.crunch.io/api/datasets/e7834a/variables/000002/"},
                  "000003": {"variable": "https://beta.crunch.io/api/datasets/e7834a/variables/000003/"}
                }
            }]
        },
        "filters": [
          {"filter": "https://beta.crunch.io/api/datasets/e7834a/filters/da9d86e43381443d9d708dc29c0c6308/"},
          {"filter": "https://beta.crunch.io/api/datasets/e7834a/filters/80638457c8bd4731990eebdc3baee839/"}
        ],
        "force": false,
        "title": "z and str",
        "notes": "just a couple of variables",
        "header": "This is for the header",
        "footer": "This is for the footer"
    }
}

Display Settings πŸ”—

The display_settings member of a CrunchBox payload allows you to customize several aspects of how it will be displayed.

A minBaseSize member will suppress display of values in tables or graphs where the sample size is below a given threshold.

To customize a CrunchBox’s color scheme, you may include an optional palette member in the display_settings of the body of the request to create or edit the boxdata. There are four types of customization available.

{"display_settings": {
    "minBaseSize": {"value": 50},
    "palette": {
        "brand": {
            "primary": "#111111",
            "secondary": "#222222",
            "messages": "#333333"
        },
        "static_colors": ["#444444", "#555555", "#666666"],
        "category_lookup": {
            "category name": "#aaaaaa",
            "another category:": "bbbbbb"
        }
    }
}}

Brand πŸ”—

The CrunchBox interface uses three colors, named Primary, Secondary, and Messages. By default, these are Crunch brand colors of green, blue, and purple. These are used, for example, as the background colors at the top of the interface and the color of the filter selector.

Static colors πŸ”—

Include an array of static_colors and every categorical color will be taken from the list in order. If none of your variables have more categories than colors provided here, the generator (below) will never be used, but category lookup will be performed.

Base πŸ”—

If the number of categories exceeds the number of static colors, or no static colors are specified, β€œbase” colors are used to generate a categorical palette. By default, these are also the Crunch green, blue, and purple, and are not overridden by brand. Each color is interpolated in HCL space from itself to Hue + 100, Lightness + 20; and then colors are ordered to maximize sequential absolute distance in Lab* space so adjacent colors can be easily distinguished.

Category Lookup πŸ”—

Finally, you may include an object where keys are exact category names that should always be assigned a specific color. Using semantically resonant colors in this manner is a boon for interpretation and is highly recommended when possible. For example, to ensure that the Green Party is a verdant shade, include a member such as "Green": "#00dd00". Building a category lookup list requires some attention to the specific categories in a dataset; they must match exactly, and not partially; to ensure that β€œGreen Party” is also green, include an additional "Green Party" key with the same value. Lookup values are processed last, replacing erstwhile static or generated colors.

Entity πŸ”—

/datasets/{id}/boxdata/{id}/

This endpoint represents each of the boxdata entities listed in the catalog.

The body of any of the entities is the same as the catalog’s tuple:

GET πŸ”—

Returns the body of the boxdata entity

{
    "user_id": "00002",
    "footer": "This is for the footer",
    "notes": "just a couple of variables",
    "title": "z and str",
    "dataset": "https://beta.crunch.io/api/datasets/e7834a/",
    "revision": "77d70a",
    "header": "This is for the header",
    "where": {
        "function": "select",
        "args": [{
            "map": {
              "000002": {"variable": "https://beta.crunch.io/api/datasets/e7834a/variables/000002/"},
              "000003": {"variable": "https://beta.crunch.io/api/datasets/e7834a/variables/000003/"}
            }
        }]
    },
    "filters": [
      {"filter": "https://beta.crunch.io/api/datasets/e7834a/filters/da9d86e43381443d9d708dc29c0c6308/"},
      {"filter": "https://beta.crunch.io/api/datasets/e7834a/filters/80638457c8bd4731990eebdc3baee839/"}
    ],
    "weight": "https://beta.crunch.io/api/datasets/e7834a/variables/000012/",
    "id": "44a4d477d70c85da4b8298677e527ad8"
}

PUT πŸ”—

PUT a complete entity body to update a CrunchBox. This will register any changes to the variables, filters, and other metadata, and will trigger a recomputation of the box data using the latest data from the dataset if either the variable/filter selection changes or if the dataset’s β€œrevision” has changed since the previous computation. That is, if the dataset has changed since the time when the box was originally computed and you want to update the values in the CrunchBox, use a PUT.

PATCH πŸ”—

PATCH selected body attributes to more selectively update a CrunchBox. Unlike PUT, if PATCHing only metadata attributes, such as title and display_settings, the box data will not be recomputed. If variable or filter selections are modified, then the box will recompute on PATCH.

DELETE πŸ”—

Deletes the entity and remove all published CrunchBox files for this box. Returns 204.