push/create

Create a new Subscription to a live stream or Historics query.

An HTTP POST request sent to:

https://api.datasift.com/v1.3/push/create

A successful call to this endpoint returns: 200 OK.

Parameters

Parameter Description
hash

required if not historics_id

The hash of a stream. Use this if you want to receive live data.

Example values: 2459b03a13577579bca76471778a5c3d

historics_id
required
if not hash

The id of a Historics query. Use this if you want to receive Historics data.

Example values: 3ea6e1ca364f3b327e6f

name
required

The name of the Subscription that this API call will create.

Example values: test

output_type
required

The output destination type. It is one of the connectors.

Example values: dynamodb

output_params.*
required

The output parameters are documented individually for each of DataSift's connectors.

Example values: output_params.format=json

initial_status
optional
default = active

Set the initial subscription status to paused if you want DataSift to buffer your data and deliver it later. Can be:

  • active
  • paused
  • waiting_for_start (when you use either start or end parameters)

Example values: active

start
optional
default = now

Set the start time/date for the streaming subscription. Time/date is given as a Unix timestamp. Must be smaller than the value of "end".

Example values: 1363973400

end
optional
default = unspecified

Set the end time/date for the streaming subscription. Time/date is given as a Unix timestamp. Must be greater than the value of "start".

Example values: 1363973800

Examples

  1. Use Push to send interactions to your chosen data destination. In the following example we are creating a Push subscription that delivers interactions to your Amazon AWS DynamoDB table:

curl -X POST 'https://api.datasift.com/v1.3/push/create' 
    -d 'name=mypushsubscription' 
    -d 'hash=42d388f8b1db997faaf7dab487f11290' 
    -d 'output_type=dynamodb' 
    -d 'output_params.region=dynamodb.eu-west-1.amazonaws.com' 
    -d 'output_params.table=datasift-dynamodb' 
    -d 'output_params.auth.access_key=YourAmazonAWSAccessKey' 
    -d 'output_params.auth.secret_key=YourAmazonAWSSecretKey' 
    -H 'Authorization: datasift-user:your-datasift-api-key'

Notice that the output parameters are echoed back in the JSON.

{
    "id": "d468655cfe5f93741ddcd30bb309a8c7",
    "output_type": "dynamodb",
    "name": "mypushsubscription",
    "created_at": 1365430066,
    "user_id": 12635,
    "hash": "42d388f8b1db997faaf7dab487f11290",
    "hash_type": "stream",
    "output_params": {
        "table": "datasift-dynamodb",
        "region": "dynamodb.eu-west-1.amazonaws.com"
    },
    "status": "active",
    "last_request": null,
    "last_success": null,
    "remaining_bytes": null,
    "lost_data": false,
    "start": 0,
    "end": 0
}

Property: Description:
id A unique ID of the newly created Push subscription. Each new subscription has a different ID, even when they are based on the same stream and the data is delivered to the same destination.
output_type The name of the output type. See the list of the values of the output_type parameter elsewhere on this page.
name A user-defined name of the subscription.
created_at A Unix timestamp that represents the date and time when the subscription was created.
user_id The DataSift ID of the user who created the subscription.
hash A stream ID or Historics query ID.
hash_type Can be either "hash" (when the hash element represents a stream) or "historics" (when the hash element represents a Historics query).
output_params output_parameters used in the call to /push/create.
status Subscription status.
last_request The time of the most recent Push delivery request sent to the associate data destination. A Unix timestamp. Set to null, because the subscription has just been created.
last_success The time of the most recent successful delivery. A Unix timestamp. Set to null, because the subscription has just been created.
remaining_bytes The number of bytes queued for delivery.
lost_data Set to true if data was removed from the Push delivery queue because it could not be delivered.
start Subscription start time/date. A Unix timestamp. Set to null for immediate start.
end Subscription end time. A Unix timestamp. Set to null when interactions should be delivered for as long as the subscription is active.

Notes

  1. All calls to the API must be properly authenticated with a DataSift username and API key.
  2. The /push/create endpoint delivers data from:
    • live streams running in real time
    • queries against DataSift's Historics archive
  3. Therefore you need to supply either a hash or a Historics id. Do not specify both in the same API call; DataSift will return a 400 error if you do.
  4. The call creates a new Subscription based on the parameters you supply. It returns a JSON object containing a unique id for the Subscription. Keep a record of this id.
  5. It is possible to define time limits for the subscription using the "start" and "end" parameters. They may be omitted but when they are set they must be set in the future and the value of "end" must be greater than the value of "start".
  6. For more details, take a look at the Push API overview.
  7. All calls to the API must be versioned. The current version is v1.3.

Revision history

v1.2

Prior to v1.2, playback_id was a synonym for the historics_id parameter. The playback_id parameter is no longer supported. You must use historics_id.

Resource information

Rate limit cost: 5

Requires authentication: Yes

Response formats: JSON, JSONP