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:

API base URL: https://api.symplur.com/v1
API documentation: https://docs.symplur.com/reference
OpenAPI v3 specification: https://api.symplur.com/v1/openapi.yaml

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=

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,
    ...
}

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 reference section for a full description of API endpoints. Most of the endpoints in the Analytics: Tweets section 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 List endpoint.

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.

Best Practices

Here are some tips for using our API:

Be sure to URL encode any special characters which you are inputting into our API. In particular, the leading # character used in hashtags has an alternate meaning for URLs, so it usually must be encoded as %23. If you are using a 3rd-party framework or library to make requests, this may already be handled for you. If not, you will have to implement this step manually.
For best performance, we recommend storing your token locally in a secure manner and reusing it each time a request needs to be made. Symplur access tokens have fixed lifetimes. If a previously working token begins failing with a 401 Unauthorized error, this probably indicates that it expired and a new one must be generated.
We are constantly improving our API. This documentation represents the features that Symplur has publicly released and is actively supporting. Undocumented features are considered Beta, or in some cases are deprecated. For maximum stability of your code, please only use the features that are documented here, and ensure that your code can tolerate the appearance of new or undocumented output fields.