Skip to main content

/chart: images of graphs

Sometimes an image is enough to get the points across. This method can provide the image.

POST /chart​

Create a new image called a chart for a new graph with the provided configurations.

Example usage​

Using configurations for constructing a graph, a POST request can create a new graph:

graph.json
{
    "data": [
        {
            "x": [0, 1, 2, 3, 4, 5, 6],
            "y": [0, 1, 4, 9, 16, 25, 36],
            "name": "squares",
            "type": "scatter"
        },
        {
            "x": [0, 1, 2, 3, 4, 5, 6],
            "y": [0, 1, 2, 3, 4, 5, 6],
            "name": "dots",
            "type": "scatter"
        }
    ],
    "layout": {
        "title": "A squared curve"
    }
}
terminal
$ curl https://api.graphing.tools/v1/chart \
    -X POST \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -d "@graph.json"
output
{
    "ok": "true",
    "graph": {
        "graph_id": "G0123456789AZ",
        "image_url": "https://plots.graphing.tools/x/G0123456789AZ.png"
    }
}

Request parameters​

Send a POST request to the following URL, replacing placeholders and providing your own values:

POST /v1/chart HTTP/1.1
Host: api.graphing.tools
Authorization: Bearer $token
Content-Type: application/json

{
    "data": Object[],
    "layout": Object,
}

$token​

An authorization token for the graphing grapher. Gathered as an API key from the account page.

data​

A collection of graph data as objects in an array. This is used to represent all types of points and numeric values and will determine so much of the final graph.

The format and types of data available is determined by the APIs of the Plotly graphing libraries. Check out this guide on constructing graph data for the nuanced details.

layout​

Optional options for the layout of the graph. This decides how the graph is presented in any visual outputs.

Configurations provided here will override any default layouts or stylings. Read about customizing layout configurations and themes for more information and inspiration.

Response parameters​

After a successful request the following data will be returned in the response:

json
{
    "ok": boolean,
    "graph": {
        "graph_id": string,
        "image_url": string
    }
}

ok​

If the request completed successfully. Hopefully true since false means something went wrong. Read about troubleshooting errors or search the known errors for more information.

graph.graph_id​

The graph ID of the newly created graph. This can be used to gather the graph data, chart image, or interactive plot.

graph.image_url​

The stable URL of the pictorial representation for the graph. This image can be viewed and downloaded as a png file.

GET /chart/:graph_id​

Retrieve an existing chart image with the graph_id of a previously uploaded graph.

Example usage​

Using the graph ID from a previous POST, possibly G0123456789AZ, a GET request can be made to gather chart details:

terminal
$ curl https://api.graphing.tools/v1/chart/G0123456789AZ
output
{
    "ok": "true",
    "graph": {
        "graph_id": "G0123456789AZ",
        "image_url": "https://plots.graphing.tools/x/G0123456789AZ.png"
    }
}

Request parameters​

Send a GET request to the following URL, updating placeholder parameters as needed:

HTTP
GET /v1/chart/:graph_id HTTP/1.1
Host: api.graphing.tools

:graph_id​

The graph ID of a previously uploaded graph.

Response parameters​

After a successful request the following data will be returned in the response:

json
{
    "ok": boolean,
    "graph": {
        "graph_id": string,
        "image_url": string
    }
}

ok​

If the request completed successfully. Hopefully true since false means something went wrong. Read about troubleshooting errors or search the known errors for more information.

graph.graph_id​

The graph ID of the gathered chart. This will match the provided :graph_id.

graph.image_url​

The stable URL of the pictorial representation for the graph. This image can be viewed and downloaded as a png file.