Col
Grids
Grids are the core of Plotly's data API. A plot's traces reference underlying grid data. This endpoint allows API creation and manipulation of grids.
Reference
Authorization
Any user with or without a Plotly account may view public grid files. For private files, see authentication.
Grid Meta Information
The grid meta information extends the file meta information with the following fields:
write-only fields:
dataonly accessible from the create endpoint
read-write fields:
Actions
create
To create a grid, POST to this endpoint with any of the writable grid fields included
in the body of the request. The only required field is data.
The data field takes the following form:
{
"cols":
{
"first column": {"data": ["a", "b", "c"], "order": 0},
"second column": {"data": [1, 2, 3], "order": 1}
}
}
Note: each column of the cols field is a key-value pair with the key
corresponding to the column header name and the value corresponding to an
object specifying the column's order and data.
Example:
// POST https://api.plotly.com/v2/grids --> 201 Created
{
"data": {"cols": {"first": {"data": [1,2,3], "order": 0}}}
}
// POST https://api.plotly.com/v2/grids --> 201 Created
{
"data": "{\"cols\": {\"first\": {\"data\": [1,2,3], \"order\": 0}}}",
"parent": 932,
"filename": "new grid"
}
Note: the integer associated with the parent field corresponds to a
file with idlocal 932. This file
must have filetype fold for a sucessful POST.
When creating a grid, you can optionally specify source fields to indicate where a grid has come from:
-
source_fid: the fid of a grid that was copied (and presumably edited) to produce this one
-
source_url: the URL this grid was imported from
-
source_referer: if source_url is given, you can optionally add this field to give the URL of an index page where the source_url link appears. (This could give more information about the data, or present it in alternate formats.)
upload
A raw file may be uploaded by making a POST request to the upload endpoint.
This will create a new grid for a single 2D data source, or a folder
containing multiple grids when there are multiple data sources (e.g.
a spreadsheet with many tabs, or a zip archive). To determine which
type of file has been created, check the filetype key in the response,
which will either be grid or fold.
The following options may be passed as HTTP headers to control the upload.
-
X-File-Name: gives the filename of the file being uploaded. The extension is used as a first guess of the file type for parsing and will be used as the created filename if possible.
-
Plotly-World-Readable: controls the visibility of the created grid or folder. May be
trueorfalse. Defaults tofalse. -
Plotly-Parent: gives the parent folder id, like for create.
-
Plotly-Parent-Path: gives the path to the parent folder, like for create.
row
The row endpoint allows you to append existing grids with new information. This endpoint requires a POST and returns a 201 Created response on success.
Examples:
// POST https://api.plotly.com/v2/grids/henreitta:88/row --> 201 Created
// Add three rows to the existing grid with fid henrietta:88
{
"rows": [[1, 0.5], [2, 0.1], [3, 0.7]]
}
col
The col endpoint allows you to retrieve existing columns of a grid via a
GET request, completely replace existing columns of a grid via a
PUT request, or append existing grids with full columns of new data via
a POST request. Both the GET and PUT requests require the existing
columns to be specified via a uid query (see examples below) and return a
200 OK response on success. The data, name and order fields of a column
can be updated via a PUT request. The POST request does not take a column
query and returns a 201 Created response on success.
Example GET:
// GET https://api.plotly.com/v2/grids/henreitta:88/col?uid=some_uid --> 200 OK
// Retrieve a column with uid "some_uid"
// GET https://api.plotly.com/v2/grids/henreitta:88/col?uid=some_uid,some_other_uid --> 200 OK
// Retrieve multiple columns with uids "some_uid" and "some_other_uid"
// GET https://api.plotly.com/v2/grids/henreitta:88/col?uid=not_contained_in_grid --> 400 Bad Request
// Attempt to retrieve a column not contained in grid
Example PUT:
// PUT https://api.plotly.com/v2/grids/henreitta:88/col?uid=some_uid --> 200 OK
// Replace a column with uid "some_uid"
{
"cols": "[{\"data\": [0, 1], \"name\": \"new name\"}]"
}
// PUT https://api.plotly.com/v2/grids/henreitta:88/col?uid=some_uid,some_other_uid --> 200 OK
// Replace multiple columns with uids "some_uid" and "some_other_uid"
{
"cols": "[{\"data\": [0, 1], \"order\": 0}, {\"data\": [\"a\", \"b\"]}]"
}
// PUT https://api.plotly.com/v2/grids/henreitta:88/col?uid=not_contained_in_grid --> 400 Bad Request
// Attempt to replace a column not contained in grid
{
"cols": "[{\"data\": [0, 1]}]"
}
// PUT https://api.plotly.com/v2/grids/henreitta:88/col?uid=only_one_uid_specified --> 400 Bad Request
// Attempt to update a column with multiple columns of data
{
"cols": "[{\"data\": [0, 1]}, {\"data\": [\"a\", \"b\"]}]"
}
Note: The data to be updated via a PUT request will respect the order
of the columns specified by the uids of the query.
Example POST:
// POST https://api.plotly.com/v2/grids/henreitta:88/col --> 400 Bad Request
// Add two columns
{
"cols": [{"name": "col name 1", "data": [0, 1]}, {"name": "col name 2", "data": [9, 9]}]
}
// POST https://api.plotly.com/v2/grids/henreitta:88/col --> 201 Created
// Add two columns
{
"cols": "[{\"name\": \"col name 1\", \"data\": [0, 1]}, {\"name\": \"col name 2\", \"data\": [9, 9]}]"
}
retrieve
The grid meta information can be retrieved by making a GET request to the grids endpoint.
Example:
// GET https://api.plotly.com/v2/grids/henrietta:88
content
The contents of a grid can be downloaded via a GET request to the content resource. The Content-Type header will be appropriately set for the response body.
Example:
// GET https://api.plotly.com/v2/grids/henrietta:88/content
destroy
To delete an grid, make a DELETE request to the grids endpoint and include the fid for the grid file. A successful response will have a status code of 204 No Content.
Example:
// DELETE https://api.plotly.com/v2/grids/henrietta:88 --> 204 No Content
partial update
To update the writable meta information of an existing grid, you make a PATCH request to the grids endpoint and include the fid for the grid file. A successful response will have a status code of 200 OK.
Example:
// PATCH https://api.plotly.com/v2/grids/henrietta:88 --> 200 OK
{
"metadata": "{\"content\": \"copy copy copy copy copy\"}",
"filename": "my new and unique grid name",
"parent": 123
}
update
To completely replace the writable meta information of an existing grid, you make a PUT request to the grids endpoint and include the fid for the grid file. A successful response will have a status code of 200 OK.
Example:
// PUT https://api.plotly.com/v2/grids/henrietta:88 --> 200 OK
{
"parent": -1,
"world_readable": true,
"filename": "my new and unique grid name"
"metadata": "{\"content\": \"copy copy copy copy copy\"}",
}
drop reference
Grids may reference other files in Plotly called extras. Because extras may be referenced from many files, instead of deleting them to remove them, you may just dereference them via a POST request to this endpoint. This is a safer approach and is used to manage extras in the Plotly webapp. A successful response will have a status code of 200 OK.
Example:
// POST https://api.plotly.com/v2/grids/henrietta:88/drop_reference --> 200 OK
{
"fid": "henrietta:99"
}
trash
A POST request to this endpoint allows for the recoverable trashing of the grid specified in the detail. A successful response will have a status code of 200 OK.
Example:
// POST https://api.plotly.com/v2/grids/henrietta:88/trash ---> 200 OK
Note: This request is idempotent. Trashing a folder that is already trashed will also succeed and return 200 OK.
restore
This endpoint allows for a trashed grid to be restored via a POST request. Only the owner of the grid has permission to restore that grid. A successful restore response will have a status code of 200 OK.
Example:
// POST https://api.plotly.com/v2/grids/henrietta:88/restore ---> 200
Note: This request is idempotent. Restoring a grid that is not yet trashed will also succeed and return 200 OK.
permanent delete
A DELETE request to this endpoint allows for the permanent deletion of the grid specified in the endpoint detail. A successful response will have a status code of 204 No Content.
Example:
// DELETE https://api.plotly.com/v2/grids/plotlvr:9/permanent_delete ---> 204 No Content
lookup
Get a grid using its path and parent instead of using its
fid. If the parent is not specified,
it's assumed to be a user's home folder. The path given is assumed to
be relative to the parent.
By default, the user making the request is assumed to be the owner of the
file being found. However, this is controlled via the user query param.
query params
Only the path param is required.
- path (required) The '/'-delimited path specifying the grid location.
- parent (optional) The parent id, an integer, which the path is relative to.
- user (optional) The username of the owner of the file.
Examples:
// GET https://api.plotly.com/v2/grids/lookup?path=my_folder/my_file ---> 200 OK
// GET https://api.plotly.com/v2/grids/lookup?parent=200&path=my_file ---> 200 OK
// GET https://api.plotly.com/v2/grids/lookup?user=wonderwoman&path=her_folder/her_file ---> 200 OK
// GET https://api.plotly.com/v2/grids/lookup?user=wonderwoman&parent=22&path=her_file ---> 200 OK
GET /v2/grids/RPlotBot:5612/col?format=api
{
"cols": [
{
"uid": "3b8db5",
"data": [
1390.63,
13.31,
1463.17,
3586.02,
16472.88,
1851.33,
259.62,
282.19,
3764.09,
2860.84,
401.84,
2078.89,
8709.48,
5050.23,
11273.76,
4589.01,
1889.15,
1914.23,
278.37,
692.75,
248.65,
3164.16,
7192.33,
2170.8,
3933.42,
1718,
7114.13,
139.89,
73.06,
500.4,
751.58,
1488.9,
3806.05,
3761.96,
3979.79,
1646.41,
1794.57,
1969.87,
31.59,
929.93,
3770.19,
1535.13,
6648.22,
453.39,
180.14,
1146.48,
3894.81,
138.89,
3090.23,
349.69
],
"order": 0,
"name": "data.1.z"
},
{
"uid": "40c8ac",
"data": [
"Alabama <br> Beef 34.4 Dairy 4.06 <br> Fruits 25.11 Veggies 14.33 <br> Wheat 70 Corn 34.9",
"Alaska <br> Beef 0.2 Dairy 0.19 <br> Fruits 0 Veggies 1.56 <br> Wheat 0 Corn 0",
"Arizona <br> Beef 71.3 Dairy 105.48 <br> Fruits 60.27 Veggies 386.91 <br> Wheat 48.7 Corn 7.3",
"Arkansas <br> Beef 53.2 Dairy 3.53 <br> Fruits 6.88 Veggies 11.45 <br> Wheat 114.5 Corn 69.5",
"California <br> Beef 228.7 Dairy 929.95 <br> Fruits 8736.4 Veggies 2106.79 <br> Wheat 249.3 Corn 34.6",
"Colorado <br> Beef 261.4 Dairy 71.94 <br> Fruits 17.99 Veggies 118.27 <br> Wheat 400.5 Corn 183.2",
"Connecticut <br> Beef 1.1 Dairy 9.49 <br> Fruits 13.1 Veggies 11.16 <br> Wheat 0 Corn 0",
"Delaware <br> Beef 0.4 Dairy 2.3 <br> Fruits 1.53 Veggies 20.03 <br> Wheat 22.9 Corn 26.9",
"Florida <br> Beef 42.6 Dairy 66.31 <br> Fruits 1371.36 Veggies 450.86 <br> Wheat 1.8 Corn 3.5",
"Georgia <br> Beef 31 Dairy 38.38 <br> Fruits 233.51 Veggies 154.77 <br> Wheat 65.4 Corn 57.8",
"Hawaii <br> Beef 4 Dairy 1.16 <br> Fruits 55.51 Veggies 24.83 <br> Wheat 0 Corn 0",
"Idaho <br> Beef 119.8 Dairy 294.6 <br> Fruits 21.64 Veggies 319.19 <br> Wheat 568.2 Corn 24",
"Illinois <br> Beef 53.7 Dairy 45.82 <br> Fruits 12.53 Veggies 39.95 <br> Wheat 223.8 Corn 2228.5",
"Indiana <br> Beef 21.9 Dairy 89.7 <br> Fruits 12.98 Veggies 37.89 <br> Wheat 114 Corn 1123.2",
"Iowa <br> Beef 289.8 Dairy 107 <br> Fruits 3.24 Veggies 7.1 <br> Wheat 3.1 Corn 2529.8",
"Kansas <br> Beef 659.3 Dairy 65.45 <br> Fruits 3.11 Veggies 9.32 <br> Wheat 1426.5 Corn 457.3",
"Kentucky <br> Beef 54.8 Dairy 28.27 <br> Fruits 6.6 Veggies 0 <br> Wheat 149.3 Corn 179.1",
"Louisiana <br> Beef 19.8 Dairy 6.02 <br> Fruits 17.83 Veggies 17.25 <br> Wheat 78.7 Corn 91.4",
"Maine <br> Beef 1.4 Dairy 16.18 <br> Fruits 52.01 Veggies 62.9 <br> Wheat 0 Corn 0",
"Maryland <br> Beef 5.6 Dairy 24.81 <br> Fruits 12.9 Veggies 20.43 <br> Wheat 55.8 Corn 54.1",
"Massachusetts <br> Beef 0.6 Dairy 5.81 <br> Fruits 80.83 Veggies 21.13 <br> Wheat 0 Corn 0",
"Michigan <br> Beef 37.7 Dairy 214.82 <br> Fruits 257.69 Veggies 189.96 <br> Wheat 247 Corn 381.5",
"Minnesota <br> Beef 112.3 Dairy 218.05 <br> Fruits 7.91 Veggies 120.37 <br> Wheat 538.1 Corn 1264.3",
"Mississippi <br> Beef 12.8 Dairy 5.45 <br> Fruits 17.04 Veggies 27.87 <br> Wheat 102.2 Corn 110",
"Missouri <br> Beef 137.2 Dairy 34.26 <br> Fruits 13.18 Veggies 17.9 <br> Wheat 161.7 Corn 428.8",
"Montana <br> Beef 105 Dairy 6.82 <br> Fruits 3.3 Veggies 45.27 <br> Wheat 1198.1 Corn 5.4",
"Nebraska <br> Beef 762.2 Dairy 30.07 <br> Fruits 2.16 Veggies 53.5 <br> Wheat 292.3 Corn 1735.9",
"Nevada <br> Beef 21.8 Dairy 16.57 <br> Fruits 1.19 Veggies 27.93 <br> Wheat 5.4 Corn 0",
"New Hampshire <br> Beef 0.6 Dairy 7.46 <br> Fruits 7.98 Veggies 4.5 <br> Wheat 0 Corn 0",
"New Jersey <br> Beef 0.8 Dairy 3.37 <br> Fruits 109.45 Veggies 56.54 <br> Wheat 6.7 Corn 10.1",
"New Mexico <br> Beef 117.2 Dairy 191.01 <br> Fruits 101.9 Veggies 43.88 <br> Wheat 13.9 Corn 11.2",
"New York <br> Beef 22.2 Dairy 331.8 <br> Fruits 202.56 Veggies 143.37 <br> Wheat 29.9 Corn 106.1",
"North Carolina <br> Beef 24.8 Dairy 24.9 <br> Fruits 74.47 Veggies 150.45 <br> Wheat 200.3 Corn 92.2",
"North Dakota <br> Beef 78.5 Dairy 8.14 <br> Fruits 0.25 Veggies 130.79 <br> Wheat 1664.5 Corn 236.1",
"Ohio <br> Beef 36.2 Dairy 134.57 <br> Fruits 27.21 Veggies 53.53 <br> Wheat 207.4 Corn 535.1",
"Oklahoma <br> Beef 337.6 Dairy 24.35 <br> Fruits 9.24 Veggies 8.9 <br> Wheat 324.8 Corn 27.5",
"Oregon <br> Beef 58.8 Dairy 63.66 <br> Fruits 315.04 Veggies 126.5 <br> Wheat 320.3 Corn 11.7",
"Pennsylvania <br> Beef 50.9 Dairy 280.87 <br> Fruits 89.48 Veggies 38.26 <br> Wheat 41 Corn 112.1",
"Rhode Island <br> Beef 0.1 Dairy 0.52 <br> Fruits 2.83 Veggies 3.02 <br> Wheat 0 Corn 0",
"South Carolina <br> Beef 15.2 Dairy 7.62 <br> Fruits 53.45 Veggies 42.66 <br> Wheat 55.3 Corn 32.1",
"South Dakota <br> Beef 193.5 Dairy 46.77 <br> Fruits 0.8 Veggies 4.06 <br> Wheat 704.5 Corn 643.6",
"Tennessee <br> Beef 51.1 Dairy 21.18 <br> Fruits 6.23 Veggies 24.67 <br> Wheat 100 Corn 88.8",
"Texas <br> Beef 961 Dairy 240.55 <br> Fruits 99.9 Veggies 115.23 <br> Wheat 309.7 Corn 167.2",
"Utah <br> Beef 27.9 Dairy 48.6 <br> Fruits 12.34 Veggies 6.6 <br> Wheat 42.8 Corn 5.3",
"Vermont <br> Beef 6.2 Dairy 65.98 <br> Fruits 8.01 Veggies 4.05 <br> Wheat 0 Corn 0",
"Virginia <br> Beef 39.5 Dairy 47.85 <br> Fruits 36.48 Veggies 27.25 <br> Wheat 77.5 Corn 39.5",
"Washington <br> Beef 59.2 Dairy 154.18 <br> Fruits 1738.57 Veggies 363.79 <br> Wheat 786.3 Corn 29.5",
"West Virginia <br> Beef 12 Dairy 3.9 <br> Fruits 11.54 Veggies 0 <br> Wheat 1.6 Corn 3.5",
"Wisconsin <br> Beef 107.3 Dairy 633.6 <br> Fruits 133.8 Veggies 148.99 <br> Wheat 96.7 Corn 460.5",
"Wyoming <br> Beef 75.1 Dairy 2.89 <br> Fruits 0.17 Veggies 10.23 <br> Wheat 20.7 Corn 9"
],
"order": 1,
"name": "data.1.text"
},
{
"uid": "c744f5",
"data": [
"AL",
"AK",
"AZ",
"AR",
"CA",
"CO",
"CT",
"DE",
"FL",
"GA",
"HI",
"ID",
"IL",
"IN",
"IA",
"KS",
"KY",
"LA",
"ME",
"MD",
"MA",
"MI",
"MN",
"MS",
"MO",
"MT",
"NE",
"NV",
"NH",
"NJ",
"NM",
"NY",
"NC",
"ND",
"OH",
"OK",
"OR",
"PA",
"RI",
"SC",
"SD",
"TN",
"TX",
"UT",
"VT",
"VA",
"WA",
"WV",
"WI",
"WY"
],
"order": 2,
"name": "data.1.locations"
},
{
"uid": "9202df",
"data": [
1390.63,
13.31,
1463.17,
3586.02,
16472.88,
1851.33,
259.62,
282.19,
3764.09,
2860.84,
401.84,
2078.89,
8709.48,
5050.23,
11273.76,
4589.01,
1889.15,
1914.23,
278.37,
692.75,
248.65,
3164.16,
7192.33,
2170.8,
3933.42,
1718,
7114.13,
139.89,
73.06,
500.4,
751.58,
1488.9,
3806.05,
3761.96,
3979.79,
1646.41,
1794.57,
1969.87,
31.59,
929.93,
3770.19,
1535.13,
6648.22,
453.39,
180.14,
1146.48,
3894.81,
138.89,
3090.23,
349.69
],
"order": 3,
"name": "data.1.marker.line.color"
}
]
}