Plots


Jump to API response

This endpoint handles manipulation of Plotly plot files.

Reference

Authorization


Any user with or without a Plotly account may view public plots. For private plots, see authentication.

Actions


list

Listing all public plots can be done via a GET request to this endpoint. By default, plots will be listed in order of date created. The order_by query parameter is accepted at this endpoint. Currently, only ordering by views is supported. It is possible to filter the plots by quality with min_quality or max_quality as query parameter.

Example:

// GET https://api.plot.ly/v2/plots/ ---> 200

// GET https://api.plot.ly/v2/plots/?order_by=-views ---> 200

// GET https://api.plot.ly/v2/plots/?min_quality=5 ---> 200

// GET https://api.plot.ly/v2/plots/?max_quality=5 ---> 200

feed

Listing all handpicked feed plots can be done via a GET request to this endpoint. By default, plots will be listed in a random order.

Example:

// GET https://api.plot.ly/v2/plots/feed ---> 200

create

You can create new plot resources here. The only required field is 'figure'. Currently, the figure is restricted to only contain references to grid data. That is, this will fail if raw data arrays are passed in. To create and manipulate underlying grids for plots, see the grids endpoint.

Example:

// This fails because a figure field is required.
// POST https://api.plot.ly/v2/plots ---> 400 Bad Request
{}

// This fails because the figure has raw data
//POST https://api.plot.ly/v2/plots ---> 400 Bad Request
{
    "figure": {"data": [{"y": ['this', 'is', 'raw', 'data']}]}
}

// This succeeds because the figure has src keys, not raw data.
//POST https://api.plot.ly/v2/plots ---> 200 OK
{
    "figure": {"data": [{"ysrc": "sven:88:u8nd62"}]}
}

When creating a grid, you can optionally specify a source_fid to specify where a plot has come from:

  • source_fid: the fid of a plot that was copied (and presumably edited) to produce this one

detail

There is a lot of meta information stored about plot files including filename, title, share_url, and content_url to name a few.

This information can only be reached with a GET to this endpoint.

Example:

// GET https://api.plot.ly/v2/plots/iheartgraphs:90

content

The contents of a plot can be downloaded via the content resource. The plot content contains referenced grid/column data by default. If you wish to return the raw grid/column data, the inline_data=true query must be included in the request url. The Content-Type header will be appropriately set for the response body.

Alternatively, you can set ?map_data=unreadable to append a mapping of sources to data that belongs to grids which are unreadable for the requestor. This is useful when you have read access to another users plot, but that plot contains grid references which you don't have access to.

Examples:

// Returns referenced grid/column data
// GET https://api.plot.ly/v2/plots/iheartgraphs:90/content ---> 200 OK

// Returns full grid/column data
// GET https://api.plot.ly/v2/plots/iheartgraphs:90/content?inline_data=true ---> 200 OK

// Returns full grid/column data when requestor doesn't have permission
// to read the referenced grid.
// GET https://api.plot.ly/v2/plots/iheartgraphs:90/content?map_data=unreadable ---> 200 OK

GET /v2/plots/andrew.j.stephens:4
HTTP 200 OK
Allow: GET, PUT, PATCH, DELETE, HEAD, OPTIONS
Content-Type: application/json
Vary: Accept

{
    "creation_time": "2019-03-21T03:17:26.585418Z",
    "comments": {
        "results": [],
        "count": 0
    },
    "parented": true,
    "embed_url": "https://plot.ly/~andrew.j.stephens/4.embed",
    "fid": "andrew.j.stephens:4",
    "filename": "Plot 4",
    "filetype": "plot",
    "img_url": "https://storage.googleapis.com/plotly-prod-images/andrew.j.stephens/4/9_8VKZMK28DFF0RFA1ARBQ1ZVF3ETMHA.png",
    "image_urls": {
        "default": "https://storage.googleapis.com/plotly-prod-images/andrew.j.stephens/4/2_S8ZUZZNFVP8WEHM3A6QJI6ZOQKC1ST.png",
        "block-thumb": "https://storage.googleapis.com/plotly-prod-images/andrew.j.stephens/4/8_V5WA2S0PGV51TULOM7WVLAF4WBIDMN.png",
        "list-thumb": "https://storage.googleapis.com/plotly-prod-images/andrew.j.stephens/4/9_8VKZMK28DFF0RFA1ARBQ1ZVF3ETMHA.png"
    },
    "api_urls": {
        "files": "https://api.plot.ly/v2/files/andrew.j.stephens:4",
        "plots": "https://api.plot.ly/v2/plots/andrew.j.stephens:4",
        "parent": "https://api.plot.ly/v2/folders/home?user=andrew.j.stephens"
    },
    "owner": "andrew.j.stephens",
    "parent": -1,
    "preview": "",
    "referencers": [],
    "references": [],
    "title": "",
    "views": 1,
    "web_url": "https://plot.ly/~andrew.j.stephens/4/",
    "world_readable": true,
    "date_modified": "2019-03-21T03:17:26.604Z",
    "stars": {
        "results": [],
        "count": 0
    },
    "collaborators": {
        "results": [],
        "count": 0
    },
    "subfolder_count": null,
    "refresh_interval": null,
    "organize_view_url": "https://plot.ly/~andrew.j.stephens/4/",
    "current_user_permission": "read",
    "is_theme": null,
    "is_template": false,
    "autosize": true,
    "caption": "",
    "figure": {
        "data": [
            {
                "mode": "lines",
                "type": "scatter",
                "xsrc": "andrew.j.stephens:3:69f3c9",
                "ysrc": "andrew.j.stephens:3:a0d68e"
            }
        ],
        "frames": [],
        "layout": {
            "title": {
                "text": "Bar Voltage vs Distance"
            },
            "xaxis": {
                "type": "linear",
                "range": [
                    0.05,
                    0.23
                ],
                "title": {
                    "text": "Distance (M)"
                },
                "autorange": true
            },
            "yaxis": {
                "type": "linear",
                "range": [
                    0.26861111111111113,
                    5.3563888888888895
                ],
                "title": {
                    "text": "Voltage (V)"
                },
                "autorange": true
            },
            "autosize": true,
            "template": {
                "data": {
                    "bar": [
                        {
                            "type": "bar",
                            "marker": {
                                "colorbar": {
                                    "ticks": "",
                                    "outlinewidth": 0
                                }
                            }
                        }
                    ],
                    "table": [
                        {
                            "type": "table",
                            "cells": {
                                "fill": {
                                    "color": "#EBF0F8"
                                },
                                "line": {
                                    "color": "white"
                                }
                            },
                            "header": {
                                "fill": {
                                    "color": "#C8D4E3"
                                },
                                "line": {
                                    "color": "white"
                                }
                            }
                        }
                    ],
                    "carpet": [
                        {
                            "type": "carpet",
                            "aaxis": {
                                "gridcolor": "#C8D4E3",
                                "linecolor": "#C8D4E3",
                                "endlinecolor": "#2a3f5f",
                                "minorgridcolor": "#C8D4E3",
                                "startlinecolor": "#2a3f5f"
                            },
                            "baxis": {
                                "gridcolor": "#C8D4E3",
                                "linecolor": "#C8D4E3",
                                "endlinecolor": "#2a3f5f",
                                "minorgridcolor": "#C8D4E3",
                                "startlinecolor": "#2a3f5f"
                            }
                        }
                    ],
                    "mesh3d": [
                        {
                            "type": "mesh3d",
                            "colorbar": {
                                "ticks": "",
                                "outlinewidth": 0
                            }
                        }
                    ],
                    "contour": [
                        {
                            "type": "contour",
                            "colorbar": {
                                "ticks": "",
                                "outlinewidth": 0
                            },
                            "autocolorscale": true
                        }
                    ],
                    "heatmap": [
                        {
                            "type": "heatmap",
                            "colorbar": {
                                "ticks": "",
                                "outlinewidth": 0
                            },
                            "autocolorscale": true
                        }
                    ],
                    "scatter": [
                        {
                            "type": "scatter",
                            "marker": {
                                "colorbar": {
                                    "ticks": "",
                                    "outlinewidth": 0
                                }
                            }
                        }
                    ],
                    "surface": [
                        {
                            "type": "surface",
                            "colorbar": {
                                "ticks": "",
                                "outlinewidth": 0
                            }
                        }
                    ],
                    "heatmapgl": [
                        {
                            "type": "heatmapgl",
                            "colorbar": {
                                "ticks": "",
                                "outlinewidth": 0
                            }
                        }
                    ],
                    "histogram": [
                        {
                            "type": "histogram",
                            "marker": {
                                "colorbar": {
                                    "ticks": "",
                                    "outlinewidth": 0
                                }
                            }
                        }
                    ],
                    "parcoords": [
                        {
                            "line": {
                                "colorbar": {
                                    "ticks": "",
                                    "outlinewidth": 0
                                }
                            },
                            "type": "parcoords"
                        }
                    ],
                    "scatter3d": [
                        {
                            "type": "scatter3d",
                            "marker": {
                                "colorbar": {
                                    "ticks": "",
                                    "outlinewidth": 0
                                }
                            }
                        }
                    ],
                    "scattergl": [
                        {
                            "type": "scattergl",
                            "marker": {
                                "colorbar": {
                                    "ticks": "",
                                    "outlinewidth": 0
                                }
                            }
                        }
                    ],
                    "choropleth": [
                        {
                            "type": "choropleth",
                            "colorbar": {
                                "ticks": "",
                                "outlinewidth": 0
                            }
                        }
                    ],
                    "scattergeo": [
                        {
                            "type": "scattergeo",
                            "marker": {
                                "colorbar": {
                                    "ticks": "",
                                    "outlinewidth": 0
                                }
                            }
                        }
                    ],
                    "histogram2d": [
                        {
                            "type": "histogram2d",
                            "colorbar": {
                                "ticks": "",
                                "outlinewidth": 0
                            },
                            "autocolorscale": true
                        }
                    ],
                    "scatterpolar": [
                        {
                            "type": "scatterpolar",
                            "marker": {
                                "colorbar": {
                                    "ticks": "",
                                    "outlinewidth": 0
                                }
                            }
                        }
                    ],
                    "contourcarpet": [
                        {
                            "type": "contourcarpet",
                            "colorbar": {
                                "ticks": "",
                                "outlinewidth": 0
                            }
                        }
                    ],
                    "scattercarpet": [
                        {
                            "type": "scattercarpet",
                            "marker": {
                                "colorbar": {
                                    "ticks": "",
                                    "outlinewidth": 0
                                }
                            }
                        }
                    ],
                    "scattermapbox": [
                        {
                            "type": "scattermapbox",
                            "marker": {
                                "colorbar": {
                                    "ticks": "",
                                    "outlinewidth": 0
                                }
                            }
                        }
                    ],
                    "scatterpolargl": [
                        {
                            "type": "scatterpolargl",
                            "marker": {
                                "colorbar": {
                                    "ticks": "",
                                    "outlinewidth": 0
                                }
                            }
                        }
                    ],
                    "scatterternary": [
                        {
                            "type": "scatterternary",
                            "marker": {
                                "colorbar": {
                                    "ticks": "",
                                    "outlinewidth": 0
                                }
                            }
                        }
                    ],
                    "histogram2dcontour": [
                        {
                            "type": "histogram2dcontour",
                            "colorbar": {
                                "ticks": "",
                                "outlinewidth": 0
                            },
                            "autocolorscale": true
                        }
                    ]
                },
                "layout": {
                    "geo": {
                        "bgcolor": "white",
                        "showland": true,
                        "lakecolor": "white",
                        "landcolor": "white",
                        "showlakes": true,
                        "subunitcolor": "#C8D4E3"
                    },
                    "font": {
                        "color": "#2a3f5f"
                    },
                    "polar": {
                        "bgcolor": "white",
                        "radialaxis": {
                            "ticks": "",
                            "gridcolor": "#EBF0F8",
                            "linecolor": "#EBF0F8"
                        },
                        "angularaxis": {
                            "ticks": "",
                            "gridcolor": "#EBF0F8",
                            "linecolor": "#EBF0F8"
                        }
                    },
                    "scene": {
                        "xaxis": {
                            "ticks": "",
                            "gridcolor": "#DFE8F3",
                            "gridwidth": 2,
                            "linecolor": "#EBF0F8",
                            "zerolinecolor": "#EBF0F8",
                            "showbackground": true,
                            "backgroundcolor": "white"
                        },
                        "yaxis": {
                            "ticks": "",
                            "gridcolor": "#DFE8F3",
                            "gridwidth": 2,
                            "linecolor": "#EBF0F8",
                            "zerolinecolor": "#EBF0F8",
                            "showbackground": true,
                            "backgroundcolor": "white"
                        },
                        "zaxis": {
                            "ticks": "",
                            "gridcolor": "#DFE8F3",
                            "gridwidth": 2,
                            "linecolor": "#EBF0F8",
                            "zerolinecolor": "#EBF0F8",
                            "showbackground": true,
                            "backgroundcolor": "white"
                        }
                    },
                    "title": {
                        "x": 0.05
                    },
                    "xaxis": {
                        "ticks": "",
                        "gridcolor": "#EBF0F8",
                        "linecolor": "#EBF0F8",
                        "automargin": true,
                        "zerolinecolor": "#EBF0F8",
                        "zerolinewidth": 2
                    },
                    "yaxis": {
                        "ticks": "",
                        "gridcolor": "#EBF0F8",
                        "linecolor": "#EBF0F8",
                        "automargin": true,
                        "zerolinecolor": "#EBF0F8",
                        "zerolinewidth": 2
                    },
                    "ternary": {
                        "aaxis": {
                            "ticks": "",
                            "gridcolor": "#DFE8F3",
                            "linecolor": "#A2B1C6"
                        },
                        "baxis": {
                            "ticks": "",
                            "gridcolor": "#DFE8F3",
                            "linecolor": "#A2B1C6"
                        },
                        "caxis": {
                            "ticks": "",
                            "gridcolor": "#DFE8F3",
                            "linecolor": "#A2B1C6"
                        },
                        "bgcolor": "white"
                    },
                    "colorway": [
                        "#636efa",
                        "#EF553B",
                        "#00cc96",
                        "#ab63fa",
                        "#19d3f3",
                        "#e763fa",
                        "#fecb52",
                        "#ffa15a",
                        "#ff6692",
                        "#b6e880"
                    ],
                    "hovermode": "closest",
                    "colorscale": {
                        "diverging": [
                            [
                                0,
                                "#8e0152"
                            ],
                            [
                                0.1,
                                "#c51b7d"
                            ],
                            [
                                0.2,
                                "#de77ae"
                            ],
                            [
                                0.3,
                                "#f1b6da"
                            ],
                            [
                                0.4,
                                "#fde0ef"
                            ],
                            [
                                0.5,
                                "#f7f7f7"
                            ],
                            [
                                0.6,
                                "#e6f5d0"
                            ],
                            [
                                0.7,
                                "#b8e186"
                            ],
                            [
                                0.8,
                                "#7fbc41"
                            ],
                            [
                                0.9,
                                "#4d9221"
                            ],
                            [
                                1,
                                "#276419"
                            ]
                        ],
                        "sequential": [
                            [
                                0,
                                "#0508b8"
                            ],
                            [
                                0.0893854748603352,
                                "#1910d8"
                            ],
                            [
                                0.1787709497206704,
                                "#3c19f0"
                            ],
                            [
                                0.2681564245810056,
                                "#6b1cfb"
                            ],
                            [
                                0.3575418994413408,
                                "#981cfd"
                            ],
                            [
                                0.44692737430167595,
                                "#bf1cfd"
                            ],
                            [
                                0.5363128491620112,
                                "#dd2bfd"
                            ],
                            [
                                0.6256983240223464,
                                "#f246fe"
                            ],
                            [
                                0.7150837988826816,
                                "#fc67fd"
                            ],
                            [
                                0.8044692737430168,
                                "#fe88fc"
                            ],
                            [
                                0.8938547486033519,
                                "#fea5fd"
                            ],
                            [
                                0.9832402234636871,
                                "#febefe"
                            ],
                            [
                                1,
                                "#fec3fe"
                            ]
                        ],
                        "sequentialminus": [
                            [
                                0,
                                "#0508b8"
                            ],
                            [
                                0.0893854748603352,
                                "#1910d8"
                            ],
                            [
                                0.1787709497206704,
                                "#3c19f0"
                            ],
                            [
                                0.2681564245810056,
                                "#6b1cfb"
                            ],
                            [
                                0.3575418994413408,
                                "#981cfd"
                            ],
                            [
                                0.44692737430167595,
                                "#bf1cfd"
                            ],
                            [
                                0.5363128491620112,
                                "#dd2bfd"
                            ],
                            [
                                0.6256983240223464,
                                "#f246fe"
                            ],
                            [
                                0.7150837988826816,
                                "#fc67fd"
                            ],
                            [
                                0.8044692737430168,
                                "#fe88fc"
                            ],
                            [
                                0.8938547486033519,
                                "#fea5fd"
                            ],
                            [
                                0.9832402234636871,
                                "#febefe"
                            ],
                            [
                                1,
                                "#fec3fe"
                            ]
                        ]
                    },
                    "plot_bgcolor": "white",
                    "paper_bgcolor": "white",
                    "shapedefaults": {
                        "line": {
                            "width": 0
                        },
                        "opacity": 0.4,
                        "fillcolor": "#506784"
                    },
                    "annotationdefaults": {
                        "arrowhead": 0,
                        "arrowcolor": "#506784",
                        "arrowwidth": 1
                    }
                },
                "themeRef": "PLOTLY_WHITE"
            }
        }
    },
    "height": null,
    "width": null,
    "user": {
        "profile_url": "https://plot.ly/~andrew.j.stephens",
        "avatar_url": "https://storage.googleapis.com/plotly-prod-profiles/39.jpg",
        "background_url": "https://storage.googleapis.com/plotly-prod-profiles/bg-2.jpg",
        "bio": "",
        "nickname": "",
        "website": "",
        "stream_tokens": null,
        "feature_set_id": null,
        "csrf_token": null,
        "date_joined": "2019-03-20 18:49:12",
        "mapbox_access_tokens": null,
        "has_password": null,
        "username": "andrew.j.stephens",
        "email": null,
        "is_active": null,
        "readonly": null
    }
}