source/update

Update a Managed Source.

An HTTPS PUT request sent to:

https://api.datasift.com/v1.3/source/update

A successful call to this endpoint returns: 202 Accepted plus a JSON object.

Parameters

Parameter Description
source_type
optional

Data source name. A string:

name
optional

Custom identifier for the user. A string.

Example values: xkcd

id
required

Source id. A string.

Example values: fd2e72e3a7ae40c2a6e86e96381d8165

parameters
optional

Source-specific configuration. The key-value pairs used here will depend on the value of the source parameter. Click the links above for full details.

resources
optional

An array of source-specific resources. Click the links above for full details.

auth
optional

An array of source-specific authentication credentials. Most source types require an OAuth2 access token, but there are exceptions. Look at the source specific documentation for full details.

Take a look at /source/create for more details on the auth and resources parameters.

validate
optional

Allows you to suppress validation of your token with the source. Can be:

  • true, t, or 1
  • false, f, or 0

Defaults to true.

If you set this parameter to false you will see a performance improvement when updating a Managed Source. However, if DataSift does not validate your token you will not see any warning or error messages until you attempt to use this newly updated Managed Source.

Examples

  1. Building on our previous example from /source/create, assume we decide to change the parameters for that Facebook source. In particular, we no longer care for comments and likes, but we do care about posts by other people. The source parameters object would like something like the following:

    {
        "comments": false,
        "likes": false,
        "posts_by_others": true,
        "page_likes": false
      }

    To update our source, we need to pass back the results of the create call, along with any changes we want to make. Note that we need to identify the source, and every resource and authentication token by the unique identifiers we got back.

    To summarize, our array of resources should look like this (note the mandatory resource ids):

    "resources": [
        {
          "parameters": {
            "title": "The Guardian",
            "id": "10513336322"
          },
          "resource_id": "706af7cce1484d098553a2be580fa3bb"
        },
        {
          "parameters": {
            "title": "BBC News",
            "id": "228735667216"
          },
          "resource_id": "b4e2ae889ff346129d687fa4c56caed2"
        }
      ]

    while our array of authentication credentials will be like this (note the mandatory identity ids):

    "auth": [
        {
          "expires_at": 2112112110,
          "parameters": {
            "value": "EZBXlFZBUgBYmjHkxc2pPmzLeJJYmAvQkwZCRdm0A1NAjidHy1h"
          },
          "identity_id": "d38e5598142746e19689ddee65ddca55"
        }
      ]

    The request should look something like this (note the mandatory source id):

    curl -X PUT https://api.datasift.com/v1.3/source/update 
        -d id=da4f8df71a0f43698acf9240b5ad668f 
        -d 'resources:[{"resource_id":"706af7cce1484d098553a2be580fa3bb","parameters":{"id":"10513336322","title":"The Guardian"}},{"resource_id":"b4e2ae889ff346129d687fa4c56caed2","parameters":{"id":"228735667216","title":"BBC News"}}]' 
        -d 'auth:[{"identity_id":"d38e5598142746e19689ddee65ddca55","parameters":{"value":"EZBXlFZBUgBYmjHkxc2pPmzLeJJYmAvQkwZCRdm0A1NAjidHy1h"},"expires_at":2112112110}]' 
        -d '{"posts_by_others":true,"likes":false,"comments":false,"page_likes": false}' 
        -d 'source_type=facebook_page' 
        -d 'name=news_source' 
        -H Authorization:datasift-user:datasift-key

    And the response will be:

    {
        "id": "da4f8df71a0f43698acf9240b5ad668f",
        "name": "news_source",
        "source_type": "facebook_page",
        "created_at": 1391707662,
        "status": "running",
        "parameters": {
          "comments": false,
          "likes": false,
          "posts_by_others": true,
          "page_likes": false
        },
        "resources": [
          {
              "parameters": {
                  "id": "10513336322",
                  "title": "The Guardian"
              },
              "resource_id": "706af7cce1484d098553a2be580fa3bb"
          },
          {
              "parameters": {
                  "id": "228735667216",
                  "title": "BBC News"
              },
              "resource_id": "b4e2ae889ff346129d687fa4c56caed2"
          }
        ],
        "auth": [
          {
            "expires_at": 2112112110,
            "parameters": {
              "value": "EZBXlFZBUgBYmjHkxc2pPmzLeJJYmAvQkwZCRdm0A1NAjidHy1h"
            },
            "identity_id": "d38e5598142746e19689ddee65ddca55"
          }
        ]
      }

  2. Now assume some time has passed, and our token is about to expire. Moreover, we want our source to start monitoring an additional page.

    To add the new page, we need to provide an array that includes all previous resources (along with their resource ids), as well as our new resource (which will not have an id). The resulting array will look like this:

    "resources": [
        {
          "parameters": {
            "title": "The Guardian",
            "id": "10513336322"
          },
          "resource_id": "706af7cce1484d098553a2be580fa3bb"
        },
        {
          "parameters": {
            "title": "BBC News",
            "id": "228735667216"
          },
          "resource_id": "b4e2ae889ff346129d687fa4c56caed2"
        },
        {
          "parameters": {
            "title": "The Huffington Post",
            "id": "18468761129"
          }
        }
      ]

    To replace our access token we need to provide an array for auth that only includes the new access token. This will effectively delete the previous entry (because it is not provided), and add the new one. The array will look like this:

    "auth": [
        {
          "expires_at": 2122112110,
          "parameters": {
            "value": "h1yHdijAN1A0mdRCZwkQvAmYJJeLzmPp2cxkHjmYBgUBZFlXBZE"
          }
        }
      ]

    The entire request will look like this:

    curl -X PUT https://api.datasift.com/v1.3/source/update 
        -d id=da4f8df71a0f43698acf9240b5ad668f 
        -d 'auth=[{"parameters":{"value":"h1yHdijAN1A0mdRCZwkQvAmYJJeLzmPp2cxkHjmYBgUBZFlXBZE"},"expires_at":2122112110}]' 
        -d 'resources=[{"resource_id":"706af7cce1484d098553a2be580fa3bb","parameters":{"id":"10513336322","title":"The Guardian"}},{"resource_id":"b4e2ae889ff346129d687fa4c56caed2","parameters":{"id":"228735667216","title":"BBC News"}},{"parameters":{"id":"18468761129","title":"The Huffington Post"}}]' 
        -d '{"posts_by_others":true,"likes":false,"comments":false,"page_likes": false}' 
        -d source_type=facebook_page 
        -d name=news_source 
        -H Authorization:datasift-user:datasift-key

    While the response we get back will look like this (note how the identity id is now different, and our new resource has acquired an id as well):

    {
        "id": "da4f8df71a0f43698acf9240b5ad668f",
        "name": "news_source",
        "source_type": "facebook_page",
        "created_at": 1391707662,
        "status": "running",
        "parameters": {
          "comments": false,
          "likes": false,
          "posts_by_others": true,
          "page_likes": false
        },
        "resources": [
          {
            "parameters": {
                "id": "10513336322",
                "title": "The Guardian"
            },
            "resource_id": "706af7cce1484d098553a2be580fa3bb"
          },
          {
            "parameters": {
                "id": "228735667216",
                "title": "BBC News"
            },
            "resource_id": "b4e2ae889ff346129d687fa4c56caed2"
          },
          {
            "parameters": {
              "title": "The Huffington Post",
              "id": "18468761129"
            },
            "resource_id": "f0fba887b29f4d51b0135e3b64c5ee38"
          }
        ],
        "auth": [
          {
            "expires_at": 2112112110,
            "parameters": {
              "value": "h1yHdijAN1A0mdRCZwkQvAmYJJeLzmPp2cxkHjmYBgUBZFlXBZE"
            },
            "identity_id": "a756727d187d4b1e836207444f130201"
          }
        ]
      }

Output fields

Property: Description:
auth The list of source-specific authentication credentials.
created_at The source creation date and time.
comments Found in the Facebook Pages, Google+, and Instagram sources, inside the parameters element. Present when the source is supposed to deliver interactions that represent comments.
distance Distance for Instagram updates.
event_types The type of Google+ updates provided by the parent resource. When present, found once per resource.
exact_match Search match scope for Instagram updates.
expires_at Expiry time and date for an authentication token.
extract_links Links augmentation algorithm. Found in Yammer resources.
foursq Foursquare ID for Instagram updates.
id The source ID or the Facebook ID of a Facebook Page.
lat Latitude for Instagram updates.
likes Found in the Facebook Pages and Instagram sources, inside the parameters element. Present when the source is supposed to deliver like interactions.
lng Longitude for Instagram updates.
name The name of a source or a set of authentication credentials. Each source has one name element and at least one set of authentication credentials.
parameters Source- or resource-specific parameters. Each source and each resource has one parameters element. Alternatively, parameters of an authentication token.
plus_ones Found in the Google+ source, inside the parameters element. Present when the source is supposed to deliver interactions that represent +1 events.
posts_by_others Found in the Facebook Pages source, inside the parameters element. Present when the source is supposed to deliver interactions related to posts created on the monitored page by the users who interact with that page, but do not administer it.
refresh_token Google+ refresh token.
resources The list of all resources defined for the current source. For additional information, see /source/create.
source_type The source type.
status The status of a source. Each source has one status element. For additional information, see /source/create.
title The title of a Facebook Page. Found once in each resource listed in the resources element.
type The type of Google+ or Instagram updates provided by the parent resource. Found once in each resource listed in the resources element.
url The URL of a Facebook Page. Found once in each resource listed in the resources element.
user_id The Google+ ID of the user whose updates are provided by the parent resource. When present, found once per resource.
search_string The type of Google+ updates provided by the parent resource. When present, found once per resource.
value Can be an Instagram user ID, when found in an Instagram resource; or an authentication token when found in the auth element.

Errors:

If there is an error, we return an HTTP 4xx status code, along with a message explaining the error; for example:

  • Trying to add an existing authentication token to a source: 400 Bad Request

    {
        "error": "Bad Request (400): {\"exception\":\"BadRequest400Exception\",\"message\":\"an identity with the same token already exists\",\"success\":false}"
    }

Notes

  1. All calls to the API must be properly authenticated with a DataSift username and API key.
  2. We recommend that you do not submit more than 100 pages or terms at a time when creating or updating sources.
  3. All calls to the API must be versioned. The current version is v1.3.

Resource information

Rate limit cost: 25

Requires authentication: Yes

Response formats: JSON, JSONP