Plotly API

Interactive, publication-quality plots in your web browser


Interface Plotly's online graphing tools with your desktop environment. Send data to your Plotly account and view your graphs in your web browser. Style with code or with our online interface; share your work publicly with a url or privately among other Plotly members; access your graphs from anywhere.

Give it a try and let us know what you think.
Click here to Fork us on GitHub!

Plotly REST API Documentation

Resource

Description

POST /apimkacct

Resource URL

https://plot.ly/apimkacct

Query String Parameter

Description

un

required

Desired username

Example Value :
anna.lyst
email

required

Email account associated with the user. Although an email is required to sign up to plotly no email verification is required to use the API.

Example Value:
anna.lyst@gmail.com
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.

Response

Parameter

Description

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

Example Value :
tj6mr88zgy
tmp_pw
A password created to login to your plotly account through the plotly website. You can change this password through the plotly website.
error
A string describing any error that occured.

Example Value:
Error: A user with this username already exists.
message
A string describing a non-critical message to the user.

Example Values:
Plotly has recently expanded the API library.

Example Request

POST
https://plot.ly/apimkacct
DATA
un=anna.lyst&email=anna.lyst@plot.ly&platform=Python&version=0.1

Example Response

DATA
Response is a JSON object encoded as a string.
{
    "api_key": "3jasdk3",
    "tmp_pw": "sdfkj43",
    "error": ""
}

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": ""
}

Basic streaming concepts

Streaming has been added as an additional API layer on top of the REST API. Therefore you follow the steps for making a REST API plot request to instantiate a base plot with your desired layout, style and mapping of streaming tokens to data arrays. This is accomplished by following the documentation for the REST API with the addition of adding tokens into the data object.
[{
  "x": [],
  "y": [],
  "type": "scatter",
  "mode": "markers",
  "stream": {
      "token": "xxxyyyxxxi",
      "maxpoints": 500
      }
}]
Once this has successfully been posted you are ready to begin streaming to the streaming endpoint, http://stream.plot.ly. To match your data stream to the correct data object in the initialized plot attach a token to the HTTP headers sent to the streaming endpoint.
headers = {"plotly-streamtoken": "xxxyyyxxxi"}
Once the stream has been connected over http, write to the request stream with newline separated JSON.
httpRequestSocket.write('{ "x": 3, "y": 1 }\n')
The newline is extremely important. Without this delimiter the Streaming Endpoint will not delineate your data, and will terminate the stream. You can send multiple streams to the same plot by nesting stream tokens within the corresponding data trace object. Similarly you can use the same token for multiple traces in a plot (they will show the same stream, so this is useful only in when using subplots).

Connecting

To connect to the Streaming API, form an HTTP request and write to the request for as long as you want to maintain the stream. Our streaming cluster will hold the connection open indefinitely, barring server-side error, excessive client-side lag, network hiccups, routine server maintenance or duplicate streams using the same token. The method to form an HTTP request and write newline separated data will be different for every language or framework, so consult the documentation for the HTTP library you are using. We have provided example Python and Nodejs documentation. Some HTTP client libraries form a single request body which is sent to the server when the request is closed. These clients will not work for accessing the Streaming API. You must use an HTTP client that will allow writing response data incrementally.

Disconnections

Plotly will close a streaming connection for the following reasons:

  • A client establishes additional streams using the same stream token. When this occurs, the oldest connection will be terminated. This means you have to be careful not to run two reconnecting clients in parallel with the same credentials, or else they will take turns disconnecting each other.
  • A client stops writing data for a time period longer than a minute. If a minute passes without receiving any data from the client the stream connection will be closed. (A connection can be maintained by writing a heartbeat within the 60 second window, a heartbeat is simply a newline).
  • A streaming server is restarted. This is usually related to a code deploy and is not very frequent.

Reconnecting

Once an established connection drops, attempt to reconnect immediately. If the reconnect fails, slow down your reconnect attempts according to the type of error experienced:

  • Back off linearly for TCP/IP level network errors. These problems are generally temporary and tend to clear quickly. Increase the delay in reconnects by 250ms each attempt, up to 16 seconds.
  • Back off exponentially for HTTP errors for which reconnecting would be appropriate. Start with a 5 second wait, doubling each attempt, up to 320 seconds.

Data Loss and Write Speed

  • Incoming data should not be written faster than 50ms. We throttle incoming JSON objects at 50ms. While there is a buffer queue to absorb changes in the data rate, continuously sending data faster than 50ms will result in data loss.
  • You must send data every minute otherwise we will consider the stream stale and destroy it. If your data comes in a slower rate send a heartbeat to let the streaming server know it is still active. A heartbeat is simply a newline "\n" written within the 60 second window.

Connection Stability

Repeatedly opening and closing a connection (churn) wastes server resources. Keep your connections as stable and long-lived as possible.

HTTP Error Codes

Most error codes are returned with a string with additional details. For all codes greater than 200, clients should wait before attempting another connection. See the Connecting section, above.
{
"200": "healthy endpoint disconnect"
, "308": "stream had ended"
, "400": "invalid or malformed request syntax"
, "403": "stream token no longer associated with this plot"
, "404": "streamtoken not registered or valid"
, "405": "bad request method: use POST for streaming"
, "406": "bad request header: missing 'plotly-streamtoken'"
, "408": "timeout on active data"
, "422": "json parse error: please stream newline seperated JSON"
, "423": "connection limit associated with this token has been reached"
, "449": "stream content has changed, reloading clients"
, "500": "internal server error"
, "503": "internal database error"
, "520": "error in request stream"
}

Scientific Graphing Libraries

Hardware and Makers