Sign in
x
☰

Protobi JSON API

Updated at 2022-09-29 01:50:02 UTC

Protobi JSON API Reference

Overview

Protobi projects consist of "data" and "metadata". The "data" is the response values for each respondent, and the "metadata" is information about the data, such as the question title, the column name, and the response value labels.

The metadata is stored in JSON syntax. as array of elements, where each element is an object with atttribute-value pairs.

Example

An example is below:

{
    "key": "Q2",
	"displayKey": "Question 2.  Opinions",
    "title": "Do you agree with the following statements?",
    "children": ["Q2a", "Q2b", "Q2c", "Q2d","Q2e"],
    "format": {
       "1": "Extremely favorable",
       "2":  "Somewhat favorable",
       "3":  "Somewhat unfavorable",
       "4":  "Extremely unfavorable",
       "5":  "Don't know / no opinion"
    },
    "type": "number",
    "showBasis": true,
    "showStats":  { "value": [1,2], "label": "Favorable NET"},
    "chartType": "Pie",
    "filter": {
        "Q1": 2
    },
    "roundby": null
}

Brief intro JSON Syntax

This syntax may look foreign at first, but has the advantage of being both easily readable by computers in almost any language, and also readable and editable by humans (at least with a little bit of introduction).

The basic idea is that an element is defined as an "object" that defines attribute-value pairs. In the example above, "title" is one such key and "Do you agree with the following statements?" is its corresponding value.

Attributes are always strings. Values can be

  • numbers (e.g. 10),
  • strings (e.g. "Q2"),
  • booleans (e.g. true),
  • arrays of values (e.g. [4,5]) or
  • objects (e.g. see format above).

A complete list of all JSON attributes

Protobi conventions

In Protobi Each element is uniquely identified by an attribute "key". No two attributes in a Protobi project can have the same value of "key".

And often the key alone can be enough to define the element - Protobi will assume the element corresponds to a data column of the same name, and will use the key as its identifier for display.

  • Top-level attributes Core information needed to calculate the data are generally top-le
  • Chart options Detailed attributes to customize display are typically under the chartOptions
  • Root element The element with key "$root" specifies project-level settings and defaults.

Top-Level Element Properties

Properties that can be set on any element (question, category, group).

Core Properties

Property Type Description Values/Examples
key string Each element is uniquely identified by its key. The key can be any string value, including spaces or special characters. The key is immutable.
title string Longer description or question text
children string Define a group by listing keys of child elements, separated by commas.
type string Type of data. Set type to 'empty' for groups that don't have their own data column. "", "date", "empty", "number", "string"
display string "", "checkbox", "compact", "independent", "stacked", "squish"

Common Properties

Property Type Description Values/Examples
col string Element key(s) that define crosstab column, separated by comma
color string Sets the color for an element or category. Accepts any CSS color value "red", "#FF0000", "#F00"...
compactto `string number Array`
dataType string "date", "number", "string"
displayKey string Specify a different string to appear as the key for display.
editorOnly boolean Hide element from clients with View permissions false, true
element string Draw data for this element from a different element. This is useful to leverage recoding or other transforms applied in another element. "A8_1", "B6", "B7_dampening"...
field string Use a different data column to use as source for this element. The default is to assume the field is the same as the element key.
filter Object Filters data using MongoDB query syntax. Defines which records to include in this element {"Q1A":1}, {"$or":[{"Q1A":1},{"Q1A":2}]}, {"$and":[{"age":{"$gte":18}},{"region":"US"}]}...
footnote string Specify text to appear below the element. Text here will override any auto-generated footnotes.

Additional Properties

Property Type Description Values/Examples
format Object Maps data values to display labels. Used to define value labels for categorical variables {"0":"Yes","1":"No"}, {"0":"1 - Not important at all","1":"2","2":"3","3":"4 - Very important"}...
headline string Brief description or summary
heritable boolean Optionally prevent any changes to this element from propagating to child elements. Default is true. false, true
hidden boolean false, true
isCaseWeight boolean false, true
maxChildren number Number of child elements to display before converting to a scrollable layout. Set to 0 to clear. 10, 12, 15...
maxValue number Set maxValue to provide a reference for means, so that they can be drawn as bar charts. 100...
measure string "nominal", "ordinal", "scale"
multiples string Copy for each value of another element "hd0a", "hidSQ30", "overall"...
numericMax number Maximum allowed value for numeric input validation 10, 100, 120...
numericMin number Minimum allowed value for numeric input validation 0, 1, -999...
protect boolean Protect element when resetting from survey engine false, true
roundby `string number Array`
scale number Multiply values by a constant or data value, e.g. scale fractions by 100 to become percentages between 0 and 100. 100...
showBasis boolean Whether to show the sample size (N) for this element false, true
showBasisUnweighted boolean false, true
showDistinct boolean false, true
showMean boolean false, true
showMissing boolean Override [NA] tool button to never (or always) include missing values in percentages. false, true
showPercent boolean Override #/% toolbar button to never or always show percentages false, true
showStats Array Array of custom statistics to display. Each can be an object with value and label, or a simple value. Values can be numbers, arrays, or special values like "$mean", "$median" [{"value":[4,5],"label":"T2B"}], [{"value":[2,3,4,5],"label":"Aware"},{"value":[3,4,5],"label":"Familiar"}], ["$mean","$median"]...
showUnformatted boolean false, true
split string Split responses at a delimiter to treat as a multiple responses. ",", "json", "word"
suppress Object Maps values to boolean indicating whether to hide that value in display {"":true,"$other":true}, {"1":true,"2":true,"3":false}, {"=6":false,"=7":false}...
titles Object Multi-language title mappings. Keys are language codes (e.g., "en", "es", "fr"), values are translated titles {"en":"What is your age?","es":"¿Cuál es tu edad?","fr":"Quel est votre âge?"}...
valueFormat string Number format for element values and means, in d3 syntax (e.g '0.1%' for percent with one decimal) ".02%", ".0f", "%"...
weight string Count each response by a frequency 0.125, 1, "B10_Kx"...

Chart Options

Chart options are specified within the chartOptions object on an element. These control how data is visualized.

Usage Example

{
  "q1": {
    "key": "q1",
    "title": "Satisfaction",
    "chartOptions": {
      "width": 800,
      "height": 400,
      "orientation": "h",
      "barmode": "stack",
      "showlegend": true,
      "xaxis": {
        "tickangle": -45
      },
      "yaxis": {
        "rangemode": "tozero"
      }
    }
  }
}

General Chart Options

Properties used across multiple chart types.

Property Type Description Values/Examples
barWidth number Set the width of the bar
fontWeight string Font weight, e.g. bold or 700 "", "bold"
rowHeight number Set the height of the row
showBars boolean Whether to show bars false, true
testUsingPairedSamples boolean Test differences using as paired samples (rather than independent samples) if possible false, true

Plotly.js Properties

These properties map directly to Plotly.js layout and trace properties.

Dimensions

Control chart size.

Property Type Description Plotly Mapping
height number Chart height in pixels layout.height
width number Chart width in pixels layout.width

Margins

Control spacing around the chart.

Property Type Description Plotly Mapping
margin.b number Bottom margin, in pixels layout.margin.b
margin.l number Left margin, in pixels layout.margin.l
margin.r number Right margin, in pixels layout.margin.r
margin.t number Top margin, in pixels layout.margin.t

Legend

Control legend appearance and position.

Property Type Description Plotly Mapping
legend.orientation string Whether to show legend vertically or horizontally layout.legend.orientation
legend.xanchor string Whether legend x position specifies the left, center or right of the legend layout.legend.xanchor
legend.yanchor string Whether legend y position specifies the top, center or bottom of the legend layout.legend.yanchor

X-Axis

Control horizontal axis appearance and behavior.

Property Type Description Plotly Mapping
xaxis.autorange boolean Automatically set the range based on data layout.xaxis.autorange
xaxis.rangemode string If 'normal', the range is computed in relation to the extrema of the input data. If 'tozero'`, the range extends to 0, regardless of the input data If 'nonnegative', the range is non-negative, regardless of the input data. Applies only to linear axes. layout.xaxis.rangemode
xaxis.showticklabels boolean Determines whether or not the tick labels are drawn layout.xaxis.showticklabels
xaxis.tickangle number Sets the angle of the tick labels with respect to the horizontal. For example, a tickangle of -90 draws the tick labels vertically. layout.xaxis.tickangle
xaxis.tickfont Object Sets the tick font. We can define properties like: size, color, weight layout.xaxis.tickfont
xaxis.tickformat string Determines the format of the ticks (e.g., '.0%', '.2f') layout.xaxis.tickformat
xaxis.visible boolean Determines whether or not the x-axis is shown layout.xaxis.visible

Y-Axis

Control vertical axis appearance and behavior.

Property Type Description Plotly Mapping
yaxis.autorange boolean Automatically set the range based on data layout.yaxis.autorange
yaxis.nticks number Maximum number of ticks for the axis layout.yaxis.nticks
yaxis.rangemode string If 'normal', the range is computed in relation to the extrema of the input data. If 'tozero'`, the range extends to 0, regardless of the input data If 'nonnegative', the range is non-negative, regardless of the input data. Applies only to linear axes. layout.yaxis.rangemode
yaxis.showticklabels boolean Determines whether or not the tick labels are drawn layout.yaxis.showticklabels
yaxis.tickangle number Sets the angle of the tick labels with respect to the horizontal. For example, a tickangle of -90 draws the tick labels vertically. layout.yaxis.tickangle
yaxis.tickfont Object Sets the tick font. We can define properties like: size, color, weight layout.yaxis.tickfont
yaxis.visible boolean Determines whether or not the y-axis is shown layout.yaxis.visible

Series (Trace)

Control individual data series appearance.

Property Type Description Plotly Mapping
orientation string Whether to show vertical columns or horizontal bar trace.orientation
series.direction string Specifies the direction at which succeeding sectors follow one another. trace.direction
series.hole number Sets the fraction of the radius to cut out of the pie. Use this to make a donut chart. trace.hole
series.hoverinfo string Determines which trace information appear on hover. If none or skip are set, no information is displayed upon hovering. But, if none is set, click and hover events are still fired. trace.hoverinfo
series.insidetextorientation string Controls the orientation of the text inside chart sectors. When set to 'auto', text may be oriented in any direction in order to be as big as possible in the middle of a sector. The 'horizontal' option orients text to be parallel with the bottom of the chart, and may make text smaller in order to achieve that goal. The 'radial' option orients text along the radius of the sector. The 'tangential' option orients text perpendicular to the radius of the sector. trace.insidetextorientation
series.line Object Line styling properties including color, width, dash, etc. trace.line
series.marker Object Marker styling properties including color, size, line, etc. trace.marker
series.textinfo string Determines which trace information appear on the graph. trace.textinfo
textposition string Sets the positions of the text elements with respects to the (x,y) coordinates. trace.textposition

Other Plotly Properties

Property Type Description Plotly Mapping
barmode string How to display multiple bar series: 'group' for side-by-side, 'stack' for stacked, 'overlay' for overlapping, 'relative' for normalized to 100% layout.barmode
fontFamily string Font family layout.font.family
margin Object Sets all margins at once as an object. Alternative to setting margin.l, margin.r, margin.t, margin.b individually layout.margin
showlegend boolean Show legend in chart layout.showlegend
uniformtext.minsize number Sets the minimum text size between traces of the same type. layout.uniformtext.minsize
uniformtext.mode number Determines how the font size for various text elements are uniformed between each trace type. If the computed text sizes were smaller than the minimum size defined by uniformtext.minsize using 'hide' option hides the text; and using 'show' option shows the text without further downscaling. Please note that if the size defined by minsize is greater than the font size defined by trace, then the minsize is used. layout.uniformtext.mode

See PLOTLY-MAPPINGS.md for complete Plotly.js integration details

Chart-Specific Options

Properties specific to particular chart types.

Word Cloud

Property Type Description Values/Examples
drawOutOfBound boolean Whether to show words that would extend out of bounds false, true
maxFontSize number Size of most frequent word, in points
maxWords number Maximum number of words to show 3, 25, 40...
minFontSize number Show all words at least this size
scaleToMaxFontSize boolean Set size of most frequent word to value maxFontSize vs scale to fit margin false, true
shuffle boolean Whether to randomly shuffle positions on each render false, true

Verbatim/Text Display

Property Type Description Values/Examples
columnWidth number Set the width of the column 120.4, 123.85714285714286, 133...
enquote boolean false, true
maxRows number Maximum number of rows to display by default

Sankey Diagram

Property Type Description Values/Examples
nodePadding number
nodeWidth number

Paired Table

Property Type Description Values/Examples
columnWidth number Set the width of the column 120.4, 123.85714285714286, 133...
testPairedSamples boolean Test differences using paired samples (rather than independent samples) false, true

Root-Level Properties

These properties are used exclusively on the $root element to configure dataset-wide settings.

Most Common Root Properties

Property Type Description Values/Examples
precisionFreq number Precision setting for numeric display
toolbar string Toolbar configuration
nsymbol string Symbol for display formatting
showPairwise boolean Controls visibility/display at root level
view Object View configuration settings
nilSymbol string Symbol for display formatting
zeroSymbol string Symbol for display formatting
showPercentSymbol string Symbol for display formatting
loops number Number of loops/iterations
id string Identifier
minPercentSymbol string Symbol for display formatting
minPercent string

See ROOT-PROPERTIES.md for complete list of 36 root properties

Common Patterns

display

{
  "display": "",            // Default table
  "display": "compact",     // Compact table
  "display": "checkbox",    // Checkbox list
  "display": "stacked",     // Stacked bars
  "display": "independent"  // Independent percentages
}

orientation

{
  "chartOptions": {
    "orientation": "h",     // Horizontal bars
    "orientation": "v"      // Vertical columns
  }
}

barmode

{
  "chartOptions": {
    "barmode": "group",     // Side-by-side bars
    "barmode": "stack",     // Stacked bars
    "barmode": "overlay",   // Overlapping bars
    "barmode": "relative"   // Normalized to 100%
  }
}

Color Strategy

{
  "chartOptions": {
    "colorBy": "category",  // Color by category
    "colorBy": "series",    // Color by series
    "colorBy": "index",     // Color by index
    "colorBy": "none"       // No coloring
  }
}