Using the Historical PowerTrack API requires Basic Authentication (username/password), like most Enterprise APIs. However, it’s worth calling out a few items that are specific to working with Historical PowerTrack. 

When you first create a Historical PowerTrack job, the API generates a job UUID. Subsequent endpoint requests relating to this job must include the job’s UUID for identification purposes. 

The job UUID can be found as part of the “jobURL” field returned in the payload when you first create a job with the POST /jobs endpoint (see example below):

"jobURL": "https://gnip-api.gnip.com:443/historical/powertrack/accounts/{ACCOUNT_NAME}/publishers/twitter/jobs/qvfsnagdx0.json"

The job UUID must be passed as part of the endpoint URL when you make subsequent requests to any of the following four endpoints:

  • GET /jobs/uuid: Monitor the status of a Historical PowerTrack job.
  • PUT /jobs/uuid: Accept or reject a Historical PowerTrack job that has been estimated.
  • GET /results/uuid: Retrieve the list of URLs for a finished job. These URLs can then be used to download the data files from AWS S3 buckets.
  • Download results: Download the Twitter data files generated for a complete Historical PowerTrack job.

 

Historical PowerTrack jobs, once completed, will generate a set of data files (each file equates to a ten minute segment of time covered by the job, except where there is no matching Twitter data found within that ten minute segment). 

The response to the GET /results/uuid request will include a “urlCount” field that indicates the total number of files to download, and the S3 URL corresponding to each file. You’ll notice the self-authenticating aspect of the S3 URLs, which will include your account name, an AWS access key, expiry date, and signature. Information on how to download each data file is available in our guide on downloading Historical PowerTrack files.

The response returned by GET /results/uuid also includes a “totalFileSizeBytes” field that indicates the total size of the data files in bytes. You can use this information to verify that the total size of all the data files downloaded matches up against the total size of all the data files provided in the results.

The following code sample is also available to help you implement Historical PowerTrack: