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, available to premium users, that provides more filtering functionality and more efficient data insertion.
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).

POST /{email}/{tsname}/{value}
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.

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 [premium]

The pushdata.io extended API is available to paying users and 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.

(Please note that the Simple API is always available to all users, free and paying)

POST /api/timeseries
GET /api/timeseries
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).

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 is to return max 1000 data points in a response. limit is the last selection criteria to be applied, after from, to and offset.

Example:
1000
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 /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
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 unconfirmed account, most requests will be granted, but if target user is confirmed, 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.

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 object, describing the quota limits for the account

Example:
{
    "timeseries": 100,
    "pointspertimeseries": 10000,
    "apicallsperday": 10000,
    "apicallspermonth": 100000
}
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