Charts API

This API allows M2X users to create and manage charts based on their devices' data. These charts can then be embedded in web pages and applications using a unique URL.

Authentication

All methods described in this page require that a Master API Key is specified in the X-M2X-KEY header. Any attempt to use a Device level API key would result in a 403 Forbidden response. Learn more about API Keys.

The only exception to this rule is the Render Chart method. This is a public method and therefore it does not require an API key nor any other kind of user authentication mechanism.

List Charts

GET /charts

Retrieve the list of charts that belong to the authenticated account. This method accepts one optional parameter:

  • device: a Device ID; it will list all the charts that are associated with that specific device.
  • if none is specified, then all charts belonging to the authenticated account will be returned.

Responses

Success

200 OK
Content-Type: application/json

{
  "charts": [
    {
      "id": "a58c276d47d5a3eb34343cd2e6aebaf2",
      "name": "Single-device Chart",
      "series": [
        { "device": "8a198ad5984605bcb6721c82e230a067", "stream": "temperature" },
        { "device": "8a198ad5984605bcb6721c82e230a067", "stream": "humidity"    }
      ],
      "url": "https://api-m2x.att.com/v2/charts/a58c276d47d5a3eb34343cd2e6aebaf2",
      "render": {
        "png": "https://api-m2x.att.com/v2/charts/a58c276d47d5a3eb34343cd2e6aebaf2.png",
        "svg": "https://api-m2x.att.com/v2/charts/a58c276d47d5a3eb34343cd2e6aebaf2.svg"
      }
    },
    {
      "id": "48087cde3837a933d36c0462cb529224",
      "name": "Multi-device Chart",
      "series": [
        { "device": "8a198ad5984605bcb6721c82e230a067", "stream": "temperature" },
        { "device": "dcecf28bfca0ff8b5e3ba719b8e2b702", "stream": "temperature" },
        { "device": "707d0a17592816dded6ba82b0e222927", "stream": "temperature" }
      ],
      "url": "https://api-m2x.att.com/v2/charts/48087cde3837a933d36c0462cb529224",
      "render": {
        "png": "https://api-m2x.att.com/v2/charts/48087cde3837a933d36c0462cb529224.png",
        "svg": "https://api-m2x.att.com/v2/charts/48087cde3837a933d36c0462cb529224.svg"
      }
    }
  ]
}

Create Chart

POST /charts

Create a new chart associated with the authenticated account. It takes the following parameters:

  • name the name of the new chart (required).
  • series an array containing the series to plot in the chart. Each element in this array must indicate the device ID and the name of the stream to be plotted (required).

Request

Content-Type: application/json

{ "name": "Single-device Chart",
  "series": [
    { "device": "8a198ad5984605bcb6721c82e230a067", "stream": "temperature" },
    { "device": "8a198ad5984605bcb6721c82e230a067", "stream": "humidity"    }
  ]
}

Responses

Success

201 Created
Content-Type: application/json
Location: https://api-m2x.att.com/v2/charts/a58c276d47d5a3eb34343cd2e6aebaf2

{
  "id": "a58c276d47d5a3eb34343cd2e6aebaf2",
  "name": "Single-device Chart",
  "series": [
    { "device": "8a198ad5984605bcb6721c82e230a067", "stream": "temperature" },
    { "device": "8a198ad5984605bcb6721c82e230a067", "stream": "humidity"    }
  ],
  "url": "https://api-m2x.att.com/v2/charts/a58c276d47d5a3eb34343cd2e6aebaf2",
  "render": {
    "png": "https://api-m2x.att.com/v2/charts/a58c276d47d5a3eb34343cd2e6aebaf2.png",
    "svg": "https://api-m2x.att.com/v2/charts/a58c276d47d5a3eb34343cd2e6aebaf2.svg"
  }
}

Validation Failed

422 Unprocessable Entity
Content-Type: application/json

{ "message": "Validation Failed",
  "errors": { "name": ["not_present"] } }

A developer will receive this response if one or more of these validations fail:

  • The chart name must be specified (not_present).
  • At least one series must be specified (not_present).
  • All devices must exist and belong to the authenticated account (not_found).
  • All streams must exist in the specified device(s) (not_found).

View Chart Details

GET /charts/{id}

Get details of a specific chart. This method is public and therefore it does not require the user to authenticate himself using an API key.

Responses

Success

200 OK
Content-Type: application/json

{
  "id": "a58c276d47d5a3eb34343cd2e6aebaf2",
  "name": "Single-device Chart",
  "series": [
    { "device": "8a198ad5984605bcb6721c82e230a067", "stream": "temperature" },
    { "device": "8a198ad5984605bcb6721c82e230a067", "stream": "humidity"    }
  ],
  "url": "https://api-m2x.att.com/v2/charts/a58c276d47d5a3eb34343cd2e6aebaf2",
  "render": {
    "png": "https://api-m2x.att.com/v2/charts/a58c276d47d5a3eb34343cd2e6aebaf2.png",
    "svg": "https://api-m2x.att.com/v2/charts/a58c276d47d5a3eb34343cd2e6aebaf2.svg"
  }
}

Chart Not Found

404 Not Found
Content-Type: application/json

{ "message": "Chart Not Found", "description": "The resource you requested could not be found. Please verify that the correct resource path was provided, or refer to https://m2x.att.com/developer/documentation for complete API documentation." }

A developer will receive this response when the specified chart does not exist.

Update Chart

PUT /charts/{id}

Update an existing chart. Same validations as in Create Chart apply.

Request

Content-Type: application/json

{ "name": "Single-device Chart",
  "series": [
    { "device": "8a198ad5984605bcb6721c82e230a067", "stream": "temperature" },
    { "device": "8a198ad5984605bcb6721c82e230a067", "stream": "humidity"    }
  ]
}

Responses

Success

204 No Content

Inactive Account

403 Forbidden
Content-Type: application/json

{ "message": "Account Not Active", "description": "Your account has not been activated yet. If you need to re-send the activation email, please visit https://m2x.att.com/activation-required" }

Not Allowed

403 Forbidden
Content-Type: application/json

{ "message": "Forbidden", "description": "The resource you requested is disabled or not accessible with your API key. Please try again with an API key authorized for this operation. Learn more about managing API keys at https://m2x.att.com/developer/documentation/overview#API-Keys" }

A developer will receive this response whenever he tries to access an existing chart that belongs to a different account.

Chart Not Found

404 Not Found
Content-Type: application/json

{ "message": "Chart Not Found", "description": "The resource you requested could not be found. Please verify that the correct resource path was provided, or refer to https://m2x.att.com/developer/documentation for complete API documentation." }

A developer will receive this response when the specified chart does not exist.

Validation Failed

422 Unprocessable Entity
Content-Type: application/json

{ "message": "Validation Failed",
  "errors": { "name": ["not_present"] } }

A developer will receive this response if one or more of these validations fail:

  • The chart name must be specified (not_present).
  • At least one series must be specified (not_present).
  • All devices must exist and belong to the authenticated account (not_found).
  • All streams must exist in the specified device(s) (not_found).

Delete Chart

DELETE /charts/{id}

Delete an existing chart.

Responses

Success

204 No Content

Inactive Account

403 Forbidden
Content-Type: application/json

{ "message": "Account Not Active", "description": "Your account has not been activated yet. If you need to re-send the activation email, please visit https://m2x.att.com/activation-required" }

Not Allowed

403 Forbidden
Content-Type: application/json

{ "message": "Forbidden", "description": "The resource you requested is disabled or not accessible with your API key. Please try again with an API key authorized for this operation. Learn more about managing API keys at https://m2x.att.com/developer/documentation/overview#API-Keys" }

A developer will receive this response whenever he tries to access an existing chart that belongs to a different account.

Chart Not Found

404 Not Found
Content-Type: application/json

{ "message": "Chart Not Found", "description": "The resource you requested could not be found. Please verify that the correct resource path was provided, or refer to https://m2x.att.com/developer/documentation for complete API documentation." }

A developer will receive this response when the specified chart does not exist.

Render Chart

GET /charts/{id}.{format}

This method is public and therefore it does not require the user to authenticate himself using an API key. It's generally used in the src attribute of an <img> html tag.

There are many types of chart rendering options, a developer can choose between render the plain values of a stream or use any of the Data Stream Sampling features. These options are controlled by passing a type parameter to the render URL along with an interval parameter when required.

Currently, the only supported formats are png and svg.

This method accepts the following optional parameters:

  • type: The type of chart to render. Defaults to values. Valid options are: nth, min, max, count, avg, sum and values.
  • limit (optional - valid only when type is values) Maximum number of values to return. If omitted it defaults to 1,000. The maximum value for this parameter is 10,000. If a greater number is specified, the server will only return the 10,000 most recent values on the specified date range.
  • interval: Required when type is not values. The interval in seconds of the data sampling. Defaults to 60.
  • start: an ISO 8601 timestamp specifying the start of the date range to be plotted in the chart. Any values registered before this timestamp will be simply ignored. By default, the last 24 hours will be plotted in the chart.
  • end: an ISO 8601 timestamp specifying the end of the date range to be plotted in the chart. Any values registered after this timestamp will be simply ignored. By default, the last 24 hours will be plotted in the chart.
  • width: image width in pixels. The default value is 600px.
  • height: image height in pixels. The default value is 300px.

Responses

Success

200 OK
Content-Type: image/png

<PNG image>

Chart Not Found

404 Not Found
Content-Type: application/json

{ "message": "Chart Not Found", "description": "The resource you requested could not be found. Please verify that the correct resource path was provided, or refer to https://m2x.att.com/developer/documentation for complete API documentation." }

A developer will receive this response when the specified chart does not exist.