Tables/States/Read
The states feature allows read access to grid states saved in the factual.com interface with filters, column orders, sorts and other settings already applied. They serve as a convenient option to save fixed customizations to a table and apply them to all results. Many of these options can then be overridden with additional parameters but serve as a customized starting point.
Requires a state key in the STATE_KEY position of request url.
| Parameter |
Description |
Requirements |
Examples |
Default |
| limit |
the number of rows to return |
integer value |
10 |
200 |
| offset |
the number of rows to skip in the result
|
integer value |
200 |
0 |
| sort_by |
a single value or an array of up to two of the following:
- column ordinal(s)
- column id(s)
- column name(s)
|
one or two of column ordinal (integer), field id (integer), or field name |
sort_by=0
sort_by=[0,1]
sort_by=1234
sort_by=[1234,12345]
sort_by=LastName
sort_by=[LastName,FirstName]
|
sorted by subject |
| sort_dir |
the direction of the sort - ascending or descending |
asc or desc |
asc
[asc.desc]
|
asc when single value
[asc,asc] when array |
| subject |
subject value(s) to retrieve a single row by primary key labels |
value or list of values that covers a single subject (primary key) |
"Apple Inc." (in a list of companies)
["McDonalds","123 Main St."] (in a list of restaurants)
|
|
| subject_key |
the unique identifier for a specific row |
string value (a row key) |
MttWppUhxVjrV6Bo9ASlBIf3obc |
|
| filters |
row and or vote filters constructed to limit results |
JSON encoded filters object |
See filter examples. |
|
| suppress_subject_key |
excludes row key from results |
boolean |
true
false
|
false |
Result Payload
| Payload Field |
Description |
Examples |
| fields |
array of field names |
|
| data |
array of rows, each of which is an array of cell values |
[
['a','b','c']
['e','f','g']
]
|
| subject_columns |
array of ordinals representing column(s) that make up the subject (primary key) of the table (the row key can always be used to identify a row, but it can also be identified by subject label) |
[1] |
| rows |
integer value of rows contained in the data object |
200 |
| total_rows |
integer value of total rows available in the table (with the given filter) |
409643
|
