API FAQ

The StatSocial API is organized around REST. Our API is designed to have predictable, resource-oriented URLs and to use HTTP response codes to indicate API errors. We use built-in HTTP features, like HTTP authentication and HTTP verbs, which can be understood by off-the-shelf HTTP clients, and we support cross-origin resource sharing to allow you to interact securely with our API from a client-side web application (remember that you should never expose your secret API key in any public website’s client-side code). JSON will be returned in all responses from the API, including errors (though if you’re using API bindings, we will convert the response to the appropriate language-specific object).

This section concerns rate limits imposed by StatSocial’s API to ensure fair usage of the platform. No more than 1 calls per endpoint until a HTTP request is returned. If you exceed your API limit, all subsequent requests will fail with a suitable error message and HTTP response code of 403.

Your Statsocial account is tied to a purchased subscription plan and or Audience limits. Audience limits are enforced prior to executing report generation. For example, if you are running a follower report that requires 1mm followers and your account has only 500,000 audience size remaining, an error will occur and the report will not run. If this happens please contact sales@statsocial.com or your client services representative. If you are running an ongoing tweet report, the report will cease when audience limits are reached.

Authenticate to the StatSocial API by providing your API key in the request. You can manage your API key from your account. You can have multiple API keys active at one time (across multiple accounts). Be sure to keep your key secret. Authentication to the API occurs via HTTP Basic Auth. Provide your API key as the basic auth username. You do not need to provide a password.

You access StatSocial’s APIs in two ways:
-Use HTTP headers
-Place all the parameters in a GET/POST request

Accessing a StatSocial API endpoint using GET/POST parameters is the simpler approach. It is sometimes useful for testing. Within this document are example that calls to each REST API endpoints.

NOTE: your API key is case sensitive.

To use the StatSocial API, the first thing you need is your API key.
1. Log in to StatSocial.
2. Go to the Settings page or email help@statsocial.com.
Note that StatSocial does not display the API key until you have a subscription plan or have purchased an audience amount. Free accounts do not have API access.
(In this document “key” refers to API Key)

This is the recommended approach for production environments. You need to include a header that contains: Authorization: your-statsocial-api-key

StatSocial will notify you via email when your account reaches, 75% and 90% of your audience limit. The email communication will include your audience limit and your remaining audience count.

StatSocial uses conventional HTTP response codes to indicate success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the provided information (e.g. a required parameter was missing, a charge failed, etc.), and codes in the 5xx range indicate an error with StatSocial’s servers.

200 OK – Everything worked as expected.
201 Created – Resulted in a new resource being created
400 Bad Request – Often missing a required parameter.
401 Unauthorized – No valid API key provided.
403 Denial – Rate limit exceeded.
404 Not Found – The requested item doesn’t exist.
500 Server errors – something went wrong on StatSocial’s end.

There are some dependencies to keep in mind. For example, you cannot consume a report until you have added the report to the platform for analysis.

We are constantly striving to build the best platform. From time to time it may be necessary to disrupt our services to perform maintenance and upgrades. Client Services will alert you to any scheduled work.

The rate limit is designed to ensure that everyone plays fair. If you find yourself hitting the limits, you might have to wait a few minutes.

API reports can currently be filtered with the following options. Filtering options are for the following variables:
• gender
• ages
• countries
• states
Variables are added to the API call required. JSON must be structured in a key to value format where value is an array containing desired filters for each key.

Format:
{
“key1”: [“value1”, ”value2”, …, ”valueN”],
”key2”: [“value1”, ”value2”, …, ”valueN”],
…,
”keyN”: [“value1”]
}

Gender
Currently supported values that can be passed to the gender option:
• male
• female

example format:
{“gender”: [“male”]}
The above example will create a report based on a male audience

Ages
Currently supported values that can be passed to ages option:
• <18
• 18-24
• 25-34
• 35-44
• 45-54
• 55+

example format:
{“ages”: [“<18”, “45-54”]}
The above example will create a report based on an audience of aged under 18 and 45 – 54

Countries
Currently supported values that can be passed to the countries option:
• Any valid country

example format:
{“countries”: [“jamaica”, “canada”]}
The above example will create a report based on an audience located in jamaica and canada

States
Currently supported values that can be passed to the states option:
• Any valid US state

example format:
{“states”: [“NY”, “NJ”]}
The above example will create a report based on an audience located in NY and NJ

Parameters were added to the StatSocial Report API to allow filtering on demographic variables for StatSocial reports. Filtering is available in the following ways:
• Running a new filtered report
• Custom Report (/reports/custom/create/)
• Tweet Report (/reports/tweet/create/)
• Follower Report (/reports/twitter/create/)
• Filtering an existing report
Note filtering an existing report will not count against your StatSocial audience or report counts.

A filtered report can be generated by requesting a report type endpoint with parameters:
• /reports/custom/create/ for custom reports
• /reports/tweet/create/ for tweet reports
• /reports/twitter/create/ for follower reports

http://api.statsocial.com/api/reports/endpoint?

Parameters:

//Twitter Handle to create report on
twitter_handle=Ronnie2K

//FILTER SHOULD BE URL ENCODED
filter={“gender”:[“male”],”ages”:[“18-24″],”countries”:[“usa”]}

therefore,

filter = %7B%22gender%22%3A%5B%22male%22%5D%2C%22ages%22%3A%5B%2218-24%22%5D%2C%22countries%22%3A%5B%22usa%22%5D%7D

//User’s API key
key={insert key here}

Final URL:

http://api.statsocial.com/api/reports/twitter/create/?twitter_handle=Ronnie2K&filter=%7B%22gender%22%3A%5B%22male%22%5D%2C%22ages%22%3A%5B%2218-24%22%5D%2C%22countries%22%3A%5B%22usa%22%5D%7D&key=aad8df0e06761e256abd328d71953409

The above URL will generate a filtered report on twitter handle ‘Ronnie2K’ which contains data on males aged 18-24 located in the US

Post “Retrieve, Create and Status methods are listed under the API REST Page. Each method is described with sample get and posts requests “

JSON (JavaScript Object Notation) is the default format for the data that our APIs return. Wikipedia introduces JSON as “a lightweight text-based open standard designed for human-readable data interchange.”