Getting Started with Symplur API

Welcome to the Symplur API! Here you can get access to our extensive set of Analytics data. Our API is JSON based, follows REST design principles, and uses OAUth 2.0 for authentication. Here are some important links:

Quick Start, Step 1

Please contact us to obtain your Client Credentials. This consists of a Client ID and a Client Secret, which serve as a username and password for your organization. Use these credentials to generate an HTTP Basic Auth header as in the following psuedo code:

header = base64(clientId + ":" + clientSecret)

This produces a string such as:

MWIxNjU2ZjgtOWY2MS00M2UwLWFlNWItMmY1NDVkZmNkMDJlOmpNaGJ5MGtOWXZsenNiclVXalhkZ1Z1bENEcXNyRWx3TkFzdldQa3Q=

Quick Start, Step 2

Make a POST request to https://api.symplur.com/v1/oauth/token with grant_type=client_credentials in the request body, using your encoded credential string from Step 1 as an HTTP Basic Auth header, as shown:

# curl -d "grant_type=client_credentials" \
    -H "Authorization: Basic MWIxNjU2ZjgtOWY2MS00M2UwLWFlNWItMmY1NDVkZmNkMDJlOmpNaGJ5MGtOWXZsenNiclVXalhkZ1Z1bENEcXNyRWx3TkFzdldQa3Q=" \
    "https://api.symplur.com/v1/oauth/token"

A successful response will include this:

{
    ...
    "access_token": "u6aYEi1auNtHFi69oqWSeq0ZRlvwiGwdfMtknJeBGXdpIu75",
    "expires_in": 3600,
    ...
}

Quick Start, Step 3

Use the access token from Step 2 to authenticate with other API endpoints. For example, here is a request for the top Influencers for #bcsm during the last 3 days:

# curl -H "Authorization: Bearer u6aYEi1auNtHFi69oqWSeq0ZRlvwiGwdfMtknJeBGXdpIu75" \
    "https://api.symplur.com/v1/twitter/analytics/people/influencers?databases=%23bcsm&start=3%20days%20ago&end=now"

That's it!

API Usage

Please see our API documentation for a full description of API endpoints. Our Twitter Analytics endpoints all support the same general set of input parameters. Three parameters are required:

  • start - The beginning timestamp of the desired date range. See below for supported formats and interpretation.
  • end - The ending timestamp of the desired date range. See below for supported formats and interpretation.
  • databases - A comma-separated list of the predicates and/or groups you want to include. May use IDs or names. Groups must be prefixed with group: to distinguish them from predicates. Examples: #bcsm or #hcsm,19265,stomach flu or 4921,group:721,#sibo,group:Diabetes. To discover which predicates and groups you may access, see our Database Search endpoint.

You may also wish to include:

  • timezone - Timezone to use in interpreting the start and end fields, and in formatting API outputs. Can be any common city-based timezone such as America/New_York or Europe/Amsterdam. Default is UTC.

Timestamps can be absolute or relative. They can be UNIX timestamps or almost any common English format. Here are some examples:

  • 1501590600
  • 2017-10-12T17:30:00-0700
  • 3 weeks ago
  • 10/12/17 5:30pm
  • 2015-04-30

Timestamps are interpreted down to the nearest second. For example, a value of 10/12/17 would be interpreted as midnight on October 12, 2017, or 2017-10-12 00:00:00, relative to the requested timezone.

Best Practices

Be sure to Percent-encode the input values for any GET requests. This is especially important for the databases field because hashtags include the "#" character, which normally has another meaning for URLs.

Note that Symplur access tokens have fixed lifetimes. The token endpoint described above includes an expires_in field which shows how many seconds the token will last (typically 1 hour.) For best performance, we recommend writing your app so that it stores your access token locally in a secure manner and reuses it each time an API request needs to be made. Then, if it receives a 401 Unauthorized response when making a request to the API, it should automatically obtain a new access token and then retry the request.