Introduction to SWIX’s REST Api

SWIX’s API allows you to access our system programmatically. Before you can acces the SWIX api you must first obtain an API key from us.

Query String

Format
Purpose: Allows you to specify the format the data is returned in.
Available Values: XML, JSON

You may use the format parameter in all of your calls to the API.

For JSON formatting:

http://swixapp.com/api/v1/brand/?format=json

For XML formatting:

http://swixapp.com/api/v1/brand/?format=xml

API Key
Purpose: Allows you to authenticate.

For the read only API we are using API Key authentication. API Key authentication requires you to provide your API Key and User Name in the query string.

For example:

http://swixapp.com/api/v1/brand/?format=json&username=fakeusername&api_key=fakeapikey

Status Codes

In all of the resource below we return status codes to indicate to you the outcome of your request. The general meaning of those status codes are as follows:

Status Code 200 - The resource you specified exists, we successfully retrieved the resource and have returned the results to you.

Status Code 401 - You do not have access or authorization to access the resource you are requesting.

Status Code 404 - The url does not exists. You would get this error if you mistyped ‘api/v1/brand/’ as ‘api/v1/barnd/’

Status Code 410 - You have requested a resource that does not exist. For instance, you are trying to retrieve /api/v1/brand/5987487 and brand with the id of 5987487 does not exist.

Status Code 500 - Something went wrong on our end and we were not able to get the resource you requested.

Account Resources

GET /api/v1/account/
Required Parameters: api_key, username
Optional Parameters: format
Response: Account Details

returns - All the details assocaited with an account.

Fields
analytics_css - The url to the custom CSS used for Swix Analytics, if one is used and if the account has white labeling. Prefix with ‘swixapp.com’.
analytics_domain - The domain used for Swix Analyticss, if one is used and if the account has white labeling.
marketing_css - The url to the custom CSS used for Campaign Manager, if one is used and if the account has white labeling. Prefix with ‘swixapp.com’.
marketing_domain - The domain used for Campaign Manager, if one is used and if the account has white labeling.
shortener_domain - The domain used for the URL shortener, if one is used, and if the account has white labeling.
facebook_iframe - Use this URL in an iframe to create a Facebook oauth token for swix for this account.
linkedin_iframe - Use this URL in an iframe to create a Linkedin oauth token for swix for this account.
oauthtokens - The end point to view the full list of oauth tokens created for this account.
userprofiles - The end point to view the user profiles assocaited with this account.
owner - An object describing the owner of the account.
owner/email - The e-mail address tied to the account.
owner/first_name - The first name of the account owner.
owner/last_name - The last name of the account owner.
owner/username - The user for the account.
owner/date_joined - The date the account was created.
owner/last_login - The date the account was last logged into.

Example:
/api/v1/account/?format=json&username=your_username&api_key=your_apikey

Brand Resources

GET /api/v1/brand/
Required Parameters: api_key, username
Optional Parameters: format
Response: List of Brands

returns - All the brands associated with your account. From here you will be able to get the necessary id’s required to use the API calls listed below. Including brand id, event id, and pod id.

Example:
/api/v1/brand/?format=json&username=your_username&api_key=your_apikey

GET /api/v1/brand/{brand_id}/
Required Parameters: api_key, username
Optional Parameters: format
Response: A Brand

returns - The brand associated with the brand id provided.

Fields

account - The URI to the account that the brand belongs to.
name - The name of the brand.
created_at - The date and time the band was created at, in the format of iso-8601 (2011-05-24T13:14:57).
id - The id of the brand.
logo - path to your logo.
CSS - path to your CSS.
event - List of events that belong to the brand
events - URL to the Event Resource which lists the events that belong to the brand
pod - List of pods that belong to the brand
pods - URL to the Pod Resource which lists the pods that belong to the brand
offers - URL to the Offer Resource which lists the offers that belong to the brand

Event Resource

GET /api/v1/brand/{brand_id}/event/
Required Parameters: api_key, username
Optional Parameters: format
Response: List of Events

returns - The events that are associated with the specified band id.

GET /api/v1/brand/{brand_id}/event/{event_id}/
Required Parameters: api_key, username
Optional Parameters: format
Response: An Event

returns - The specific event that is specified by the event id.

Fields

name - Name of the event.
deleted - Flag that indicates whether the event is deleted.
created_at - Date the event was created.
id - The id of the Event.
brand - The brand the event belongs to.
brand - URL to the brand which owns the event.
date - The date of the event.

Offer Resource

GET /api/v1/brand/{brand_id}/offer/
Required Parameters: api_key, username
Optional Parameters: format
Response: List of Offers

returns - The offers which are assocaited with the specified offer id.

GET /api/v1/brand/{brand_id}/offer/{offer_id}/
Required Parameters: api_key, username
Optional Parameters: format
Response: An Offer

returns - The offer which is specified by the offer_id parameter.

Fields

landing_page - The page the offer is on. The short url will point to this URL.
conversion - URL to the Conversion Resource which lists the conversions by date.
name - Name of the Offer.
end_date - The date the offer is scheduled to end.
roi - The calculated return on investment. ‘N/A’ if this field does not apply.
short_url - The short URL which will redirect a user to the landing page.
brand - The URL to the Brand Resource which this offer belongs to.
updated_at - When the resource was last updated.
start_date - The start date of the offer.
total_revenue - Total revenue this campaign has given you.
conversions - The total number of conversions this offer has given you.
default_value_in_cents - The default value of each sale, in cents.
activity_name - The name of the activity.
initial_cost_in_cents - The upfront consts of the offer.
click_data - URL to the Click Data Resource.
created_at - Date the offer was created.
offer_transactions - URL to the Offer Transaction Resource.
type - Type of offer, Either ‘Sales’ or ‘Activity’.
id - ID of the offer.
revenue_by_day - URL to the Revenue By Day Resource.

Offer Transaction Resource

GET /api/v1/brand/{brand_id}/offer/{offer_id}/offertransaction/
Required Parameters: api_key, username
Optional Parameters: format
Response: List of Offer Transactions

returns - A list of Offer Transactions that belong to the given offer id.

GET /api/v1/brand/{brand_id}/offer/{offer_id}/offertransaction/{offertransaction_id}/
Required Parameters: api_key, username
Optional Parameters: format
Response: An Offer Transaction

returns - The Offer Transaction specified by the offertransaction_id parameter.

Fields

referrer - Where the sale came from. (i.e Twitter, Facebook, ect.)
created_at - When the transaction took place.
offer - URL to the offer the transaction belongs to.
id - ID of the transaction.
amount_in_cents - Transaction amount in cents.

Click Data Resource

GET /api/v1/brand/{brand_id}/offer/{offer_id}/clickdata/
Required Parameters: api_key, username
Optional Parameters: format, graph, startdate, enddate
Response: Click data.

returns - A compiled list of the click data, from various reffers.

Fields

clicks - Number of clicks. measured_at - The date the clicks happened on.

Revenue By Day Resource

GET /api/v1/brand/{brand_id}/offer/{offer_id}/revenuebyday/
Required Parameters: api_key, username
Optional Parameters: format, graph, startdate, enddate
Response: A compiled list of the total revenue by day.

returns - A compiled list of revenue earned, by day for the given offer.

Fields

sales - Amount of sales in dollars. measured_at - The date for the sales.

Pod Resource

GET /api/v1/brand/{brand_id}/pod/
Required Parameters: api_key, username
Optional Parameters: format
Response: List of Pods

returns - The pods which are associated with the specified brand id.

Example:
/api/v1/brand/55/pod/?format=json&username=your_username&api_key=your_apikey

GET /api/v1/brand/{brand_id}/pod/{pod_id}/
Required Parameters: api_key, username
Optional Parameters: format
Response: A Pod

returns - The specific pod specified by the pod id parameter.

Fields

name - Pod name
created_at - Date pod was created.
uri - URL to the resource this pod uses.
updated_at - Date pod was updated
id - The id of the pod.
active - Flag that tells you if this pod is active.
type - This will indicate what type of pod this is. This will tell you which format seriesdata will be in.
brand - The brand this pod belongs to.
brand - URL to the brand which owns the event.
seriesdata - the URL to the series data for this pod

Series Data Resource

GET /api/v1/brand/{brand_id}/pod/{pod_id}/seriesdata/
Required Parameters: api_key, username
Optional Parameters: format, graph, startdate, enddate
Response: Series data for a given pod

returns - The series data that we have collected for that pod in the last 90 days. See the additional parameter below to see more options (like getting more than 90 days worth of data).

The data in the series data is pretty much a count, for that metric, on the day of measured_at. If you wish to know the exact time the metric was taken, you can use updated_at.

Fields
twitter

id - Series Data ID.
measured_at - Date measured at. Appears in the format YYYY-MM-DD”T”HH:MM:SS. Example: 2011-04-08T13:50:28
updated_at - Date and Time the data was updated at. Appears in the format YYYY-MM-DD”T”HH:MM:SS. Example: 2011-04-12T13:50:28
followers - Count of twitter followers.
listed - Count of places you are listed
friends - Count of friends.
statuses - Count of statuses.

Example:
This example gives you an idea of what to expect from twitter series data. However, all the others will be pretty much the same but with different field names.
Also, please note there are more examples below that demonstrate the use the optional query string parameters. /api/v1/brand/55/pod/1/seriesdata/?format=json&username=your_username&api_key=your_apikey

facebook

id - Series Data ID.
measured_at - Date measured at. Appears in the format YYYY-MM-DD”T”HH:MM:SS. Example: 2011-04-08T13:50:28
updated_at - Date and Time the data was updated at. Appears in the format YYYY-MM-DD”T”HH:MM:SS. Example: 2011-04-12T13:50:28
friends - Count of facebook friends.
wallposts - Count of wallposts.

Blog

id - Series Data ID.
measured_at - Date measured at. Appears in the format YYYY-MM-DD”T”HH:MM:SS. Example: 2011-04-08T13:50:28
updated_at - Date and Time the data was updated at. Appears in the format YYYY-MM-DD”T”HH:MM:SS. Example: 2011-04-12T13:50:28
subscribers - Count of subscribers to your blog.
reach - You total reach.
hits - Number of hits.

Google Analytics

id - Series Data ID.
measured_at - Date measured at. Appears in the format YYYY-MM-DD”T”HH:MM:SS. Example: 2011-04-08T13:50:28
updated_at - Date and Time the data was updated at. Appears in the format YYYY-MM-DD”T”HH:MM:SS. Example: 2011-04-12T13:50:28
newvisits - Total number of new visits.
visits - Total number of visits
pageviews - Total number of page views.
uniquepageviews - Total number of unique page views.

Youtube Channel

id - Series Data ID.
measured_at - Date measured at. Appears in the format YYYY-MM-DD”T”HH:MM:SS. Example: 2011-04-08T13:50:28
updated_at - Date and Time the data was updated at. Appears in the format YYYY-MM-DD”T”HH:MM:SS. Example: 2011-04-12T13:50:28
subscribers - Total number of subscribers.
views - Total number of views.

Youtube Video

id - Series Data ID.
measured_at - Date measured at. Appears in the format YYYY-MM-DD”T”HH:MM:SS. Example: 2011-04-08T13:50:28
updated_at - Date and Time the data was updated at. Appears in the format YYYY-MM-DD”T”HH:MM:SS. Example: 2011-04-12T13:50:28
views - Total number of views on your youtube video.
favorited - Total number of times your video was favorited.

Facebook Group

id - Series Data ID.
measured_at - Date measured at. Appears in the format YYYY-MM-DD”T”HH:MM:SS. Example: 2011-04-08T13:50:28
updated_at - Date and Time the data was updated at. Appears in the format YYYY-MM-DD”T”HH:MM:SS. Example: 2011-04-12T13:50:28
members - Number of members in your facebook group.

Facebook App

id - Series Data ID.
measured_at - Date measured at. Appears in the format YYYY-MM-DD”T”HH:MM:SS. Example: 2011-04-08T13:50:28
updated_at - Date and Time the data was updated at. Appears in the format YYYY-MM-DD”T”HH:MM:SS. Example: 2011-04-12T13:50:28
monthly_active_users - Total number of active monthly users for your app.
weekly_active_users - Total number of active weekly users for your app.
daily_active_users - Total number of active daily users for your app.

Facebook Page

id - Series Data ID.
measured_at - Date measured at. Appears in the format YYYY-MM-DD”T”HH:MM:SS. Example: 2011-04-08T13:50:28
updated_at - Date and Time the data was updated at. Appears in the format YYYY-MM-DD”T”HH:MM:SS. Example: 2011-04-12T13:50:28
fans - Total number of facebook fans.

Flickr User

id - Series Data ID.
measured_at - Date measured at. Appears in the format YYYY-MM-DD”T”HH:MM:SS. Example: 2011-04-08T13:50:28
updated_at - Date and Time the data was updated at. Appears in the format YYYY-MM-DD”T”HH:MM:SS. Example: 2011-04-12T13:50:28
photos - Number of photos.
groups - Number of groups.
contacts - Number of contacts.

Flickr Group

id - Series Data ID.
measured_at - Date measured at. Appears in the format YYYY-MM-DD”T”HH:MM:SS. Example: 2011-04-08T13:50:28
updated_at - Date and Time the data was updated at. Appears in the format YYYY-MM-DD”T”HH:MM:SS. Example: 2011-04-12T13:50:28
members -

Flickr Set

id - Series Data ID.
measured_at - Date measured at. Appears in the format YYYY-MM-DD”T”HH:MM:SS. Example: 2011-04-08T13:50:28
updated_at - Date and Time the data was updated at. Appears in the format YYYY-MM-DD”T”HH:MM:SS. Example: 2011-04-12T13:50:28
comments - Number of comments.

Identica Profile

id - Series Data ID.
measured_at - Date measured at. Appears in the format YYYY-MM-DD”T”HH:MM:SS. Example: 2011-04-08T13:50:28
updated_at - Date and Time the data was updated at. Appears in the format YYYY-MM-DD”T”HH:MM:SS. Example: 2011-04-12T13:50:28
followers - Number of followers.
friends - Number of friends.
statuses - Number of statuses.

Linkedin Profiles

id - Series Data ID.
measured_at - Date measured at. Appears in the format YYYY-MM-DD”T”HH:MM:SS. Example: 2011-04-08T13:50:28
updated_at - Date and Time the data was updated at. Appears in the format YYYY-MM-DD”T”HH:MM:SS. Example: 2011-04-12T13:50:28
connections - Total number of connections.
recommendations - Total number of recommendations.

Delicious Url

id - Series Data ID.
measured_at - Date measured at. Appears in the format YYYY-MM-DD”T”HH:MM:SS. Example: 2011-04-08T13:50:28
updated_at - Date and Time the data was updated at. Appears in the format YYYY-MM-DD”T”HH:MM:SS. Example: 2011-04-12T13:50:28
bookmark - Number of bookmarks

Stumbleupon Url

id - Series Data ID.
measured_at - Date measured at. Appears in the format YYYY-MM-DD”T”HH:MM:SS. Example: 2011-04-08T13:50:28
updated_at - Date and Time the data was updated at. Appears in the format YYYY-MM-DD”T”HH:MM:SS. Example: 2011-04-12T13:50:28
reviews - Number of reviews
rating - Number of Ratings

Mybloglog Community

id - Series Data ID.
measured_at - Date measured at. Appears in the format YYYY-MM-DD”T”HH:MM:SS. Example: 2011-04-08T13:50:28
updated_at - Date and Time the data was updated at. Appears in the format YYYY-MM-DD”T”HH:MM:SS. Example: 2011-04-12T13:50:28
members - Number of members.

Upcoming Event

id - Series Data ID.
measured_at - Date measured at. Appears in the format YYYY-MM-DD”T”HH:MM:SS. Example: 2011-04-08T13:50:28
updated_at - Date and Time the data was updated at. Appears in the format YYYY-MM-DD”T”HH:MM:SS. Example: 2011-04-12T13:50:28
attending -
interested -

Metacafe Channel

id - Series Data ID.
measured_at - Date measured at. Appears in the format YYYY-MM-DD”T”HH:MM:SS. Example: 2011-04-08T13:50:28
updated_at - Date and Time the data was updated at. Appears in the format YYYY-MM-DD”T”HH:MM:SS. Example: 2011-04-12T13:50:28
views -
rank -
subscribers -
videos -

Metacafe Video

id - Series Data ID.
measured_at - Date measured at. Appears in the format YYYY-MM-DD”T”HH:MM:SS. Example: 2011-04-08T13:50:28
updated_at - Date and Time the data was updated at. Appears in the format YYYY-MM-DD”T”HH:MM:SS. Example: 2011-04-12T13:50:28
views - Number of views.
rank - Total rank.
comments - Number of comments.

Meetup Group

id - Series Data ID.
measured_at - Date measured at. Appears in the format YYYY-MM-DD”T”HH:MM:SS. Example: 2011-04-08T13:50:28
updated_at - Date and Time the data was updated at. Appears in the format YYYY-MM-DD”T”HH:MM:SS. Example: 2011-04-12T13:50:28
members - Number of members.
events - Number of events.
rating - Total rating.

Meetup Event

id - Series Data ID.
measured_at - Date measured at. Appears in the format YYYY-MM-DD”T”HH:MM:SS. Example: 2011-04-08T13:50:28
updated_at - Date and Time the data was updated at. Appears in the format YYYY-MM-DD”T”HH:MM:SS. Example: 2011-04-12T13:50:28
rsvp - Number of RSVP.

Myspace Profile

id - Series Data ID.
measured_at - Date measured at. Appears in the format YYYY-MM-DD”T”HH:MM:SS. Example: 2011-04-08T13:50:28
updated_at - Date and Time the data was updated at. Appears in the format YYYY-MM-DD”T”HH:MM:SS. Example: 2011-04-12T13:50:28
friends - Number of friends.
comments - Number of comments.

Vimeo Video

id - Series Data ID.
measured_at - Date measured at. Appears in the format YYYY-MM-DD”T”HH:MM:SS. Example: 2011-04-08T13:50:28
updated_at - Date and Time the data was updated at. Appears in the format YYYY-MM-DD”T”HH:MM:SS. Example: 2011-04-12T13:50:28
plays - Number of times a video is played.
comments - Number of comments.
rating - Total rating.

Vimeo Channel

id - Series Data ID.
measured_at - Date measured at. Appears in the format YYYY-MM-DD”T”HH:MM:SS. Example: 2011-04-08T13:50:28
updated_at - Date and Time the data was updated at. Appears in the format YYYY-MM-DD”T”HH:MM:SS. Example: 2011-04-12T13:50:28
subscribers - Total number of subscribers.
videos - Total videos.

Vimeo Group

id - Series Data ID.
measured_at - Date measured at. Appears in the format YYYY-MM-DD”T”HH:MM:SS. Example: 2011-04-08T13:50:28
updated_at - Date and Time the data was updated at. Appears in the format YYYY-MM-DD”T”HH:MM:SS. Example: 2011-04-12T13:50:28
members - Number of members.
videos - Number of videos.
topics - Number of topics.
events - Number of events.

Digg Url

id - Series Data ID.
measured_at - Date measured at. Appears in the format YYYY-MM-DD”T”HH:MM:SS. Example: 2011-04-08T13:50:28
updated_at - Date and Time the data was updated at. Appears in the format YYYY-MM-DD”T”HH:MM:SS. Example: 2011-04-12T13:50:28
diggs - Number of diggs.
stories - Number of stories.
comments - Number of comments.

Additional Parameters

graph
Available Values: highcharts

This parameter allows you to specify a special format for graphing libraries. At this point in time we only support Highcharts. Highcharts is a javascript library that creates awesome graphs, and with our javascript library it’s super easy.

For more information checkout Highchart’s website http://www.highcharts.com/.

Notes about the format: We return the JSON that you would assign to the “data” portion of the graph options. In the data field, we have a list of values, Date, Count. The date field is stored in epoch format, the second field is the metric specified in the “name” fields.

fields

Use this query string parameter to specify the metrics you would like to retrieve. You specify the fields using a comma separated list. For instance, if you wanted only the number of followers on twitter you would do “fields=followers”. Or perhaps you want followers and friends. To do so you would do “fields=followers,friends”. If you specify fields that don’t exist in the seriesdata you requested, you will receive an empty reply.

startdate

This query string parameter allows you to specify the start date for the date range used to retrieve the seriesdata. The format of the date needs to be YYYY-MM-DD.

enddate

This query string parameter allows you to specify the end date for the date range used to retrieve the seriesdata. The format of the date needs to be YYYY-MM-DD.

Putting it together

Lets say we want to graph the number of followers we have, from the seriesdata that belongs to pod 1 for the month of May. We would use the following url: