public
Created

Socialyzer API Docs

  • Download Gist
socialyzer_api.textile
Textile

Overview and Authentication

All API requests should be directed to http://api.socialyzerhq.com and include at least a key parameter, the value of which should be your Socialyzer API key. Some API endpoints have other required parameters, but key is always necessary.

Currently GET and POST (as JSON) requests are supported. For example with the rest_client Ruby gem:

<pre>#!/usr/bin/env ruby require 'rest_client' require 'json'

res = RestClient.get “http://dev.socialyzerhq.com/api/optimize.json”, ‘user’ => “bradleyjoyce”, :content_type => :json, :accept => :json

puts res.to_str

or

<pre>#!/usr/bin/env ruby require 'rest_client' require 'json'

res = RestClient.post “http://dev.socialyzerhq.com/api/optimize.json”, {’user’ => "bradleyjoyce"}.to_json, :content_type => :json, :accept => :json

puts res.to_str

Endpoints

Optimize (/api/optimize.json)

Returns an array of one (by default) or more timestamps, in order of preference, in UTC, as suggested posting times based on inputs and analysis, in JSON format:
<pre>{"time":["2012-06-08T17:22:22Z","2012-06-08T18:22:22Z"]}</pre>

All parameters are optional. Supported parameters include:

User (user)

May be in the form of a twitter screen_name or id. This is the user for whom the optimization is to be performed. If not supplied, results are returned based on aggregate analysis of millions of Twitter users.

Start (start)

The beginning of the window over which the tweet is to be optimized, as a number of hours from now. Defaults to 0. Certain keywords are supported, including:

  • today: Same as now, 0 or omitting the parameter
  • tomorrow: Equivalent to midnight tonight (the end of the day the request is made)
  • Sunday: Any weekday name is equivalent to the beginning of the next occurrence of that weekday

End (end)

The end of the window over which the tweet is to be optimized. Defaults to 24 hours from now. Supports the same keywords as start, plus week, which is 24*7 hours from now.

Add Twitter Account (/api/add_twitter_account.json)

Currently accepts two parameters:

User (user, Required)

The value of this parameter should be a Twitter screen_name or id. This is the user to be added to the system.

Fetch (fetch)

Users with large numbers of followers take some time to process because of the volume of data to be fetched from Twitter, including tweets by the user’s followers. For these users, by default, Socialyzer will fetch only a statistically significant sample of data in the interest of bringing them “on board” as quickly as possible. In most cases the cost of a complete data set for such a user, relative to its statistical value, makes this prudent. The purpose of this parameter is to override that default behavior. The value can take the form of an integer. For example if testuser123 has 400,000 followers, you may use this parameter to specify how many of those followers to process, e.g. 50000. Other supported values include:

  • all: Fetch all data. This should almost never be used, and it’s likely to be deprecated.
  • most: Fetch more than half of the user’s data. The precise value is determined based on the magnitude of data involved, but guaranteed to be more than half. This is more than necessary in most circumstances.
  • some: This is the default for users with more than (currently) 5,000 followers. The exact count depends again on the magnitude of data, but will always be sufficient for a sample size sufficient to produce a very small margin of error.

In general this parameter should not be used. A value smaller than the default may compromise quality, and a larger value will cause delays and incur billable costs (details TBD).

Twitter User (/api/twitter_user.json)

Returns details for a given Twitter user. Currently the only supported parameter is user which, as usual, may be a Twitter screen_name or id.

Sample Output

<pre>{ "twitter_user":{ "created_at":"2012-06-01T00:26:33Z", "statuses_count":13799, "followers_count":2452, "screen_name":"bradleyjoyce", "ready":false, "id":14150637, "utc_offset":-8, "stored_tweets":2788 } }</pre>

"ready":false conveys the fact that this user’s data has not yet been fetched, or that it is more than 7 days old. We can return results for him but they may not be fully optimized. Once the user has been added to your app via the add_twitter_user API call, his data will be fetched and kept up to date.

Please sign in to comment on this gist.

Something went wrong with that request. Please try again.