Getting Started - Curl

What you'll learn: How to submit a strategy task to the API, wait for analysis to be completed, and fetch the analysis results
Duration: 20 minutes

Table of contents

Before you start

Before you start this guide, if you haven't already done so take a look at our product overview page to learn the key concepts of the platform.

You work with the Media Strategies API by submitting strategy tasks to be run, waiting for the analysis to complete, and then retrieving the results.

This guide will show how you can call the API directly using curl commands to queue and fetch strategy tasks.

Choosing a strategy and parameters

You can choose from a number of strategies when calling the API.

For this example you'll analyze LinkedIn engagement activity using the top_urls strategy. You will use this strategy to discover the content seeing the most engagement for the topic of 'cloud computing' by members in the US.

Your parameters for the strategy will be:

{
    "name": "Top urls for cloud",
    "subscription_id": "cd99abbc812f646c77bfd8ddf767a134f0b91e84",
    "type": "strategy",
    "parameters": {
        "strategy": "top_urls",
        "version": 1,
        "parameters": {
            "keywords": {
                "any": ["cloud", "azure", "aws", "google cloud", "vmware"]
            },
            "audience": {
                "countries": ["united states"]
            },
            "comparison_audience": "global"
        }
    }
}

Notice how you specify the strategy to be run using the strategy and version parameters.

Also notice how you use the keywords parameter to specify terms that relate to the topic, and the audience parameter to specify the country of members you'd like to analyze.

Queuing a strategy task for processing

To run a strategy task you add it to your task queue. The task will then be processed by the platform when capacity is available for your account.

You use the POST /pylon/{service}/task endpoint to queue a new task.

curl -X POST "https://api.datasift.com/v1.5/pylon/linkedin/task" \
    -H 'Auth: USERNAME:IDENTITY_APIKEY' \
    -H "Content-Type: application/json" \
    -d '{"name": "Top urls for cloud","subscription_id": "cd99abbc812f646c77bfd8ddf767a134f0b91e84","type": "strategy","parameters":{"strategy": "top_urls","version": 1,"parameters": {"keywords": {"any": ["cloud","azure","aws","google cloud","vmware"]},"audience": {"countries": ["united states"]},"comparison_audience": "global"}}}'

Notice in the command you:

  • use linkedin as the service, as this is the data source you are analyzing.
  • use the Content-Type header to specify content type as application/json.
  • use the Auth header to pass in your account details.
  • pass in parameters for the task as JSON.

When you submit a task, provided the request is accepted, you will receive a task id in the API response:

{"id":"16f9cd543900cbb80728d78ae95947ea6103e2aa"}

You will use this id when fetching the status and result of the task.

Waiting for strategy task to complete

Now that your task is submitted you will check its status until the task is completed.

To check the status of the task you use the GET /pylon/{service}/task/{type}/{id} endpoint.

curl -X GET "https://api.datasift.com/v1.5/pylon/linkedin/task/strategy/16f9cd543900cbb80728d78ae95947ea6103e2aa" \
    -H 'Auth: USERNAME:IDENTITY_APIKEY'

Notice in the command you:

  • use linkedin as the service, as this is the data source you are analyzing.
  • use strategy as the type, as you are fetching a Media Strategies API task.
  • use the id of the task as the final portion of the url.

The API will respond with details for the task:

{
  "name": "Top urls for cloud",
  "type": "strategy",
  "parameters": { ... },
  "status": "queued",
  "result": null,
  ...
}

In this case you can see from the status property that the task is currently queued.

You can repeat the request after waiting a number of seconds until the status is completed.

Fetching results of a strategy task

Once a task is complete, when you fetch the task the API response will include the analysis results.

{
  "name": "Top urls for cloud",
  "type": "strategy",
  "parameters": { ... },
  "status": "completed",
  "result": {
    "interactions": 1093200,
    "unique_authors": 893400,
    "redacted": false,
    "urls": [
      {
        "engagement_ratio": 2.554,
        "interactions": 600,
        "url": "http://www.military-technologies.net/2017/04/11/data-blue-acquires-williams-garcia-llc-2/",
        "unique_authors": 500
      },
      ...
  },
  ...
}

For this example the top_urls strategy gives you a list of urls and the amount of engagement each has seen.

These results can now be simply integrated with your application.

Next steps

Next take a look at our developer guide to learn each feature of the Media Strategies API in depth.

Also, take a look at the complete list of strategies supported by the Media Strategies API.