pushdata.io
by ragnarlonn

pushdata.io

This documentation describes the API methods available at pushdata.io, and how to use them. There is a Simple API, with just two methods, that allow you to store and retrieve time series data. There is also an Extended API that provides more filtering functionality and more efficient data insertion.
Client SDKs

If you prefer not to use the REST API directly, there are currently client SDKs for Python and Arduino (ESP8266). Check out this blog article about them or look at the Github repositories:

Simple API

The pushdata.io Simple API provides an extremely simple way to store and retrieve time series data to/from pushdata.io. You can start storing data immediately, without registering an account (the account will be created automatically).

Store data point
POST /{email}/{tsname}/{value}
Get time series data
GET /{email}/{tsname}
Store data point
POST /{email}/{tsname}/{value}

Stores a time series value on pushdata.io.

The email path variable identifies your unique user on pushdata.io. This user will be created automatically if it doesn’t already exist.

The tsname path variable identifies which time series the data point should be added to. The time series will also be created if it doesn’t exist.

The timestamp used for the data point will be the current time, but can be overridden using the ?ts= (e.g. ?ts=1540380567) query parameter and supplying a timestamp in Unix EPOCH format.

Path variables

email
string required

Your email address. Should be a valid email address.

Example:
example@example.com
tsname
string required

Time series name. May contain alphanumerics and “-_.”

Example:
Temperature5
value
string required

Numerical value to store. Integer or float (everything is stored as float64).

Example:
33

Request parameters

ts
string optional

Timestamp (in RFC3339 format or Unix EPOCH format) to use for data point.

Examples:
15412546592018-11-02T22:18:50Z
apikey
string optional

Include account API key, for confirmed accounts where authentication is necessary. If this parameter is not present, and the account is confirmed, pushdata.io will look for an existing session cookie as a last attempt at authenticating the user.

Example:
6y0nsaug0d5lx4slobar

Responses

201 201 - Created
Example 1
Example 2

Storing a single data point to a time series.

POST https://pushdata.io/example@example.com/Temperature5/33 HTTP/1.1 

HTTP/1.1 201 Created

Storing a data point when the user is confirmed.

POST https://pushdata.io/example@example.com/Temperature5/33?apikey=6y0nsaug0d5lx4slobar HTTP/1.1 

HTTP/1.1 201 Created
Get time series data
GET /{email}/{tsname}

Fetches data points from a time series and returns them in JSON format.

Path variables

email
string required

The email address you used when storing data.

Example:
example@example.com
tsname
string required

The time series name.

Example:
Temperature5

Request parameters

offset
integer optional

Return data points starting at this offset.

limit
integer optional

Max number of data points to return. Default is to return max 1000 data points in a response.

apikey
string optional

Include account API key, for confirmed accounts where authentication is necessary. If this parameter is not present, and the account is confirmed, pushdata.io will look for an existing session cookie as a last attempt at authenticating the user.

Example:
6y0nsaug0d5lx4slobar

Responses

201 Time series data

JSON object containing both time series data from a time series, and meta-information about the time series (e.g. time series name, total number of points stored).

Example 1
Example 2

Fetch all data points from, plus meta information about, a time series.

GET https://pushdata.io/example@example.com/Temperature5 HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "name": "Temperature5",
    "first": "2018-10-24T12:00:10.445297Z",
    "last": "2018-10-24T12:01:10.342221Z",
    "total": 2,
    "returned": 2,
    "offset": 0,
    "limit": 1000,
    "points": [
        {
            "time": "2018-10-24T12:00:10.445297Z",
            "value": 33
        },
        {
            "time": "2018-10-24T12:01:10.342221Z",
            "value": 33
        }
    ]
}

Fetch time series data from a confirmed account.

GET https://pushdata.io/example@example.com/Temperature5?apikey=6y0nsaug0d5lx4slobar HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "name": "Temperature5",
    "first": "2018-10-24T11:59:47.767933Z",
    "last": "2018-10-24T12:00:10.445297Z",
    "total": 2,
    "returned": 2,
    "offset": 0,
    "limit": 1000,
    "points": [
        {
            "time": "2018-10-24T11:59:47.767933Z",
            "value": 33
        },
        {
            "time": "2018-10-24T12:00:10.445297Z",
            "value": 34
        }
    ]
}
201 Time series data

JSON object containing both time series data from a time series, and meta-information about the time series (e.g. time series name, total number of points stored).

Body
Object
name
string

Time series name.

Example:
Temperature5
first
string

Timestamp (in RFC3339-format) of oldest data point in series.

Example:
2018-10-24T11:59:47.767933Z
last
string

Timestamp (in RFC3339-format) of newest data point in series.

Example:
2018-10-24T12:00:10.445297Z
total
integer

Total number of data points in series on pushdata.io.

Example:
1244
returned
integer

How many data points were returned in the JSON response.

offset
integer

What offset query parameter was used in the call.

Example:
0
limit
integer

What limit query parameter was used in the call.

Example:
1000
points
Array of Point

An array with data points from the time series.

Extended API

The pushdata.io extended API allows more advanced integrations. It lets you upload time series data as a JSON object, sending many data points in one single call. It also lets you filter data when fetching, and manipulate/change stored data.

Store data points
POST /api/timeseries
Get time series data
GET /api/timeseries
Delete time series
DELETE /api/timeseries
Store data points
POST /api/timeseries

Store one or more time series data points.

Request parameters

If the account and/or the time series do not exist, they will be created automatically.

email
string optional

Email address of pushdata.io user account.

Example:
example@example.com
apikey
string optional

Include account API key, for confirmed accounts where authentication is necessary. If this parameter is not present, and the account is confirmed, pushdata.io will look for an existing session cookie as a last attempt at authenticating the user.

Example:
6y0nsaug0d5lx4slobar
uid
integer optional

User ID number of pushdata.io user account. Can be used instead of the email parameter if you want to be able to identify an account that may at some point change its registered email address.

Request headers

Content-Type
string optional

application/json

Request body

Object
name
string

Time series name.

Example:
Temperature5
points
Array

Time series data points.

Object
time
string

Timestamp (in RFC3339-format).

Example:
2018-10-24T11:59:47.767933Z
value
number

Data point value (int or float - everything is stored as float64).

Example:
33

Responses

201 Created
Example 1
Example 2

Store two data points to a time series.

POST https://pushdata.io/api/timeseries?apikey=6y0nsaug0d5lx4slobar HTTP/1.1 

Content-Type: application/json

{
    "name": "Temperature5",
    "points": [
        {
            "time": "2018-10-24T11:58:46.455543Z",
            "value": 33
        }
        {
            "time": "2018-10-24T11:59:47.767933Z",
            "value": 35
        }
    ]
}

HTTP/1.1 201 Created

Store a data point for an unconfirmed user (no authentication needed).

POST https://pushdata.io/api/timeseries?email=example@example.com HTTP/1.1 

Content-Type: application/json

{
    "name": "Temperature5",
    "points": [
        {
            "time": "2018-10-24T11:59:47.767933Z",
            "value": 33
        }
    ]
}

HTTP/1.1 201 Created
Get time series data
GET /api/timeseries

Fetches time series data from pushdata.io.

Request parameters

tsname
string required

Name of time series to fetch.

Example:
Temperature5
email
string optional

Account that owns the time series. If this parameter is not given, pushdata.io will try to look at either a supplied apikey= query parameter, or use an existing session cookie to determine what account to fetch data from.

Example:
example@example.com
from
string optional

Select data points where the timestamp is >= from value. Expressed in either RFC3339 format or Unix EPOCH seconds.

Examples:
2018-11-02T22:18:50Z1541254659
to
string optional

Select data points where the timestamp is <= to value. Expressed in either RFC3339 format or Unix EPOCH seconds.

Examples:
2018-11-02T22:18:50Z1541254659
offset
integer optional

Return data points starting at this offset, from the set of selected data points. If the from and to parameters were not used, offset will be applied to the whole set of data points in the time series.

Example:
0
limit
integer optional

Max number of data points to return. Default (and max allowed) is to return max 10000 data points in a response. limit is the last selection criteria to be applied, after from, to and offset.

Example:
10000
apikey
string optional

Include account API key, for confirmed accounts where authentication is necessary. If this parameter is not present, and the account is confirmed, pushdata.io will look for an existing session cookie as a last attempt at authenticating the user.

Example:
6y0nsaug0d5lx4slobar
uid
integer optional

User ID number of pushdata.io user account. Can be used instead of the email parameter if you want to be able to identify an account that may at some point change its registered email address.

Responses

201 Time series data

JSON object containing both time series data from a time series, and meta-information about the time series (e.g. time series name, total number of points stored).

Example 1
Example 2
Example 3

Get time series data.

GET https://pushdata.io/api/timeseries?tsname=Temperature5&apikey=6y0nsaug0d5lx4slobar HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "name": "Temperature5",
    "first": "2018-10-24T11:59:47.767933Z",
    "last": "2018-10-24T12:00:10.445297Z",
    "total": 2,
    "returned": 2,
    "offset": 0,
    "limit": 1000,
    "points": [
        {
            "time": "2018-10-24T12:00:10.445297Z",
            "value": 33
        },
        {
            "time": "2018-10-24T12:01:10.583374Z",
            "value": 34
        }
    ]
}

Get time series data from an unconfirmed account (no auth needed).

GET https://pushdata.io/api/timeseries?tsname=Temperature5 HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "name": "Temperature5",
    "first": "2018-10-24T11:59:47.767933Z",
    "last": "2018-10-24T12:00:10.445297Z",
    "total": 2,
    "returned": 2,
    "offset": 0,
    "limit": 1000,
    "points": [
        {
            "time": "2018-10-24T11:59:47.767933Z",
            "value": 33
        },
        {
            "time": "2018-10-24T12:00:10.445297Z",
            "value": 33
        }
    ]
}
GET https://pushdata.io/api/timeseries?tsname=Temperature5&from=2018-11-02T22:00:00Z&to=2018-11-02T22:05:00Z HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "name": "Temperature5",
    "first": "2018-11-02T22:01:05.767933Z",
    "last": "2018-11-02T22:04:05.445297Z",
    "total": 2,
    "returned": 2,
    "offset": 0,
    "limit": 1000,
    "points": [
        {
            "time": "2018-11-02T22:01:05.767933Z",
            "value": 33
        },
        {
            "time": "2018-11-02T22:04:05.445297Z",
            "value": 34
        }
    ]
}
Delete time series
DELETE /api/timeseries

Delete a whole time series.

Request parameters

tsname
string required

Time series name.

Example:
Temperature5
email
string optional

Email address for account that owns the time series. Not necessary if you include apikey to authenticate a confirmed account - in that case, the key will be used to identify the user account also.

Example:
example@example.com
apikey
string optional

Include account API key, for confirmed accounts where authentication is necessary. If this parameter is not present, and the account is confirmed, pushdata.io will look for an existing session cookie as a last attempt at authenticating the user.

Example:
6y0nsaug0d5lx4slobar
uid
string optional

User ID number of pushdata.io user account. Can be used instead of the email parameter if you want to be able to identify an account that may at some point change its registered email address.

Responses

204 No Content
Example 1

Delete a time series.

DELETE https://pushdata.io/api/timeseries?tsname=Temperature5&apikey=6y0nsaug0d5lx4slobar HTTP/1.1 

HTTP/1.1 204 No Content
More API methods

All methods not related to storing/fetching/manipulating time series data

Get user account data
GET /api/user
Get user account data
GET /api/user

Fetch user account information, including a list of stored time series owned by the user.

Request parameters

email
string optional

Email address of pushdata.io user account.

Example:
example@example.com
uid
string optional

User ID number of pushdata.io user account. Can be used instead of the email parameter if you want to be able to identify an account that may at some point change its registered email address.

Example:
334506
apikey
string optional

Include account API key, for confirmed accounts where authentication is necessary. If this parameter is not present, and the account is confirmed, pushdata.io will look for an existing session cookie as a last attempt at authenticating the user.

Example:
6y0nsaug0d5lx4slobar

Responses

200 OK

User data as JSON object

Body
Object
uid
integer

User ID number.

Example:
334506
email
string

User email address.

Example:
example@example.com
apikey
string

Account API key.

Example:
6y0nsaug0d5lx4slobar
confirmed
boolean

True if the email address has been confirmed.

accountlevel
integer

User level of the account. 0=Free, 1-3=Premium.

timeseries
Array of TimeSeriesData

Array of TimeSeriesData objects.

quota
Quota
Example 1
GET https://pushdata.io/api/user HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "uid": 334506,
    "email": "example@example.com",
    "apikey": "6y0nsaug0d5lx4slobar",
    "confirmed": true,
    "accountlevel": 1,
    "timeseries": [
        {
            "name": "Temperature5",
            "first": "2018-10-24T11:59:47.767933Z",
            "last": "2018-10-24T12:00:10.445297Z",
            "total": 2,
            "returned": 2,
            "offset": 0,
            "limit": "1000",
            "points": [
                {
                    "time": "2018-10-24T11:59:47.767933Z",
                    "value": 33
                },
                {
                    "time": "2018-10-24T12:00:10.445297Z",
                    "value": 34
                }
            ]
        }
    ],
    "quota": {
        "timeseries": 50,
        "pointspertimeseries": 10000,
        "apicallsperday": 10000,
        "apicallspermonth": 100000
    }
}
Identification and authorization

The pushdata.io API methods are pretty smart, and will do their best to figure out two things whenever an API request is made:

  1. Which authenticated user is making the request
  2. Which target user the request involves

The target user is the user whose data the request is trying to either fetch or manipulate somehow. For instance, a POST to https://pushdata.io/example@example.com/Temperature5/33 means that the target user is the one currently registered with the email example@example.com.

The authenticated user is whichever user account the request successfully authenticates as. For instance, if we had added ?apikey=6y0nsaug0d5lx4slobar to the above POST request, pushdata.io would have looked up who the owner of that API key was, and then set authenticated user to be that user.

When both the target user and authenticated user have been determined, pushdata.io can decide whether to do what the request wants, or deny the request. If the target user is an account with the security disabled, most requests will be granted, but if target user has enabled security, then authenticated user has to match target user (i.e. they have to be the same user) or the request will be denied.

There are several ways a user can supply target user and authenticated user to pushdata.io. Here is what happens behind the scenes in almost all cases when using the extended API:

  1. If an apikey=x query parameter is present, it will be used to determine the authenticated user. This parameter takes priority in determining authenticated user
  2. If no apikey parameter was present, pushdata.io will look for a valid session cookie, which will then determine which the authenticated user is
  3. If a uid=x query parameter is present, it will be used to determine who the target user is. This parameter takes priority in determining the target user
  4. If no uid parameter was present, pushdata.io will look for an email=x parameter and use that to determine the target user
  5. If neither a uid nor an email parameter were present, meaning we have no target user identified, pushdata.io will then use the authenticated user as target user

The above means that if a request just provides authentication info (via an API key or a session cookie), but does not provide info about which user to manpiulate/fetch data for, then pushdata.io will assume the target user to be the same as the authenticated user.

TimeSeriesData

A TimeSeriesData object contains a series of data points from a time series, plus meta information (e.g. the name of the time series).

Object
name
string

Name of time series

Example:
Temperature5
first
string

Timestamp (in RFC3339-format) of oldest data point in series, or oldest data point of those that were selected, if we provided from and/or to parameters in the query.

Example:
2018-10-24T11:59:47.767933Z
last
string

Timestamp (in RFC3339-format) of newest data point in series, or newest data point of those that were selected, if we provided from and/or to parameters in the query.

Example:
2018-10-24T12:00:10.445297Z
total
integer

Total number of data points in this time serie, or total number of data points that were selected, if we provided from and/or to parameters in the query.

returned
integer

How many data points are present in this particular TimeSeriesData object

Example:
2
offset
integer

If the query contained an offset parameter, the value provided there will be present here also, signifying at what offset from the total (explained above), the first returned data point is located. Default offset for queries is 0 (zero).

Example:
0
limit
string

This property is set to whatever the user supplied as the limit query parameter, when e.g. requesting time series data through the API. The default limit, when returning data points, is to return up to 1000 points.

Example:
1000
points
Array of Point

Data points for the time series

Example 1
{
    "name": "Temperature5",
    "first": "2018-10-24T11:59:47.767933Z",
    "last": "2018-10-24T12:00:10.445297Z",
    "total": 2,
    "returned": 2,
    "offset": 0,
    "limit": "1000",
    "points": [
        {
            "time": "2018-10-24T11:59:47.767933Z",
            "value": 33
        },
        {
            "time": "2018-10-24T12:00:10.445297Z",
            "value": 34
        }
    ]
}
Point

A timestamp/value pair. Multiple Point objects make up a time series.

Object
time
string

Time stamp, in RFC3339 format

Example:
2018-10-24T11:59:47.767933Z
value
number

Data point value. Integer or float (pushdata stores all values as 64-bit float).

Example:
33
User

The User object contains information about a user account

Object
Example: 
{
    "uid": 334102,
    "email": "example@example.com",
    "apikey": "6y0nsaug0d5lx4slobar",
    "confirmed": true,
    "accountlevel": 1,
    "timeseries": [
        {
            "name": "Temperature5",
            "first": "2018-10-24T11:59:47.767933Z",
            "last": "2018-10-24T12:00:10.445297Z",
            "total": 1,
            "returned": 1,
            "offset": 1,
            "limit": "1000",
            "points": [
                {
                    "time": "2018-10-24T11:59:47.767933Z",
                    "value": 33
                }
            ]
        }
    ],
    "quota": {
        "timeseries": 100,
        "pointspertimeseries": 10000,
        "apicallsperday": 10000,
        "apicallspermonth": 100000
    }
}
uid
integer

User ID: A unique ID number that is assigned upon account creation and never changed (the email address connected to an account can be changed).

Example:
334102
email
string

The email address connected to the account. The email is often used as identifier when making API requests, but it is possible to change it.

Example:
example@example.com
apikey
string

Secret API key used to authenticate a user when making API requests.

Example:
6y0nsaug0d5lx4slobar
confirmed
boolean

True if the account email has been confirmed. Confirmed accounts are secure (which means you have to use an API key or be logged in, in order to access the account and its data)

accountlevel
integer

User level of the account. 0=Free, 1-3=Premium

Example:
0
timeseries
Array of TimeSeriesData

The time series stored on the account

Example: 
[
    {
        "name": "Temperature5",
        "first": "2018-10-24T11:59:47.767933Z",
        "last": "2018-10-24T12:00:10.445297Z",
        "total": 1,
        "returned": 1,
        "offset": 1,
        "limit": "1000",
        "points": [
            {
                "time": "2018-10-24T11:59:47.767933Z",
                "value": 33
            }
        ]
    }
]
quota
Quota

Quota object, describing the quota limits for the account

Example: 
{
    "timeseries": 100,
    "pointspertimeseries": 10000,
    "apicallsperday": 10000,
    "apicallspermonth": 100000
}
nick
string

Nickname last used when posting a blog comment

Example:
SleepyKoala
security
boolean

Whether security is enabled for the account or not. Security can only be toggled when a user has authenticated, using their API key.

Example:
true
premiumsubcanceled
boolean

True if a user has bought a premium subscription and then canceled it (the subscription will still be active until the premiumsubend date).

Example:
true
premiumsubend
string

Date and time when a canceled premium subscription ends, reverting the account back to non-premium.

Example:
2019-03-08T10:18:58Z
Quota

JSON object containing account limits information

Object
timeseries
integer

Max number of time series account is allowed to store on pushdata.io

Example:
100
pointspertimeseries
integer

Max number of data points account is allowed to store in each of its time series

Example:
10000
apicallsperday
integer

Max number of API calls the account may make each 24-hour period

Example:
10000
apicallspermonth
integer

Max number of API calls the account may make each 30-day period

Example:
100000