push/create

Create a new Subscription to a live stream.

An HTTP POST request sent to:

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

A successful call to this endpoint returns: 200 OK.

Parameters

Parameter Description
hash

required

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

Example values: 2459b03a13577579bca76471778a5c3d

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.6/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.
    hash_type "hash"
    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
  3. Therefore you need to supply either a hash.
  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.6.

Resource information

Rate limit cost: 5

Requires authentication: Yes

Response formats: JSON