Sign In SIGN UP UPGRADE

Plotly Rest API

Developers: Please use Plotly's open V2 API.
The V1 API below is no longer actively maintained.
Getting started with Plotly's V2 API.

Plotly REST API 1.0 Documentation

Resource

Description

POST /clientresp

Resource URL

https://plot.ly/clientresp

Query String Parameter

Description

un

required

Desired username

Example Value :
anna.lyst
key

required

Key used to access your plotly account with through the API.

Example Value :
tj6mr88zgy
origin

required

plot, style, or layout. Specifies the type of call and the type of data in the parameter args. See the examples below.
platform

required

Language or platform that the client is making the request from.

Example Value :
'lisp'
version

optional

Version of the API client code. This parameter may be used to issue a warning response to users that are using an out-of-date client library. For example, if a user is making a request with the MATLAB Plotly interface, version 0.1 (which has since been updated to version 0.2), Plotly will return with:
warning: Using a depreciated client library. Please upgrade to version 0.2
If you are a developer and you are versioning your Plotly client library and would like these warning messages issued, then please get in touch at chris[at]plot[dot]ly.
args

required

Data and/or styling argument. The structure of args depends on the value of origin.

origin=plot:

Either args=[x1, y1[, ..., xn, yn]] where xi, yi are arrays of numbers or strings or args=[data1[, ... datan]] where datai is a JSON object with at least the names x, y, or z but may contain more styling and chart-type data. See the examples below for many examples.

origin=style:

args=[style1[,style2, ...]] where stylei is a JSON object that customizes the style of the i'th trace. It is identical to the datai object used in origin=plot except that it doesn't contain the data key-value pairs x, y, or z.

origin=layout:

args=layout where layout is an object that customizes the style of the layout, the axes, and the legend.

Examples

origin=plot:

[[0, 1, 2], [3, 1, 6]],
[{"x": [0, 1, 2], "y": [3, 1, 6]}],
[{"x": [0, 1, 2], "y": [3, 1, 6], "name": "Experimental", "marker": {"symbol": "square", "color": "purple"}}, {"x": [1, 2, 3], "y": [3, 4, 5], "name": "Control"}]

origin=style:
[{"type": "bar"}, {"type": "scatter", "marker": {"symbol": "square", "color": "marker"}}])

origin=layout:
{"title": "experimental data"}

kwargs

required

Key

Value

filename

required

Name of the plot in your plotly account. Use / to specify directories. If a directory path does not exist it will be created.

Example Values
{"filename": "plot from api"}
{"filename": "data/temperature vs humidity"}
fileopt

required

"new", "overwrite", "append", or "extend"

See below for an illustrative example of these values.
style

optional

The trace-style object as described above and in the examples. The style object is applied to every single trace (default) or to the traces specified in the optional traces key-value pair.

Example Values

Apply style to all traces, e.g. make every trace a bar type:
{"style":{"type": "bar"}}

Apply style to select traces by index, e.g. make traces 0, 1, and 5 a bar type plot:
{"style": {"type": "bar"},"traces": [0,1,5]}

Apply style to select traces by name, e.g. make the traces titled "experimental" and "control" a bar type:
{"style": [{"name": "experiment", "type": "bar"},{"name": "control", "type": "bar"}]}
traces

optional

traces specifies the indices that the style object should be applied to.
Also applies to which traces are extended if using fileopt="extend"
layout

optional

a key-value paired object that describes the layout of the plot. See below for an example that specifies all available key-value pairs.

Example Values
{"title": "my plot title", "xaxis": {"name": "Time (ms)"}, "yaxis": {"name": "Voltage (mV)"}}
world_readable

optional

If true: graph is viewable by anyone who has the link and in the owner's plotly account.
If false: graph is only viewable in the owner's plotly account.
kwarg_example

optional

kwargs={
  "filename": "plot from api",
  "fileopt": "overwrite",
  "style": {
      "type": "bar"
  },
  "traces": [0,3,5],
  "layout": {
      "title": "experimental data"
  },
  "world_readable": true
}

Response

Parameter

Description

filename
The filename of the plot as saved in the user's account.
url
A url where you can view the rendered graph of your data if
world_readable=True.
error
A string describing a possible error that may have occured.
Example Value:
Error: A user with this username already exists.
warning
A string describing a possible warning message.
Example Values:
Warning: You are using an outdated version of the API.
message
A string describing a non-critical message to the user.
Example Values:
Message: Plotly has recently expanded the API library.

Example Request

POST
https://plot.ly/clientresp
DATA
un=chris&
key=kdfa3d&
origin=plot&
platform=lisp&
args=[[0, 1, 2], [3, 4, 5], [1, 2, 3], [6, 6, 5]]&
kwargs={"filename": "plot from api",
        "fileopt": "overwrite",
        "style": {
            "type": "bar"
        },
    "traces": [1],
    "layout": {
        "title": "experimental data"
    },
    "world_readable": true
}

Example Response

DATA
Response is a JSON object encoded as a string.
{
  "filename": "plot from api",
  "url": "https://plot.ly/~chris/1459",
  "error": "",
  "warning": "",
  "message": ""
}