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/fibi:13
HTTP 200 OK
Allow: GET, PUT, PATCH, DELETE, HEAD, OPTIONS
Content-Type: application/json
Vary: Accept

{
    "creation_time": "2019-03-21T03:14:16.383068Z",
    "comments": {
        "results": [],
        "count": 0
    },
    "parented": true,
    "embed_url": "https://plot.ly/~fibi/13.embed",
    "fid": "fibi:13",
    "filename": "interest_seg_click",
    "filetype": "plot",
    "img_url": "https://storage.googleapis.com/plotly-prod-images/fibi/13/9_0WK806I8E41O3AH66KR6SG555EBV7R.png",
    "image_urls": {
        "default": "https://storage.googleapis.com/plotly-prod-images/fibi/13/2_U4T6B0SOK658RZ7244PH2S50G3U4FH.png",
        "block-thumb": "https://storage.googleapis.com/plotly-prod-images/fibi/13/8_41KZUQE589PIO30CRLACE8HRYGTWHT.png",
        "list-thumb": "https://storage.googleapis.com/plotly-prod-images/fibi/13/9_0WK806I8E41O3AH66KR6SG555EBV7R.png"
    },
    "api_urls": {
        "files": "https://api.plot.ly/v2/files/fibi:13",
        "plots": "https://api.plot.ly/v2/plots/fibi:13",
        "parent": "https://api.plot.ly/v2/folders/home?user=fibi"
    },
    "owner": "fibi",
    "parent": -1,
    "preview": "",
    "referencers": [],
    "references": [],
    "title": "",
    "views": 1,
    "web_url": "https://plot.ly/~fibi/13/",
    "world_readable": true,
    "date_modified": "2019-03-21T03:15:34.868Z",
    "stars": {
        "results": [],
        "count": 0
    },
    "collaborators": {
        "results": [],
        "count": 0
    },
    "subfolder_count": null,
    "refresh_interval": null,
    "organize_view_url": "https://plot.ly/~fibi/13/",
    "current_user_permission": "read",
    "is_theme": null,
    "is_template": null,
    "autosize": true,
    "caption": "",
    "figure": {
        "data": [
            {
                "mode": "markers",
                "type": "scatter3d",
                "xsrc": "fibi:12:8dd293",
                "ysrc": "fibi:12:75296e",
                "zsrc": "fibi:12:275b82",
                "frame": null,
                "marker": {
                    "line": {
                        "color": "transparent"
                    },
                    "symbol": "circle",
                    "sizesrc": "fibi:12:570e82",
                    "colorsrc": "fibi:12:fd6927",
                    "sizemode": "diameter",
                    "fillcolor": "rgba(31,119,180,1)",
                    "showscale": true,
                    "colorscale": [
                        "#FFE1A1",
                        "#683531"
                    ]
                },
                "textsrc": "fibi:12:0a766f"
            }
        ],
        "layout": {
            "scene": {
                "xaxis": {
                    "title": "Recency"
                },
                "yaxis": {
                    "title": "Frequency"
                },
                "zaxis": {
                    "title": "Depth"
                },
                "plot_bgcolor": "rgb(243, 243, 243)",
                "paper_bgcolor": "rgb(243, 243, 243)"
            },
            "xaxis": {
                "domain": [
                    0,
                    1
                ]
            },
            "yaxis": {
                "domain": [
                    0,
                    1
                ]
            },
            "margin": {
                "b": 40,
                "l": 60,
                "r": 10,
                "t": 25
            },
            "hovermode": "closest",
            "showlegend": false
        }
    },
    "height": null,
    "width": null,
    "user": {
        "profile_url": "https://plot.ly/~fibi",
        "avatar_url": "https://storage.googleapis.com/plotly-prod-profiles/93.jpg",
        "background_url": "https://storage.googleapis.com/plotly-prod-profiles/bg-3.jpg",
        "bio": "",
        "nickname": "",
        "website": "",
        "stream_tokens": null,
        "feature_set_id": null,
        "csrf_token": null,
        "date_joined": "2019-03-19 20:55:18",
        "mapbox_access_tokens": null,
        "has_password": null,
        "username": "fibi",
        "email": null,
        "is_active": null,
        "readonly": null
    }
}