Skip to main content

/graph: structured data

The information of a graph can sometimes be easier to read when in the JSON format. And sometimes having it can be useful.

Gather all of the graph data, layout information, and permalinks to the plots and charts of a graph with these methods.

POST /graph​

Create a new graph object with the provided configurations and receive all created resources.

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/graph \
    -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",
        "permalink": "https://plots.graphing.tools/x/G0123456789AZ",
        "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"
        }
    }
}

Request parameters​

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

POST /v1/graph 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,
        "permalink": string,
        "data": Object[],
        "layout": Object
    }
}

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.

graph.permalink​

The permanant URL of the interactive plot for a graph. This page can be shared or downloaded as a standalone html file.

graph.data​

The collection of graph data as an array of objects. This is a stable JSON representation of the points on a graph as interpreted by Plotly.

In most cases, this will exactly match the input data for the graph.

graph.layout​

Metadata containing the styles applied and any other adjustments to the visual representation of a graph.

GET /graph/:graph_id​

Retrieve existing graph information 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 graph details:

terminal
$ curl https://api.graphing.tools/v1/graph/G0123456789AZ
output
{
    "ok": "true",
    "graph": {
        "graph_id": "G0123456789AZ",
        "image_url": "https://plots.graphing.tools/x/G0123456789AZ.png",
        "permalink": "https://plots.graphing.tools/x/G0123456789AZ",
        "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"
        }
    }
}

Request parameters​

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

HTTP
GET /v1/graph/: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,
        "permalink": string,
        "data": Object[],
        "layout": Object
    }
}

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 graph. 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.

The permanant URL of the interactive plot for a graph. This page can be shared or downloaded as a standalone html file.

graph.data​

The collection of graph data as an array of objects. This is a stable JSON representation of the points on a graph as interpreted by Plotly.

graph.layout​

Metadata containing the styles applied and any other adjustments to the visual representation of a graph.

DELETE /graph/:graph_id​

Remove all resources associated with an existing graph. This includes both data and generated files.

Example usage​

With the graph ID from a previous POST, perhaps G0123456789AZ, a DELETE request can be made to remove graph resources:

terminal
$ curl https://api.graphing.tools/v1/graph/G0123456789AZ \
    -X DELETE \
    -H "Authorization: Bearer YOUR_API_KEY"
output
{
    "ok": "true"
}

Request parameters​

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

DELETE /v1/graph/:graph_id HTTP/1.1
Host: api.graphing.tools
Authorization: Bearer $token

:graph_id​

The graph ID of a previously uploaded graph.

$token​

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

Response parameters​

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

json
{
    "ok": boolean
}

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.